Ringing - CometChat Docs

Quick Reference - Initiate a call and listen for events:

// Initiate a video call (default 45s no-answer timeout)
const call = new CometChat.Call("RECEIVER_ID", CometChat.CALL_TYPE.VIDEO, CometChat.RECEIVER_TYPE.USER);
await CometChat.initiateCall(call);

// Initiate with custom timeout (60 seconds)
await CometChat.initiateCall(call, 60);

// Accept an incoming call
await CometChat.acceptCall(sessionId);

// Reject or cancel
await CometChat.rejectCall(sessionId, CometChat.CALL_STATUS.REJECTED);

Available via: SDK | REST API | UI Kits

Overview

This section explains how to implement a complete calling workflow with ringing functionality, including incoming/outgoing call UI, call acceptance, rejection, and cancellation. Previously known as Default Calling.

After the call is accepted, you need to start the call session. See the Call Session guide for details on starting and managing the actual call.

Call Flow:

Caller initiates a call using initiateCall()
Receiver gets notified via onIncomingCallReceived() callback
Receiver can either:
- Accept the call using acceptCall()
- Reject the call using rejectCall() with status CALL_STATUS_REJECTED
Caller can cancel the call using rejectCall() with status CALL_STATUS_CANCELLED
Once accepted, both participants generate a call token and render the CometChatCalls.Component to join the call

Initiate Call

The initiateCall() method sends a call request to a user or a group. On success, the receiver gets an onIncomingCallReceived() callback.

User Call (JavaScript)
Group Call (JavaScript)
User Call (TypeScript)
Group Call (TypeScript)

const receiverID = "UID";
const callType = CometChat.CALL_TYPE.VIDEO;
const receiverType = CometChat.RECEIVER_TYPE.USER;

const call = new CometChat.Call(receiverID, callType, receiverType);

CometChat.initiateCall(call).then(
  (outgoingCall) => {
    console.log("Call initiated:", outgoingCall);
    // Show outgoing call UI
    // Store outgoingCall.getSessionId() for later use
  },
  (error) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID = "GUID";
const callType = CometChat.CALL_TYPE.VIDEO;
const receiverType = CometChat.RECEIVER_TYPE.GROUP;

const call = new CometChat.Call(receiverID, callType, receiverType);

CometChat.initiateCall(call).then(
  (outgoingCall) => {
    console.log("Call initiated:", outgoingCall);
    // Show outgoing call UI
  },
  (error) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID: string = "UID";
const callType: string = CometChat.CALL_TYPE.VIDEO;
const receiverType: string = CometChat.RECEIVER_TYPE.USER;

const call: CometChat.Call = new CometChat.Call(receiverID, callType, receiverType);

CometChat.initiateCall(call).then(
  (outgoingCall: CometChat.Call) => {
    console.log("Call initiated:", outgoingCall);
  },
  (error: CometChat.CometChatException) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID: string = "GUID";
const callType: string = CometChat.CALL_TYPE.VIDEO;
const receiverType: string = CometChat.RECEIVER_TYPE.GROUP;

const call: CometChat.Call = new CometChat.Call(receiverID, callType, receiverType);

CometChat.initiateCall(call).then(
  (outgoingCall: CometChat.Call) => {
    console.log("Call initiated:", outgoingCall);
  },
  (error: CometChat.CometChatException) => {
    console.log("Call initiation failed:", error);
  }
);

Parameter	Description
`receiverID`	The UID or GUID of the recipient
`receiverType`	`CometChat.RECEIVER_TYPE.USER` or `CometChat.RECEIVER_TYPE.GROUP`
`callType`	`CometChat.CALL_TYPE.AUDIO` or `CometChat.CALL_TYPE.VIDEO`

On success, a Call object is returned containing the call details including a unique sessionId required for starting the call session. By default, an unanswered call automatically cancels after 45 seconds. You can customize this duration by passing an optional timeout parameter (in seconds) as the second argument to initiateCall().

User Call (JavaScript)
Group Call (JavaScript)
User Call (TypeScript)
Group Call (TypeScript)

const receiverID = "UID";
const callType = CometChat.CALL_TYPE.VIDEO;
const receiverType = CometChat.RECEIVER_TYPE.USER;

const call = new CometChat.Call(receiverID, callType, receiverType);

// Set a custom timeout of 60 seconds
CometChat.initiateCall(call, 60).then(
  (outgoingCall) => {
    console.log("Call initiated with 60s timeout:", outgoingCall);
  },
  (error) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID = "GUID";
const callType = CometChat.CALL_TYPE.VIDEO;
const receiverType = CometChat.RECEIVER_TYPE.GROUP;

const call = new CometChat.Call(receiverID, callType, receiverType);

// Set a custom timeout of 60 seconds
CometChat.initiateCall(call, 60).then(
  (outgoingCall) => {
    console.log("Call initiated with 60s timeout:", outgoingCall);
  },
  (error) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID: string = "UID";
const callType: string = CometChat.CALL_TYPE.VIDEO;
const receiverType: string = CometChat.RECEIVER_TYPE.USER;

const call: CometChat.Call = new CometChat.Call(receiverID, callType, receiverType);

// Set a custom timeout of 60 seconds
CometChat.initiateCall(call, 60).then(
  (outgoingCall: CometChat.Call) => {
    console.log("Call initiated with 60s timeout:", outgoingCall);
  },
  (error: CometChat.CometChatException) => {
    console.log("Call initiation failed:", error);
  }
);

const receiverID: string = "GUID";
const callType: string = CometChat.CALL_TYPE.VIDEO;
const receiverType: string = CometChat.RECEIVER_TYPE.GROUP;

const call: CometChat.Call = new CometChat.Call(receiverID, callType, receiverType);

// Set a custom timeout of 60 seconds
CometChat.initiateCall(call, 60).then(
  (outgoingCall: CometChat.Call) => {
    console.log("Call initiated with 60s timeout:", outgoingCall);
  },
  (error: CometChat.CometChatException) => {
    console.log("Call initiation failed:", error);
  }
);

Parameter	Type	Description
`call`	`Call`	The call object created with receiver ID, call type, and receiver type.
`timeout`	`number`	Optional. The ringing duration in seconds before an unanswered call is automatically cancelled. Default: `45`.

Response

On Success — initiateCall() returns a Call object with session details:

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-7"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"initiated"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009087929026e8ed35bb3c1f9b4aea3d6fe52b63eaa060"`
`status`	string	Current call status	`"initiated"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009087`
`joinedAt`	number	Unix timestamp when user joined	`1772009087`
`id`	string	Unique message ID	`"25329"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who initiated the call	See User Object below
`receiver`	object	User receiving the call	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call was sent	`1772009087`
`updatedAt`	number	Unix timestamp of last update	`1772009087`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-6"`
`name`	string	Display name of the user	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Call Listeners

Register the CallListener to receive real-time call events. Each listener requires a unique listenerId string to prevent duplicate registrations and enable targeted removal.

JavaScript
TypeScript

const listenerId = "UNIQUE_LISTENER_ID";

// Register listener
CometChat.addCallListener(
  listenerId,
  new CometChat.CallListener({
    onIncomingCallReceived: (call) => {
      console.log("Incoming call:", call);
      // Show incoming call UI
    },
    onOutgoingCallAccepted: (call) => {
      console.log("Outgoing call accepted:", call);
      // Receiver accepted, start the call session
    },
    onOutgoingCallRejected: (call) => {
      console.log("Outgoing call rejected:", call);
      // Receiver rejected, dismiss outgoing call UI
    },
    onIncomingCallCancelled: (call) => {
      console.log("Incoming call cancelled:", call);
      // Caller cancelled, dismiss incoming call UI
    },
    onCallEndedMessageReceived: (call) => {
      console.log("Call ended message:", call);
      // Call ended by remote participant
    }
  })
);

// Unregister listener when done
CometChat.removeCallListener(listenerId);

const listenerId: string = "UNIQUE_LISTENER_ID";

// Register listener
CometChat.addCallListener(
  listenerId,
  new CometChat.CallListener({
    onIncomingCallReceived: (call: CometChat.Call) => {
      console.log("Incoming call:", call);
      // Show incoming call UI
    },
    onOutgoingCallAccepted: (call: CometChat.Call) => {
      console.log("Outgoing call accepted:", call);
      // Receiver accepted, start the call session
    },
    onOutgoingCallRejected: (call: CometChat.Call) => {
      console.log("Outgoing call rejected:", call);
      // Receiver rejected, dismiss outgoing call UI
    },
    onIncomingCallCancelled: (call: CometChat.Call) => {
      console.log("Incoming call cancelled:", call);
      // Caller cancelled, dismiss incoming call UI
    },
    onCallEndedMessageReceived: (call: CometChat.Call) => {
      console.log("Call ended message:", call);
      // Call ended by remote participant
    }
  })
);

// Unregister listener when done
CometChat.removeCallListener(listenerId);

Always remove call listeners when the component unmounts using CometChat.removeCallListener(listenerId). Failing to do so can cause memory leaks and duplicate event handling.

Events

Event	Description
`onIncomingCallReceived(call)`	Invoked when an incoming call is received. The `call` contains caller details, session ID, and call type. Display incoming call UI here.
`onOutgoingCallAccepted(call)`	Invoked on the caller’s device when the receiver accepts. Generate call token and start the session here.
`onOutgoingCallRejected(call)`	Invoked on the caller’s device when the receiver rejects the call. Dismiss outgoing call UI here.
`onIncomingCallCancelled(call)`	Invoked on the receiver’s device when the caller cancels before answering. Dismiss incoming call UI here.
`onCallEndedMessageReceived(call)`	Invoked when a call ends. The `call` contains final status and duration. Update call history here.

Response

On Event — onIncomingCallReceived returns a Call object (same structure as initiateCall response):

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-7"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"initiated"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009087929026e8ed35bb3c1f9b4aea3d6fe52b63eaa060"`
`status`	string	Current call status	`"initiated"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009087`
`joinedAt`	number	Unix timestamp when user joined	`1772009087`
`id`	string	Unique message ID	`"25329"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who initiated the call	See User Object below
`receiver`	object	User receiving the call	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call was sent	`1772009087`
`updatedAt`	number	Unix timestamp of last update	`1772009087`

On Event — onOutgoingCallRejected / onIncomingCallCancelled returns a Call object with status: "unanswered":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-7"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"unanswered"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009087929026e8ed35bb3c1f9b4aea3d6fe52b63eaa060"`
`status`	string	Current call status	`"unanswered"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009087`
`id`	string	Unique message ID	`"25330"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who initiated the call	See User Object below
`receiver`	object	User receiving the call	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call was sent	`1772009132`
`updatedAt`	number	Unix timestamp of last update	`1772009132`

On Event — onOutgoingCallAccepted returns a Call object with status: "ongoing":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"ongoing"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009341a5f92ad7d21eba0bf840bb6950c7000eb9d5863b"`
`status`	string	Current call status	`"ongoing"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009341`
`joinedAt`	number	Unix timestamp when user joined	`1772009347`
`id`	string	Unique message ID	`"25332"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who accepted the call	See User Object below
`receiver`	object	User receiving the acceptance	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call was sent	`1772009347`
`updatedAt`	number	Unix timestamp of last update	`1772009347`

On Event — onCallEndedMessageReceived returns a Call object with status: "ended":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"ended"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009341a5f92ad7d21eba0bf840bb6950c7000eb9d5863b"`
`status`	string	Current call status	`"ended"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009341`
`id`	string	Unique message ID	`"25333"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who ended the call	See User Object below
`receiver`	object	Other participant	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call ended	`1772009475`
`updatedAt`	number	Unix timestamp of last update	`1772009475`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-6"`
`name`	string	Display name of the user	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Accept Call

When an incoming call is received via onIncomingCallReceived(), use acceptCall() to accept it. On success, start the call session.

JavaScript
TypeScript

const sessionId = call.getSessionId(); // From onIncomingCallReceived

CometChat.acceptCall(sessionId).then(
  (call) => {
    console.log("Call accepted:", call);
    // Call accepted, now start the call session
    // Generate token and render CometChatCalls.Component
  },
  (error) => {
    console.log("Accept call failed:", error);
  }
);

const sessionId: string = call.getSessionId(); // From onIncomingCallReceived

CometChat.acceptCall(sessionId).then(
  (call: CometChat.Call) => {
    console.log("Call accepted:", call);
    // Call accepted, now start the call session
  },
  (error: CometChat.CometChatException) => {
    console.log("Accept call failed:", error);
  }
);

Response

On Success — acceptCall() returns a Call object with status: "ongoing":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"ongoing"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009341a5f92ad7d21eba0bf840bb6950c7000eb9d5863b"`
`status`	string	Current call status	`"ongoing"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009341`
`joinedAt`	number	Unix timestamp when user joined	`1772009347`
`id`	string	Unique message ID	`"25332"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who accepted the call	See User Object below
`receiver`	object	User receiving the acceptance	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call was sent	`1772009347`
`updatedAt`	number	Unix timestamp of last update	`1772009347`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Reject Call

Use rejectCall() to reject an incoming call. Set the status to CALL_STATUS_REJECTED.

JavaScript
TypeScript

const sessionId = call.getSessionId();
const status = CometChat.CALL_STATUS.REJECTED;

CometChat.rejectCall(sessionId, status).then(
  (call) => {
    console.log("Call rejected:", call);
    // Dismiss incoming call UI
  },
  (error) => {
    console.log("Reject call failed:", error);
  }
);

const sessionId: string = call.getSessionId();
const status: string = CometChat.CALL_STATUS.REJECTED;

CometChat.rejectCall(sessionId, status).then(
  (call: CometChat.Call) => {
    console.log("Call rejected:", call);
  },
  (error: CometChat.CometChatException) => {
    console.log("Reject call failed:", error);
  }
);

Response

On Success — rejectCall() with REJECTED status returns a Call object:

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"rejected"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772011647d5c89acf4865fd17a9e7195bae5cee3e15d0dc34"`
`status`	string	Current call status	`"rejected"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772011647`
`id`	string	Unique message ID	`"25361"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who rejected the call	See User Object below
`receiver`	object	User receiving the rejection	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when rejection was sent	`1772011654`
`updatedAt`	number	Unix timestamp of last update	`1772011654`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Cancel Call

The caller can cancel an outgoing call before it’s answered using rejectCall() with status CALL_STATUS_CANCELLED.

JavaScript
TypeScript

const sessionId = call.getSessionId();
const status = CometChat.CALL_STATUS.CANCELLED;

CometChat.rejectCall(sessionId, status).then(
  (call) => {
    console.log("Call cancelled:", call);
    // Dismiss outgoing call UI
  },
  (error) => {
    console.log("Cancel call failed:", error);
  }
);

const sessionId: string = call.getSessionId();
const status: string = CometChat.CALL_STATUS.CANCELLED;

CometChat.rejectCall(sessionId, status).then(
  (call: CometChat.Call) => {
    console.log("Call cancelled:", call);
  },
  (error: CometChat.CometChatException) => {
    console.log("Cancel call failed:", error);
  }
);

Response

On Success — rejectCall() with CANCELLED status returns a Call object:

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-7"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"cancelled"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009850a11d03ce320d8df8fde2ac7b43a0c30009b954f5"`
`status`	string	Current call status	`"cancelled"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772009850`
`id`	string	Unique message ID	`"25338"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who cancelled the call	See User Object below
`receiver`	object	User who was being called	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when cancellation was sent	`1772009856`
`updatedAt`	number	Unix timestamp of last update	`1772009856`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-6"`
`name`	string	Display name of the user	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Start Call Session

Once the call is accepted, both participants need to start the call session. Caller flow: In the onOutgoingCallAccepted() callback, generate a token and start the session. Receiver flow: In the acceptCall() success callback, generate a token and start the session.

JavaScript
TypeScript

const sessionId = call.getSessionId();
const loggedInUser = await CometChat.getLoggedinUser();
const userAuthToken = loggedInUser.getAuthToken();

// Step 1: Generate call token
CometChatCalls.generateToken(sessionId, userAuthToken).then(
  (callToken) => {
    // Step 2: Configure call settings
    const callListener = new CometChatCalls.OngoingCallListener({
      onCallEnded: () => {
        CometChat.clearActiveCall();
        CometChatCalls.endSession();
        // Close calling screen
      },
      onCallEndButtonPressed: () => {
        CometChat.endCall(sessionId).then(
          () => {
            CometChat.clearActiveCall();
            CometChatCalls.endSession();
            // Close calling screen
          },
          (error) => console.log("End call failed:", error)
        );
      },
      onUserJoined: (user) => console.log("User joined:", user),
      onUserLeft: (user) => console.log("User left:", user),
      onError: (error) => console.log("Call error:", error)
    });

    const callSettings = new CometChatCalls.CallSettingsBuilder()
      .enableDefaultLayout(true)
      .setIsAudioOnlyCall(false)
      .setCallEventListener(callListener)
      .build();

    // Step 3: Render call component
    // <CometChatCalls.Component callSettings={callSettings} callToken={callToken} />
  },
  (error) => {
    console.log("Token generation failed:", error);
  }
);

const sessionId: string = call.getSessionId();
const loggedInUser = await CometChat.getLoggedinUser();
const userAuthToken: string = loggedInUser.getAuthToken();

// Step 1: Generate call token
CometChatCalls.generateToken(sessionId, userAuthToken).then(
  (callToken: GenerateToken) => {
    // Step 2: Configure call settings
    const callListener = new CometChatCalls.OngoingCallListener({
      onCallEnded: () => {
        CometChat.clearActiveCall();
        CometChatCalls.endSession();
        // Close calling screen
      },
      onCallEndButtonPressed: () => {
        CometChat.endCall(sessionId).then(
          () => {
            CometChat.clearActiveCall();
            CometChatCalls.endSession();
            // Close calling screen
          },
          (error: CometChat.CometChatException) => console.log("End call failed:", error)
        );
      },
      onUserJoined: (user: CometChat.User) => console.log("User joined:", user),
      onUserLeft: (user: CometChat.User) => console.log("User left:", user),
      onError: (error: CometChat.CometChatException) => console.log("Call error:", error)
    });

    const callSettings = new CometChatCalls.CallSettingsBuilder()
      .enableDefaultLayout(true)
      .setIsAudioOnlyCall(false)
      .setCallEventListener(callListener)
      .build();

    // Step 3: Render call component
    // <CometChatCalls.Component callSettings={callSettings} callToken={callToken} />
  },
  (error: CometChat.CometChatException) => {
    console.log("Token generation failed:", error);
  }
);

Response

On Success — generateToken() returns an object with session and token:

Parameter	Type	Description	Sample Value
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772009341a5f92ad7d21eba0bf840bb6950c7000eb9d5863b"`
`token`	string	JWT token for authenticating the call session	`"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImNjcHJvX2p3dF9yczI1Nl9rZXkxIn0..."`

On Event — onUserJoined returns user info when a participant joins:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`isVideoMuted`	boolean	Whether user’s video is muted	`true`
`isAudioMuted`	boolean	Whether user’s audio is muted	`false`
`isLocalUser`	boolean	Whether this is the local user	`false`
`id`	string	Internal participant ID	`"03dcf87d"`
`joinedAt`	string	Unix timestamp (ms) when user joined	`"1772009349593"`

On Event — onUserListUpdated returns the current list of participants:

Parameter	Type	Description	Sample Value
(array)	array	Array of participant objects	See below

Each participant object:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-6"`
`name`	string	Display name of the user	`"Ronald Jerry"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-6.webp"`

On Event — onUserLeft returns user info when a participant leaves:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`id`	string	Internal participant ID	`"07ba41cd"`
`joinedAt`	string	Unix timestamp (ms) when user joined	`"1772010034825"`
`isAudioMuted`	boolean	Whether user’s audio was muted	`false`
`isVideoMuted`	boolean	Whether user’s video was muted	`true`

For more details on call settings and customization, see the Call Session guide.

End Call

To end an active call in the ringing flow, the process differs based on who ends the call. User who ends the call: When the user presses the end call button, the onCallEndButtonPressed() callback is triggered. Inside this callback, call CometChat.endCall() to notify other participants. On success, call CometChat.clearActiveCall() and CometChatCalls.endSession() to release resources.

JavaScript
TypeScript

onCallEndButtonPressed: () => {
  CometChat.endCall(sessionId).then(
    (call) => {
      console.log("Call ended successfully");
      CometChat.clearActiveCall();
      CometChatCalls.endSession();
      // Close the calling screen
    },
    (error) => {
      console.log("End call failed:", error);
    }
  );
}

onCallEndButtonPressed: () => {
  CometChat.endCall(sessionId).then(
    (call: CometChat.Call) => {
      console.log("Call ended successfully");
      CometChat.clearActiveCall();
      CometChatCalls.endSession();
      // Close the calling screen
    },
    (error: CometChat.CometChatException) => {
      console.log("End call failed:", error);
    }
  );
}

Remote participant (receives onCallEnded() callback):

JavaScript
TypeScript

onCallEnded: () => {
  CometChat.clearActiveCall();
  CometChatCalls.endSession();
  // Close the calling screen
}

onCallEnded: () => {
  CometChat.clearActiveCall();
  CometChatCalls.endSession();
  // Close the calling screen
}

Response

On Success — endCall() returns a Call object with status: "ended":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"ongoing"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.17720117078263785b8e96c36c6a586d6bb3a60e0a6c16d018"`
`status`	string	Current call status	`"ended"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772011707`
`joinedAt`	number	Unix timestamp when user joined	`1772011711`
`id`	string	Unique message ID	`"25363"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who ended the call	See User Object below
`receiver`	object	Other participant	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when call ended	`1772011711`
`updatedAt`	number	Unix timestamp of last update	`1772011711`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

For more details, see the End Call Session guide.

Busy Call Handling

If the receiver is already on another call, you can reject the incoming call with CALL_STATUS_BUSY status.

JavaScript
TypeScript

const sessionId = call.getSessionId();
const status = CometChat.CALL_STATUS.BUSY;

CometChat.rejectCall(sessionId, status).then(
  (call) => {
    console.log("Busy status sent:", call);
  },
  (error) => {
    console.log("Busy rejection failed:", error);
  }
);

const sessionId: string = call.getSessionId();
const status: string = CometChat.CALL_STATUS.BUSY;

CometChat.rejectCall(sessionId, status).then(
  (call: CometChat.Call) => {
    console.log("Busy status sent:", call);
  },
  (error: CometChat.CometChatException) => {
    console.log("Busy rejection failed:", error);
  }
);

Response

On Success — rejectCall() with BUSY status returns a Call object:

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"busy"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772011351c36eb867b604d0a861952ea718d3d8eaf1c89ec0"`
`status`	string	Current call status	`"busy"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772011351`
`id`	string	Unique message ID	`"25359"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who sent busy status	See User Object below
`receiver`	object	User receiving the busy status	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when busy status was sent	`1772011351`
`updatedAt`	number	Unix timestamp of last update	`1772011351`

On Event — The caller receives onOutgoingCallRejected with status: "busy":

Parameter	Type	Description	Sample Value
`receiverId`	string	UID of the call recipient	`"cometchat-uid-6"`
`type`	string	Type of call	`"audio"`
`receiverType`	string	Type of receiver	`"user"`
`category`	string	Message category	`"call"`
`action`	string	Current call action	`"busy"`
`sessionId`	string	Unique session identifier for the call	`"v1.in.2748663902141719.1772011351c36eb867b604d0a861952ea718d3d8eaf1c89ec0"`
`status`	string	Current call status	`"busy"`
`initiatedAt`	number	Unix timestamp when call was initiated	`1772011351`
`id`	string	Unique message ID	`"25359"`
`conversationId`	string	Unique conversation identifier	`"cometchat-uid-6_user_cometchat-uid-7"`
`sender`	object	User who sent busy status	See User Object below
`receiver`	object	User receiving the busy status	See User Object below
`callInitiator`	object	User who started the call	See User Object below
`callReceiver`	object	Intended call recipient	See User Object below
`sentAt`	number	Unix timestamp when busy status was sent	`1772011351`
`updatedAt`	number	Unix timestamp of last update	`1772011351`

User Object Structure:

Parameter	Type	Description	Sample Value
`uid`	string	Unique user identifier	`"cometchat-uid-7"`
`name`	string	Display name of the user	`"Henry Marino"`
`avatar`	string	URL to user’s avatar image	`"https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-7.webp"`
`status`	string	User’s online status	`"online"`
`role`	string	User’s role	`"default"`

Best Practices

Always remove call listeners on component unmount to prevent memory leaks and duplicate events
Store the sessionId from initiateCall() or onIncomingCallReceived() — you’ll need it for accept, reject, cancel, and starting the session
Handle the CALL_STATUS_BUSY case when the receiver is already on another call
Call CometChat.clearActiveCall() and CometChatCalls.endSession() together when a call ends to properly release all resources
Request camera and microphone permissions before initiating or accepting a call
Show appropriate UI feedback (spinner, ringing animation) while waiting for the receiver to respond

Troubleshooting

onIncomingCallReceived not firing: Ensure CometChat.addCallListener() is registered before the call is initiated and that the listener ID is unique
Call accepted but no audio/video: After acceptCall(), you must start the call session by generating a token and rendering CometChatCalls.Component — see the Start Call Session section above
Duplicate call events: You may have registered the same listener multiple times — always call CometChat.removeCallListener(listenerId) on unmount
initiateCall fails with error: Verify the receiver UID/GUID exists and that the logged-in user has an active session
Call ends immediately after accept: Make sure both caller and receiver generate a call token and render CometChatCalls.Component — if only one side renders the component, the call will appear to drop
Busy status not working: Ensure you’re using CometChat.CALL_STATUS.BUSY (not REJECTED) when the receiver is already on a call

Next Steps

Call Session

Start and manage the actual call session after the ringing flow completes.

Calls SDK Setup

Install dependencies, configure permissions, and initialize the Calls SDK.

Recording

Record audio and video calls for playback or compliance.

Call Logs

Retrieve and display call history including duration and participants.

​Overview

​Initiate Call

​Call Listeners

​Events

​Accept Call

​Reject Call

​Cancel Call

​Start Call Session

​End Call

​Busy Call Handling

​Next Steps

Call Session

Calls SDK Setup

Recording

Call Logs

Overview

Initiate Call

Call Listeners

Events

Accept Call

Reject Call

Cancel Call

Start Call Session

End Call

Busy Call Handling

Next Steps