Setup

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

Quick Reference - Install and initialize in three steps:

// 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);

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 section below to upgrade to the latest version of v4.

Get your Application Keys

Signup for CometChat 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:

npm

npm i @cometchat/chat-sdk-react-native

yarn

yarn add @cometchat/chat-sdk-react-native

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

Async-Storage

npm

npm install @react-native-async-storage/async-storage

yarn

yarn add @react-native-async-storage/async-storage

Calling Component Configuration

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

Required Dependencies

{
  "@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

Android

Add the following permissions to your AndroidManifest.xml:

<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" />

iOS

Add the following keys to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>This is for Camera permission</string>
<key>NSMicrophoneUsageDescription</key>
<string>This is for Mic permission</string>

Platform-Specific Configuration

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.

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.

buildscript {
  ext {
    buildToolsVersion = "29.0.2"
    minSdkVersion = 24
    compileSdkVersion = 29
    targetSdkVersion = 29
  }
}

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:

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.

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

JavaScript

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);
  }
);

TypeScript

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);
  }
);

Make sure you replace the APP_ID with your CometChat App ID and REGION with your App Region in the above code.

Sample Console Output

On Success — console.log("Initialization completed successfully") returns:

Initialization completed successfully

On Failure — console.log("Initialization failed with error:", error) returns:

{
  "code": "ERR_INVALID_APP_ID",
  "name": "Invalid App ID",
  "message": "The App ID provided is incorrect. Please verify your App ID from the CometChat Dashboard.",
  "details": {}
}

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

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

Next Steps

Authentication

Register and log in users with Auth Key or Auth Token

Key Concepts

Understand the fundamental building blocks of CometChat

Send Messages

Start sending text, media, and custom messages

UI Kit Integration

Add pre-built UI components to your app