JavaScript SDK

Add real-time chat and calling to your JavaScript application

Quick Reference for AI Agents & Developers

Package: @cometchat/chat-sdk-javascript
Init: CometChat.init(appID, appSettings)
Login: CometChat.login(uid, authKey) or CometChat.login(authToken)
Send: CometChat.sendMessage(textMessage)
Receive: CometChat.addMessageListener(id, listener)
Logout: CometChat.logout()

Build powerful chat experiences in your web applications using CometChat’s JavaScript SDK. Whether you’re building with React, Angular, Vue, or vanilla JavaScript, this SDK provides the foundation for real-time messaging, voice, and video calling.

Choose Your Integration Path

CometChat offers multiple ways to add chat to your application:

Approach	Best For	Effort
Widget Builder	Quick embed, minimal coding	No Code
UI Kit Builder	Visual customization with code export	Low Code
UI Kits	Pre-built components, full control	Code
SDK (this guide)	Complete flexibility, custom UI	Code
REST API	Server-side integration	Code

Quick Start

Get up and running in 4 steps:

1. Get Your Credentials

   Sign up for CometChat and create a new app. Note your App ID, Region, and Auth Key from the API & Auth Keys section.

2. Install the SDK

   npm

   npm install @cometchat/chat-sdk-javascript
   

   yarn

   yarn add @cometchat/chat-sdk-javascript
   

   CDN

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

   import { CometChat } from "@cometchat/chat-sdk-javascript";
   
   const appID = "YOUR_APP_ID";
   const region = "YOUR_REGION";
   
   const appSetting = new CometChat.AppSettingsBuilder()
     .subscribePresenceForAllUsers()
     .setRegion(region)
     .build();
   
   CometChat.init(appID, appSetting).then(
     () => console.log("CometChat initialized successfully"),
     (error) => console.log("Initialization failed:", error)
   );
   

   CometChat.init() must be called before any other SDK method. Call it once at app startup — calling login(), sendMessage(), or registering listeners before init() will fail.

4. Login a User

   const UID = "cometchat-uid-1";
   const authKey = "YOUR_AUTH_KEY";
   
   CometChat.login(UID, authKey).then(
     (user) => console.log("Login successful:", user),
     (error) => console.log("Login failed:", error)
   );
   

   We provide 5 test users: cometchat-uid-1 through cometchat-uid-5

Using Next.js, Nuxt, or another SSR framework? CometChat requires browser APIs and won’t work during server-side rendering. Use dynamic imports and client-only directives. See the Framework Integration section for complete setup guides for React, Next.js, Vue, Nuxt, and Angular.

What’s Next?

Setup Guide

Detailed configuration options including SSR support for Next.js and Nuxt.

Key Concepts

Understand users, groups, messages, and how CometChat works.

Send Messages

Send text, media, and custom messages to users and groups.

Receive Messages

Handle real-time messages and fetch message history.

---

Core Features

Essential messaging capabilities built into the SDK:

Feature	Description	Learn More
Instant Messaging	Real-time one-on-one and group chat	Send Message
Media Sharing	Share images, videos, documents, and files	Media Messages
Read Receipts	Know when messages are delivered and read	Delivery & Read Receipts
Mark as Unread	Mark messages as unread to revisit later	Mark as Unread
Typing Indicators	Show when users are typing	Typing Indicators
User Presence	Real-time online/offline status	User Presence
Reactions	React to messages with emojis	Reactions
Mentions	@mention users in conversations	Mentions
Threaded Conversations	Create message threads for organized discussions	Threaded Messages
Quoted Replies	Reply to specific messages with context	Quoted Messages
Group Chats	Create and manage group conversations	Groups
Report Message	Allow users to report inappropriate content	Flag Message
Conversation & Advanced Search	Search messages by text, file name, mentions, or mime type	Search Messages

---

Extensions

Enhance your chat with these optional features. Enable them from the CometChat Dashboard under Extensions.

User Experience

Extension	Description
Message Shortcuts	Quick shortcuts for common messages
Avatars	Auto-generated avatars for users
Link Preview	Rich previews for shared URLs
Rich Media Preview	Enhanced previews for media content
Thumbnail Generation	Auto-generate thumbnails for images and videos
Pin Message	Pin important messages in conversations
Save Messages	Save messages for later reference
TinyURL	Shorten long URLs automatically
Bitly	URL shortening via Bitly integration
Voice Transcription	Transcribe voice messages to text

User Engagement

Extension	Description
Giphy	Send animated GIFs
Tenor	Alternative GIF integration
Message Translation	Translate messages in real-time
Polls	Create polls for group decisions
Reminders	Set reminders for messages
Stickers	Send stickers in conversations
Stipop Stickers	Premium sticker packs via Stipop
Emojis	Enhanced emoji support

Collaboration

Extension	Description
Collaborative Document	Create and share documents in real-time
Collaborative Whiteboard	Shared whiteboard for visual collaboration

Security

Extension	Description
Disappearing Messages	Messages that auto-delete after a set time
End-to-End Encryption	Secure message encryption

Customer Support

Extension	Description
Chatwoot	Connect with Chatwoot for support workflows
Intercom	Integrate with Intercom for customer messaging

AI User Copilot

Feature	Description
Conversation Starter	AI-suggested conversation starters
Smart Replies	AI-generated reply suggestions
Conversation Summary	AI-generated summaries of conversations

Learn more about AI User Copilot →

---

Voice & Video Calling

Add real-time calling capabilities to your app:

Ringing Flow

Complete calling experience with incoming/outgoing UI, accept/reject, and notifications.

Direct Call

Start call sessions directly without the ringing flow.

Recording

Record calls for playback or compliance.

Virtual Background

Blur or replace backgrounds during video calls.

Explore all Calling features →

---

AI Features

Leverage AI to enhance your chat experience:

AI Moderation

Automatically moderate content for safety

AI Agents

Build AI-powered chat agents

AI Chatbots

Create intelligent chatbot experiences

---

Framework Guides

React

Integration guide for React applications

Angular

Integration guide for Angular applications

Vue

Integration guide for Vue.js applications

Sample Apps

Explore complete implementations with UI:

Framework	Repository
React	javascript-react-chat-app
Angular	javascript-angular-chat-app
Vue	javascript-vue-chat-app

---

Need Pre-Built UI?

If you prefer ready-to-use components instead of building from scratch:

React UI Kit

Production-ready React components for chat and calling

Chat Widget

Embeddable chat widget for any website

---

Complete Working Example

Here’s a production-ready example that initializes CometChat, logs in, sends a message, and listens for responses:

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

// Configuration
const APP_ID = "YOUR_APP_ID";
const REGION = "YOUR_REGION"; // "us", "eu", or "in"
const AUTH_KEY = "YOUR_AUTH_KEY";

class ChatService {
  static instance = null;
  
  static getInstance() {
    if (!ChatService.instance) {
      ChatService.instance = new ChatService();
    }
    return ChatService.instance;
  }

  async initialize() {
    const appSettings = new CometChat.AppSettingsBuilder()
      .subscribePresenceForAllUsers()
      .setRegion(REGION)
      .autoEstablishSocketConnection(true)
      .build();

    try {
      await CometChat.init(APP_ID, appSettings);
      console.log("✓ CometChat initialized");
      return true;
    } catch (error) {
      console.error("✗ Init failed:", error);
      return false;
    }
  }

  async login(uid) {
    try {
      // Check if already logged in
      let user = await CometChat.getLoggedinUser();
      if (user) {
        console.log("✓ Already logged in:", user.getName());
        return user;
      }

      // Login
      user = await CometChat.login(uid, AUTH_KEY);
      console.log("✓ Logged in:", user.getName());
      return user;
    } catch (error) {
      console.error("✗ Login failed:", error);
      throw error;
    }
  }

  async sendMessage(receiverUID, text) {
    const message = new CometChat.TextMessage(
      receiverUID,
      text,
      CometChat.RECEIVER_TYPE.USER
    );

    try {
      const sent = await CometChat.sendMessage(message);
      console.log("✓ Message sent:", sent.getId());
      return sent;
    } catch (error) {
      console.error("✗ Send failed:", error);
      throw error;
    }
  }

  startListening(onMessage) {
    const listenerID = "MAIN_LISTENER";
    
    CometChat.addMessageListener(
      listenerID,
      new CometChat.MessageListener({
        onTextMessageReceived: (message) => {
          console.log("← Received:", message.getText());
          onMessage?.(message);
        },
        onMediaMessageReceived: (message) => {
          console.log("← Media received:", message.getAttachment());
          onMessage?.(message);
        }
      })
    );

    return () => CometChat.removeMessageListener(listenerID);
  }

  async logout() {
    try {
      await CometChat.logout();
      console.log("✓ Logged out");
    } catch (error) {
      console.error("✗ Logout failed:", error);
    }
  }
}

// Usage
const chat = ChatService.getInstance();
await chat.initialize();
await chat.login("cometchat-uid-1");
chat.startListening((msg) => console.log("New message:", msg));
await chat.sendMessage("cometchat-uid-2", "Hello from the SDK!");

---

Common Errors & Solutions

ERR_INVALID_APP_ID - App ID is invalid

Cause: The App ID doesn’t match any app in your CometChat account.

Solution:

1. Go to CometChat Dashboard
2. Select your app → API & Auth Keys
3. Copy the exact App ID (case-sensitive)
4. Ensure no extra spaces when pasting

ERR_INVALID_AUTH_KEY - Auth Key is invalid

Cause: Using wrong key type or incorrect key.

Solution:

• Use Auth Key (not REST API Key) for client-side login
• Auth Key is for development only; use Auth Tokens in production
• Copy directly from Dashboard → API & Auth Keys

ERR_UID_NOT_FOUND - User does not exist

Cause: Trying to login with a UID that hasn’t been created.

Solution:

• Use test users: cometchat-uid-1 through cometchat-uid-5
• Or create users via REST API before login
• Check for typos in the UID

ERR_NOT_LOGGED_IN - User is not logged in

Cause: Calling SDK methods before successful login.

Solution:

// Always check login status first
const user = await CometChat.getLoggedinUser();
if (!user) {
  await CometChat.login(uid, authKey);
}
// Now safe to use other methods

Messages not received in real-time

Cause: Message listener not registered or registered before login.

Solution:

1. Register listeners AFTER successful login
2. Use unique listener IDs
3. Check WebSocket connection: CometChat.getConnectionStatus()
4. Ensure autoEstablishSocketConnection(true) in app settings

CORS errors in browser

Cause: Browser security blocking requests.

Solution:

• CometChat handles CORS automatically
• If using a proxy, ensure it forwards headers correctly
• Check browser console for specific blocked URLs

---

SDK Method Reference

Quick lookup for common operations:

Operation	Method	Returns
Initialize	CometChat.init(appID, settings)	Promise<boolean>
Login (Auth Key)	CometChat.login(uid, authKey)	Promise<User>
Login (Auth Token)	CometChat.login(authToken)	Promise<User>
Logout	CometChat.logout()	Promise<void>
Get Logged-in User	CometChat.getLoggedinUser()	Promise<User|null>
Send Text	CometChat.sendMessage(textMessage)	Promise<TextMessage>
Send Media	CometChat.sendMediaMessage(mediaMessage)	Promise<MediaMessage>
Fetch Messages	messagesRequest.fetchPrevious()	Promise<BaseMessage[]>
Fetch Conversations	conversationsRequest.fetchNext()	Promise<Conversation[]>
Get User	CometChat.getUser(uid)	Promise<User>
Get Group	CometChat.getGroup(guid)	Promise<Group>
Connection Status	CometChat.getConnectionStatus()	string