Setup

Install, configure, and initialize the CometChat JavaScript SDK in your application using npm or CDN.

Quick Setup Reference

# Install
npm install @cometchat/chat-sdk-javascript

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

// Initialize (run once at app start)
const appSettings = new CometChat.AppSettingsBuilder()
  .subscribePresenceForAllUsers()
  .setRegion("REGION")
  .autoEstablishSocketConnection(true)
  .build();
await CometChat.init("APP_ID", appSettings);

Required: App ID, Region from CometChat Dashboard → API & Auth Keys

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

Package Manager

npm

npm install @cometchat/chat-sdk-javascript

Then, import the CometChat object wherever you want to use CometChat.

JavaScript

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

HTML (via CDN)

Include the CometChat JavaScript library in your HTML code.

HTML

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

Initialize CometChat

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

1. appID - You CometChat App ID
2. appSettings - An object of the AppSettings class can be created using the AppSettingsBuilder class. The region field is mandatory and can be set using the setRegion() method.

The AppSettings class allows you to configure two settings:

• Region: The region where you app was created.
• Presence Subscription: Represents the subscription type for user presence (real-time online/offline status)
• autoEstablishSocketConnection(boolean value): This property takes a boolean value which when set to true informs the SDK to manage the web-socket connection internally. If set to false , it informs the SDK that the web-socket connection will be managed manually. The default value for this parameter is true. For more information on this, please check the Managing Web-Socket connections manually section. The default value for this property is true.
• overrideAdminHost(adminHost: string): This method takes the admin URL as input and uses this admin URL instead of the default admin URL. This can be used in case of dedicated deployment of CometChat.
• overrideClientHost(clientHost: string): This method takes the client URL as input and uses this client URL instead of the default client URL. This can be used in case of dedicated deployment of CometChat.

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 index.js file.

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

TypeScript

let appID: string = "APP_ID",
  region: string = "APP_REGION",
  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);
  }
);

Async/Await

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

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

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

Auth Key is for development/testing only. In production, generate Auth Tokens on your server using the REST API and pass them to the client. Never expose Auth Keys in production client code.

Parameter	Description
appID	CometChat App ID
appSetting	An object of the AppSettings class.

AppSettings Configuration Options

Method	Description	Default
setRegion(region)	The region where your app was created (us, eu, in, in-private)	Required
subscribePresenceForAllUsers()	Subscribe to presence events for all users	—
subscribePresenceForRoles(roles)	Subscribe to presence events for specific roles	—
subscribePresenceForFriends()	Subscribe to presence events for friends only	—
autoEstablishSocketConnection(bool)	Let the SDK manage WebSocket connections internally	true
overrideAdminHost(adminHost)	Use a custom admin URL (dedicated deployment)	—
overrideClientHost(clientHost)	Use a custom client URL (dedicated deployment)	—
setStorageMode(storageMode)	Configure local storage mode (CometChat.StorageMode.SESSION for session storage)	—

Server-Side Rendering (SSR): CometChat SDK requires browser APIs (window, WebSocket). For Next.js, Nuxt, or other SSR frameworks, initialize the SDK only on the client side using dynamic imports or useEffect. See the Overview page for framework-specific examples.

Best Practices

Call init() once at app startup

Call CometChat.init() as early as possible in your application lifecycle — typically in your entry file (index.js, main.js, or App.js). It only needs to be called once per app session.

Check for existing sessions before login

Use CometChat.getLoggedinUser() to check if a user session already exists before calling login(). This avoids unnecessary login calls and improves app startup time.

Use environment variables for credentials

Store your App ID, Region, and Auth Key in environment variables rather than hardcoding them. This makes it easier to switch between development and production environments.

Troubleshooting

init() fails with 'App ID not found'

Verify your App ID is correct and matches the one in your CometChat Dashboard. Ensure you’re using the right region (us, eu, in, or in-private).

SDK methods fail with 'CometChat not initialized'

This means init() was not called or hasn’t completed before other SDK methods were invoked. Ensure init() resolves successfully before calling login(), sendMessage(), or registering listeners.

WebSocket connection issues

If you’re behind a corporate firewall or proxy, WebSocket connections may be blocked. Check your network configuration. You can also manage WebSocket connections manually — see Managing WebSocket Connections.

---

Next Steps

Authentication

Log in users with Auth Key or Auth Token

Send Messages

Send your first text, media, or custom message