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

# Setup

> Install the CometChat React Native SDK, configure dependencies and permissions, and initialize CometChat in your application.

<Info>
  **Quick Reference** - Install and initialize in three steps:

  ```javascript theme={null}
  // 1. Install dependencies
  // npm i @cometchat/chat-sdk-react-native @react-native-async-storage/async-storage

  // 2. Initialize CometChat (call once on app startup)
  const appSetting = new CometChat.AppSettingsBuilder()
    .subscribePresenceForAllUsers()
    .setRegion("REGION")
    .autoEstablishSocketConnection(true)
    .build();
  await CometChat.init("APP_ID", appSetting);
  ```
</Info>

<Note>
  **Migrating from v3 to v4?**

  Skip the create new app step. Your existing v3 app can be migrated to v4.

  Follow the steps mentioned in the [Add the CometChat Dependency](#add-the-cometchat-dependency) section below to upgrade to the latest version of v4.
</Note>

## Get your Application Keys

[Signup for CometChat](https://app.cometchat.com) and then:

1. Create a new app
2. Head over to the **API & Auth Keys** section and note the **Auth Key**, **App ID** & **Region**

## Add the CometChat Dependency

Install the package as an NPM module:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm i @cometchat/chat-sdk-react-native
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @cometchat/chat-sdk-react-native
    ```
  </Tab>
</Tabs>

In order to integrate the CometChat React Native SDK, you need to install one more dependency.

### Async-Storage

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @react-native-async-storage/async-storage
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @react-native-async-storage/async-storage
    ```
  </Tab>
</Tabs>

<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.
</Warning>

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

## Calling Component Configuration

For `@cometchat/calls-sdk-react-native`, please make sure you add the following additional dependencies & permissions.

### Required Dependencies

```json theme={null}
{
  "@cometchat/chat-sdk-react-native": "^4.0.18",
  "@react-native-async-storage/async-storage": "^1.23.1",
  "@react-native-community/netinfo": "^11.3.1", // for react-native 0.63 & above
  "@react-native-community/netinfo": "6.1.0",   // for react-native below 0.63
  "react-native-background-timer": "^2.4.1",
  "react-native-callstats": "^3.73.7",
  "react-native-webrtc": "^1.106.1"
}
```

### Permissions

<Tabs>
  <Tab title="Android">
    Add the following 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" />
    ```
  </Tab>

  <Tab title="iOS">
    Add the following 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>
    ```
  </Tab>
</Tabs>

### Platform-Specific Configuration

<AccordionGroup>
  <Accordion title="Android Configuration">
    Go to the `./android` folder and open the **project level** `build.gradle` file. Add all repository URLs in the `repositories` block under the `allprojects` section.

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

    Also in the same file, in the `buildscript` section in the `ext` block, make sure you have set **minSdkVersion** to **24**.

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

  <Accordion title="iOS Configuration">
    Please update the minimum target version in the Podfile. Go to the `./ios` folder and open the Podfile. In the Podfile, update the platform version to `11.0`:

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

    Open the `ios/App` folder and run `pod install`. This will create an `App.xcworkspace` file. Open this and run the app.
  </Accordion>
</AccordionGroup>

## Initialize CometChat

The `init()` method initializes the settings required for CometChat. The `init()` method takes the below parameters:

| Parameter     | Description                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------- |
| `appID`       | Your CometChat App ID                                                                                       |
| `appSettings` | An object of the `AppSettings` class created using the `AppSettingsBuilder` class. The region is mandatory. |

The `AppSettings` class allows you to configure the following settings:

| Setting                                    | Description                                                                                                                                                                                                                                                     |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Region**                                 | The region where your app was created (mandatory). Set using `setRegion()`                                                                                                                                                                                      |
| **Presence Subscription**                  | Represents the subscription type for user presence (real-time online/offline status). See [User Presence](/sdk/react-native/user-presence)                                                                                                                      |
| **autoEstablishSocketConnection(boolean)** | When set to `true`, the SDK manages the web-socket connection internally. When set to `false`, you manage the connection manually. Default: `true`. See [Managing Web-Socket connections manually](/sdk/react-native/managing-web-sockets-connections-manually) |
| **overrideAdminHost(adminHost: string)**   | Uses a custom admin URL instead of the default. Used for dedicated CometChat deployments                                                                                                                                                                        |
| **overrideClientHost(clientHost: string)** | Uses a custom client URL instead of the default. Used for dedicated CometChat deployments                                                                                                                                                                       |

You need to call `init()` before calling any other method from CometChat. We suggest you call the `init()` method on app startup, preferably in the `App.tsx` file.

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

    // Build app settings with presence subscription and auto socket connection
    let appSetting = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    // Initialize CometChat — call once on app startup
    CometChat.init(appID, appSetting).then(
      () => {
        console.log("Initialization completed successfully");
      },
      (error) => {
        console.log("Initialization failed with error:", error);
      }
    );
    ```
  </Tab>

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

    // Build app settings with presence subscription and auto socket connection
    let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(region)
      .autoEstablishSocketConnection(true)
      .build();

    // Initialize CometChat — call once on app startup
    CometChat.init(appID, appSetting).then(
      (initialized: boolean) => {
        console.log("Initialization completed successfully", initialized);
      },
      (error: CometChat.CometChatException) => {
        console.log("Initialization failed with error:", error);
      }
    );
    ```
  </Tab>
</Tabs>

<Warning>
  Make sure you replace the `APP_ID` with your CometChat **App ID** and `REGION` with your **App Region** in the above code.
</Warning>

<Accordion title="Response">
  **On Success** — `init()` returns `true` and logs:

  ```
  Initialization completed successfully
  ```

  **On Failure** — Returns a CometChatException object:

  | Parameter | Type   | Description              | Sample Value                                                                                  |
  | --------- | ------ | ------------------------ | --------------------------------------------------------------------------------------------- |
  | `code`    | string | Error code               | `"ERR_INVALID_APP_ID"`                                                                        |
  | `name`    | string | Error name               | `"Invalid App ID"`                                                                            |
  | `message` | string | Error description        | `"The App ID provided is incorrect. Please verify your App ID from the CometChat Dashboard."` |
  | `details` | object | Additional error details | `{}`                                                                                          |
</Accordion>

<AccordionGroup>
  <Accordion title="Best Practices">
    * Always call `init()` before any other CometChat method
    * Call `init()` on app startup, preferably in `App.tsx`
    * Use `autoEstablishSocketConnection(true)` unless you have a specific need to manage connections manually
    * For dedicated deployments, use `overrideAdminHost` and `overrideClientHost` to point to your custom URLs
  </Accordion>

  <Accordion title="Troubleshooting">
    * **Initialization fails:** Verify your App ID and Region are correct
    * **Network errors:** Check internet connectivity and firewall settings
    * **Calling not working:** Verify all calling dependencies are installed and permissions are granted
    * **iOS build fails:** Run `pod install` in the `ios` directory after adding dependencies
    * **Android build fails:** Ensure `minSdkVersion` is set to 24 and the CometChat Maven repository is added
  </Accordion>
</AccordionGroup>

## Next Steps

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

  <Card title="Key Concepts" icon="book" href="/sdk/react-native/key-concepts">
    Understand the fundamental building blocks of CometChat
  </Card>

  <Card title="Send Messages" icon="paper-plane" href="/sdk/react-native/messaging">
    Start sending text, media, and custom messages
  </Card>

  <Card title="UI Kit Integration" icon="palette" href="/ui-kit/react-native/overview">
    Add pre-built UI components to your app
  </Card>
</CardGroup>