> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install, configure, initialize, and log in users with the CometChat React Native SDK using app settings and auth keys.

<Accordion title="AI Integration Quick Reference">
  ```bash theme={null}
  npm install @cometchat/chat-sdk-react-native @react-native-async-storage/async-storage
  ```

  ```typescript theme={null}
  import { CometChat } from "@cometchat/chat-sdk-react-native";

  const appSettings: CometChat.AppSettings = new CometChat.AppSettingsBuilder()
    .setRegion("APP_REGION")
    .subscribePresenceForAllUsers()
    .autoEstablishSocketConnection(true)
    .build();

  await CometChat.init("APP_ID", appSettings);
  await CometChat.login("UID", "AUTH_KEY"); // dev only
  ```

  **Prerequisites:** npm 8+, Node.js 16+, React Native 0.63+, credentials from [CometChat Dashboard](https://app.cometchat.com)
</Accordion>

## Prerequisites

| Requirement           | Version       |
| --------------------- | ------------- |
| npm                   | 8.x or above  |
| Node.js               | 16 or above   |
| React Native          | 0.63 or above |
| Android minSdkVersion | 24            |
| iOS                   | 11.0          |

Get your credentials from the [CometChat Dashboard](https://app.cometchat.com):

* App ID
* Region
* Auth Key (for development)

<Warning>
  **Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API. Never expose Auth Keys in production client code.
</Warning>

<Note>
  **Migrating from v3 to v4?** Your existing v3 app can be migrated directly — no need to create a new app. Follow the installation steps below to upgrade to the latest version of v4.
</Note>

## Installation

```bash theme={null}
npm install @cometchat/chat-sdk-react-native
```

The React Native SDK requires `async-storage` as a peer dependency:

```bash theme={null}
npm install @react-native-async-storage/async-storage
```

<Warning>
  **Android only:** `@react-native-async-storage/async-storage` v3 ships a local Maven artifact. Add this to your `android/build.gradle` or the Android build will fail:

  ```gradle theme={null}
  allprojects {
      repositories {
          google()
          mavenCentral()
          maven {
              url = uri(project(":react-native-async-storage_async-storage").file("local_repo"))
          }
      }
  }
  ```
</Warning>

### Voice & Video Calling (Optional)

v2.4+ onwards, calling functionality lives in a separate package. Install it only if you need voice/video:

```bash theme={null}
npm install @cometchat/calls-sdk-react-native
```

Required additional dependencies for calling:

```json theme={null}
{
  "@react-native-community/netinfo": "^11.3.1",
  "react-native-background-timer": "^2.4.1",
  "react-native-callstats": "^3.73.7",
  "react-native-webrtc": "^1.106.1"
}
```

<Tabs>
  <Tab title="Android">
    Add permissions to your `AndroidManifest.xml`:

    ```xml theme={null}
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    ```

    Add the CometChat Maven repository to your project-level `build.gradle`:

    ```gradle theme={null}
    allprojects {
      repositories {
        maven {
          url "https://dl.cloudsmith.io/public/cometchat/cometchat-pro-android/maven/"
        }
      }
    }
    ```

    Ensure `minSdkVersion` is set to **24** in the `buildscript` ext block:

    ```gradle theme={null}
    buildscript {
      ext {
        buildToolsVersion = "29.0.2"
        minSdkVersion = 24
        compileSdkVersion = 29
        targetSdkVersion = 29
      }
    }
    ```
  </Tab>

  <Tab title="iOS">
    Add keys to your `Info.plist`:

    ```xml theme={null}
    <key>NSCameraUsageDescription</key>
    <string>This is for Camera permission</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>This is for Mic permission</string>
    ```

    Update the minimum platform version in your Podfile:

    ```ruby theme={null}
    platform :ios, '11.0'
    ```

    Then run `pod install` in the `ios` directory.
  </Tab>
</Tabs>

## Initialization

The `init()` method initializes the SDK and must be called before any other CometChat method. Call it once at app startup, typically in `App.tsx`.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    let appID: string = "APP_ID";
    let region: string = "APP_REGION";

    let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    CometChat.init(appID, appSetting).then(
      (initialized: boolean) => {
        console.log("Initialization completed successfully", initialized);
      },
      (error: CometChat.CometChatException) => {
        console.log("Initialization failed with error:", error);
      }
    );
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    let appID = "APP_ID";
    let region = "APP_REGION";

    let appSetting = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    CometChat.init(appID, appSetting).then(
      () => {
        console.log("Initialization completed successfully");
      },
      (error) => {
        console.log("Initialization failed with error:", error);
      }
    );
    ```

    Alternatively, you can use the `async/await` syntax:

    ```javascript theme={null}
    let appID = "APP_ID";
    let region = "APP_REGION";

    let appSetting = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    try {
      await CometChat.init(appID, appSetting);
      console.log("Initialization completed successfully");
    } catch (error) {
      console.log("Initialization failed with error:", error);
    }
    ```
  </Tab>
</Tabs>

Replace `APP_ID` and `APP_REGION` with your credentials from the [Dashboard](https://app.cometchat.com).

<Warning>
  `CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail.
</Warning>

### Parameters

| Parameter  | Type        | Description                                        |
| ---------- | ----------- | -------------------------------------------------- |
| appID      | string      | Your CometChat App ID                              |
| appSetting | AppSettings | Configuration object built with AppSettingsBuilder |

### AppSettings Options

| Method                                | Description                                          | Default  |
| ------------------------------------- | ---------------------------------------------------- | -------- |
| `setRegion(region)`                   | Region where your app was created (`us`, `eu`, `in`) | Required |
| `subscribePresenceForAllUsers()`      | Subscribe to presence events for all users           | —        |
| `subscribePresenceForRoles(roles)`    | Subscribe to presence for specific roles             | —        |
| `subscribePresenceForFriends()`       | Subscribe to presence for friends only               | —        |
| `autoEstablishSocketConnection(bool)` | Let SDK manage WebSocket connections                 | `true`   |
| `overrideAdminHost(adminHost)`        | Custom admin URL (dedicated deployment)              | —        |
| `overrideClientHost(clientHost)`      | Custom client URL (dedicated deployment)             | —        |

### Presence Subscription

Choose how to subscribe to user presence (online/offline status):

```javascript theme={null}
// All users
new CometChat.AppSettingsBuilder()
  .subscribePresenceForAllUsers()
  .setRegion(region)
  .build();

// Specific roles
new CometChat.AppSettingsBuilder()
  .subscribePresenceForRoles(["admin", "moderator"])
  .setRegion(region)
  .build();

// Friends only
new CometChat.AppSettingsBuilder()
  .subscribePresenceForFriends()
  .setRegion(region)
  .build();
```

See [User Presence](/sdk/react-native/user-presence) for more details.

### WebSocket Connection

By default, the SDK manages WebSocket connections automatically. To manage them manually:

```javascript theme={null}
let appSetting = new CometChat.AppSettingsBuilder()
  .setRegion(region)
  .autoEstablishSocketConnection(false)
  .build();
```

See [Managing WebSocket Connections](/sdk/react-native/managing-web-sockets-connections-manually) for manual control.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/sdk/react-native/authentication-overview">
    Log in users with Auth Key or Auth Token
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/react-native/send-message">
    Send your first message
  </Card>
</CardGroup>