Setup

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

AI Integration Quick Reference

npm install @cometchat/chat-sdk-react-native @react-native-async-storage/async-storage

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

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:

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

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.

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.

Installation

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

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

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

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:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven {
            url = uri(project(":react-native-async-storage_async-storage").file("local_repo"))
        }
    }
}

Voice & Video Calling (Optional)

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

npm install @cometchat/calls-sdk-react-native

Required additional dependencies for calling:

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

Android

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

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

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:

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

iOS

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

Update the minimum platform version in your Podfile:

platform :ios, '11.0'

Then run pod install in the ios directory.

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.

TypeScript

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

JavaScript

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:

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

Replace APP_ID and APP_REGION with your credentials from the Dashboard.

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

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):

// 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 for more details.

WebSocket Connection

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

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

See Managing WebSocket Connections for manual control.

---

Next Steps

Authentication

Log in users with Auth Key or Auth Token

Send Messages

Send your first message