Setup

Install, configure, and initialize the CometChat JavaScript SDK in your application.

AI Integration Quick Reference

npm install @cometchat/chat-sdk-javascript

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

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+, credentials from CometChat Dashboard SSR: SDK requires browser APIs — initialize client-side only (useEffect / mounted)

Prerequisites

Requirement	Version
npm	8.x or above
Node.js	16 or above

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.

Installation

Package Manager

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