Events

Handle CometChat Calls SDK v5 events on React Native for call lifecycle, participants, media state, errors, and real-time updates.

The CometChat Calls SDK uses the addEventListener method to subscribe to call events for the call lifecycle, participants, media state, and real-time updates.

​

addEventListener

For more granular control, use CometChatCalls.addEventListener() to subscribe to specific events:

const unsubscribe = CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
  console.log('Participant joined:', participant);
});

// Later, unsubscribe when no longer needed
unsubscribe();

​

Session Status Events

Event	Payload	Description
onSessionJoined	-	Successfully joined the session
onSessionLeft	-	Left the session
onConnectionLost	-	Connection to the session was lost
onConnectionRestored	-	Connection was restored
onConnectionFailed	Connection error	Failed to establish the connection to the session
onConnectionClosed	-	Connection was closed
onSessionTimedOut	-	Session timed out due to inactivity

CometChatCalls.addEventListener('onSessionJoined', () => {
  console.log('Successfully joined the session');
});

CometChatCalls.addEventListener('onSessionLeft', () => {
  console.log('Left the session');
});

CometChatCalls.addEventListener('onConnectionLost', () => {
  console.log('Connection lost - attempting to reconnect');
});

CometChatCalls.addEventListener('onConnectionRestored', () => {
  console.log('Connection restored');
});

CometChatCalls.addEventListener('onConnectionFailed', (error) => {
  console.log('Connection failed:', error);
});

CometChatCalls.addEventListener('onSessionTimedOut', () => {
  console.log('Session timed out');
});

​

Media Events

Event	Payload	Description
onAudioMuted	-	Local audio was muted
onAudioUnMuted	-	Local audio was unmuted
onVideoPaused	-	Local video was paused
onVideoResumed	-	Local video was resumed
onRecordingStarted	-	Recording started
onRecordingStopped	-	Recording stopped
onScreenShareStarted	-	Screen sharing started
onScreenShareStopped	-	Screen sharing stopped
onAudioModeChanged	Audio mode	Audio output mode changed
onCameraFacingChanged	Camera facing	Camera switched (front/rear)

CometChatCalls.addEventListener('onAudioMuted', () => {
  console.log('Audio muted');
});

CometChatCalls.addEventListener('onAudioUnMuted', () => {
  console.log('Audio unmuted');
});

CometChatCalls.addEventListener('onVideoPaused', () => {
  console.log('Video paused');
});

CometChatCalls.addEventListener('onVideoResumed', () => {
  console.log('Video resumed');
});

CometChatCalls.addEventListener('onAudioModeChanged', (mode) => {
  console.log('Audio mode changed to:', mode);
});

CometChatCalls.addEventListener('onCameraFacingChanged', (facing) => {
  console.log('Camera facing:', facing); // 'FRONT' or 'REAR'
});

​

Participant Events

Event	Payload	Description
onParticipantConnected	Participant	A participant’s device prepared the session without joining. On the caller’s prepared session this is the callee ringing
onParticipantJoined	Participant	A participant joined. On the caller’s prepared session this is the callee answering: join now
onParticipantLeft	Participant	A participant left
onParticipantAudioMuted	Participant	A participant muted their audio
onParticipantAudioUnmuted	Participant	A participant unmuted their audio
onParticipantVideoPaused	Participant	A participant paused their video
onParticipantVideoResumed	Participant	A participant resumed their video
onParticipantHandRaised	Participant	A participant raised their hand
onParticipantHandLowered	Participant	A participant lowered their hand
onParticipantStartedScreenShare	Participant	A participant started screen sharing
onParticipantStoppedScreenShare	Participant	A participant stopped screen sharing
onParticipantStartedRecording	Participant	A participant started recording
onParticipantStoppedRecording	Participant	A participant stopped recording
onDominantSpeakerChanged	Participant	The dominant speaker changed
onParticipantListChanged	Participant array	The participant list changed

CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
  console.log('Participant joined:', participant.name);
});

CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
  console.log('Participant left:', participant.name);
});

CometChatCalls.addEventListener('onParticipantListChanged', (participants) => {
  console.log('Total participants:', participants.length);
});

CometChatCalls.addEventListener('onParticipantHandRaised', (participant) => {
  console.log('Hand raised by:', participant.name);
});

CometChatCalls.addEventListener('onDominantSpeakerChanged', (participant) => {
  console.log('Dominant speaker:', participant.name);
});

​

Button Click Events

Event	Payload	Description
onLeaveSessionButtonClicked	-	Leave session button clicked
onRaiseHandButtonClicked	-	Raise hand button clicked
onShareInviteButtonClicked	-	Share invite button clicked
onChangeLayoutButtonClicked	-	Change layout button clicked
onParticipantListButtonClicked	-	Participant list button clicked
onToggleAudioButtonClicked	-	Toggle audio button clicked
onToggleVideoButtonClicked	-	Toggle video button clicked
onRecordingToggleButtonClicked	-	Recording toggle button clicked
onScreenShareButtonClicked	-	Screen share button clicked
onChatButtonClicked	-	Chat button clicked
onSwitchCameraButtonClicked	-	Switch camera button clicked

CometChatCalls.addEventListener('onLeaveSessionButtonClicked', () => {
  console.log('Leave button clicked');
  // Handle leave confirmation
});

CometChatCalls.addEventListener('onChatButtonClicked', () => {
  console.log('Chat button clicked');
  // Open chat interface
});

​

Layout Events

Event	Payload	Description
onCallLayoutChanged	Layout	The call layout changed
onParticipantListVisible	-	Participant list became visible
onParticipantListHidden	-	Participant list was hidden
onPictureInPictureLayoutEnabled	-	PiP mode was enabled
onPictureInPictureLayoutDisabled	-	PiP mode was disabled

CometChatCalls.addEventListener('onCallLayoutChanged', (layout) => {
  console.log('Layout changed to:', layout); // 'TILE', 'SIDEBAR', or 'SPOTLIGHT'
});

CometChatCalls.addEventListener('onPictureInPictureLayoutEnabled', () => {
  console.log('PiP enabled');
});

​

Participant Object

The participant object contains:

Property	Type	Description
pid	string	Participant ID
uid	string	User ID
name	string	Display name
avatar	string	Avatar URL (optional)

​

Complete Example

import React, { useEffect } from 'react';
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

function useCallEvents(onCallEnd: () => void) {
  useEffect(() => {
    const controller = new AbortController();
    const { signal } = controller;

    // Session events
    CometChatCalls.addEventListener('onSessionJoined', () => {
      console.log('Joined session');
    }, { signal });

    CometChatCalls.addEventListener('onSessionLeft', () => {
      console.log('Left session');
      onCallEnd();
    }, { signal });

    CometChatCalls.addEventListener('onSessionTimedOut', () => {
      console.log('Session timed out');
      onCallEnd();
    }, { signal });

    // Participant events
    CometChatCalls.addEventListener('onParticipantJoined', (participant) => {
      console.log(`${participant.name} joined`);
    }, { signal });

    CometChatCalls.addEventListener('onParticipantLeft', (participant) => {
      console.log(`${participant.name} left`);
    }, { signal });

    // Media events
    CometChatCalls.addEventListener('onAudioModeChanged', (mode) => {
      console.log('Audio mode:', mode);
    }, { signal });

    // Layout events
    CometChatCalls.addEventListener('onCallLayoutChanged', (layout) => {
      console.log('Layout:', layout);
    }, { signal });

    // Cleanup
    return () => controller.abort();
  }, [onCallEnd]);
}

export default useCallEvents;

​

Events on a prepared session

CometChatCalls.getActiveSession() returns the session as soon as it is prepared — which is what initiateCall does on the caller and what the Push SDK’s ring does on the callee — before anyone has joined. Listening on it is what lets a caller show “Ringing…” and detect the answer without joining first.

const session = CometChatCalls.getActiveSession();   // null when no session is prepared or joined
const me = CometChatCalls.getLoggedInUser()?.uid;

session?.addEventListener('onParticipantConnected', p => {
  if (p.uid !== me) setStatus('Ringing…');   // the callee's device got the push
});
session?.addEventListener('onParticipantJoined', p => {
  if (p.uid !== me) join();                  // the callee answered
});

Event	On a prepared session it means
onParticipantConnected	The other device prepared the session: it is ringing there
onParticipantJoined	The other side answered
onSessionTimedOut	A joined session ended after being idle. A prepared session that nobody joins fires onConnectionClosed instead
onConnectionClosed	The call ended before anyone joined (declined, cancelled from another device, or the room went away)

A participant who has only prepared isn’t in the roster. A callee whose device has prepared the session reaches the caller as onParticipantConnected, not onParticipantJoined, and that is the only caller-side signal that the callee’s device has been reached. Participants who have actually joined are reported as usual, including to a session that is still prepared, so handle a callee who is already there.

---

​

Incoming call events

On React Native these come from the Push Notifications SDK, not the Calls SDK. They report a call for the logged-in user starting and ending, whether it arrived by push while the app was killed or while it was running.

import { CometChatVoipNotifications } from '@cometchat/push-notifications-voip-react-native';

const offRinging = CometChatVoipNotifications.onCallRinging(call => { /* ringing */ });
const offAccepted = CometChatVoipNotifications.onCallAccepted(call => { /* answered here */ });
const offEnded = CometChatVoipNotifications.onCallEnded(e => { /* e.reason */ });
const offRingEnded = CometChatVoipNotifications.onRingEnded(e => { /* the ring stopped */ });

Event	Payload	Description
onCallRinging	PNCallInfo	A call for the logged-in user is ringing
onCallAccepted	PNCallInfo	The user answered; open your call screen
onCallEnded	PNCallEndEvent	The call ended. Caller: declined, timedOut, cancelled. Callee still ringing: cancelled, answeredElsewhere, declined, timedOut. The raw wire action is on PNCallEndEvent.callAction
onRingEnded	PNRingEndEvent	The ring stopped, whatever happened to the call

Each returns an unsubscribe function. Subscribing late is safe: a call answered before your component mounted is held and delivered to the first subscriber. See Ringing.

---

​

Login events

CometChatCalls.addLoginListener reports the Calls SDK login state. The Push SDK uses it to keep the identity its ring gates read in step with the logged-in user; your app can use it to gate call UI.

CometChatCalls.addLoginListener('my-app', {
  onLoginSuccess: user => console.log('logged in as', user.uid),
  onLogoutSuccess: () => console.log('logged out'),
});

CometChatCalls.removeLoginListener('my-app');

Listener ids are keys: registering the same id twice replaces the earlier listener. Remove it when the screen goes away. The User the Calls SDK hands back is a plain object with a uid field, not a class with getUid().

---

​

Related Documentation

• Ringing - Start, answer and end calls
• Actions - Control the call programmatically
• Session Settings - Configure event listeners
• Participant Management - Manage participants