Setup

Migrating app version from v3 to v4 ?

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

Follow steps mentioned in Add the CometChat dependency section below to upgrade to 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

NPM

JavaScript

npm install @cometchat/chat-sdk-javascript

Then import wherever needed:

import { CometChat } from "@cometchat/chat-sdk-javascript";

CDN

<script
  type="text/javascript"
  src="https://unpkg.com/@cometchat/chat-sdk-javascript/CometChat.js"
></script>

When using the CDN, CometChat is available as a global variable.

Initialization

The init() method initializes the SDK and must be called before any other CometChat method. Call it once at app startup, typically in your entry file (index.js, main.js, or App.js).

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)	—
setStorageMode(storageMode)	Local storage mode (CometChat.StorageMode.SESSION for session storage)	—

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.

Session Storage

Use session storage instead of local storage (data clears when browser closes):

let appSetting = new CometChat.AppSettingsBuilder()
  .setRegion(region)
  .setStorageMode(CometChat.StorageMode.SESSION)
  .build();

SSR Compatibility

The CometChat SDK requires browser APIs (window, WebSocket) and cannot run on the server. For SSR frameworks, initialize the SDK only on the client side.

Next.js

Import the SDK dynamically in useEffect:

import React from "react";

export default function Home() {
  let [ready, setReady] = React.useState(false);

  React.useEffect(() => {
    window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat;
    setReady(true);
  }, []);

  return ready ? <Chat /> : <p>Loading...</p>;
}

NuxtJS

Import the SDK in the mounted lifecycle hook:

export default {
  data() {
    return { ready: false };
  },
  mounted() {
    window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat;
    this.ready = true;
  }
};

Ionic/Cordova

Use the JavaScript SDK directly. Import and initialize in your root component:

import { CometChat } from "@cometchat/chat-sdk-javascript";

ngOnInit() {
  const appSetting = new CometChat.AppSettingsBuilder()
    .subscribePresenceForAllUsers()
    .setRegion("APP_REGION")
    .autoEstablishSocketConnection(true)
    .build();

  CometChat.init("APP_ID", appSetting).then(
    () => console.log("CometChat initialized successfully"),
    (error) => console.log("CometChat initialization failed:", error)
  );
}

The dedicated Ionic Cordova SDK has been deprecated. For new Ionic/Cordova applications, use the JavaScript SDK as shown above.

---

Next Steps

Authentication

Log in users with Auth Key or Auth Token

Send Messages

Send your first message