> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> CometChat Calling SDK v5 - Events for React Native

The CometChat Calls SDK provides two ways to listen for call events: the `OngoingCallListener` class for legacy-style callbacks, and the `addEventListener` method for modern event subscriptions.

## OngoingCallListener

The `OngoingCallListener` class provides callbacks for call events. Pass it to `CallSettingsBuilder.setCallEventListener()`:

```tsx theme={null}
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

const callListener = new CometChatCalls.OngoingCallListener({
  onUserJoined: (user) => {
    console.log('User joined:', user);
  },
  onUserLeft: (user) => {
    console.log('User left:', user);
  },
  onUserListUpdated: (userList) => {
    console.log('User list updated:', userList);
  },
  onCallEnded: () => {
    console.log('Call ended');
  },
  onCallEndButtonPressed: () => {
    console.log('End call button pressed');
  },
  onSessionTimeout: () => {
    console.log('Session timed out');
  },
  onError: (error) => {
    console.error('Call error:', error);
  },
  onAudioModesUpdated: (audioModes) => {
    console.log('Audio modes updated:', audioModes);
  },
  onRecordingStarted: (data) => {
    console.log('Recording started:', data);
  },
  onRecordingStopped: (data) => {
    console.log('Recording stopped:', data);
  },
  onUserMuted: (user) => {
    console.log('User muted:', user);
  },
  onCallSwitchedToVideo: (data) => {
    console.log('Call switched to video:', data);
  },
});

const callSettings = new CometChatCalls.CallSettingsBuilder()
  .setCallEventListener(callListener)
  .build();
```

### OngoingCallListener Events

| Event                    | Payload           | Description                             |
| ------------------------ | ----------------- | --------------------------------------- |
| `onUserJoined`           | User object       | A user joined the call                  |
| `onUserLeft`             | User object       | A user left the call                    |
| `onUserListUpdated`      | User array        | The participant list changed            |
| `onCallEnded`            | -                 | The call has ended                      |
| `onCallEndButtonPressed` | -                 | The end call button was pressed         |
| `onSessionTimeout`       | -                 | The session timed out due to inactivity |
| `onError`                | Error object      | An error occurred                       |
| `onAudioModesUpdated`    | Audio modes array | Available audio modes changed           |
| `onRecordingStarted`     | Recording data    | Recording has started                   |
| `onRecordingStopped`     | Recording data    | Recording has stopped                   |
| `onUserMuted`            | User object       | A user was muted                        |
| `onCallSwitchedToVideo`  | Session data      | An audio call was switched to video     |

## addEventListener

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

```tsx theme={null}
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             |
| `onConnectionClosed`   | -       | Connection was closed               |
| `onSessionTimedOut`    | -       | Session timed out due to inactivity |

```tsx theme={null}
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('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) |

```tsx theme={null}
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                          |
| --------------------------------- | ----------------- | ------------------------------------ |
| `onParticipantJoined`             | Participant       | A participant joined                 |
| `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         |

```tsx theme={null}
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    |

```tsx theme={null}
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           |

```tsx theme={null}
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

```tsx theme={null}
import React, { useEffect, useRef } from 'react';
import { CometChatCalls } from '@cometchat/calls-sdk-react-native';

function useCallEvents(onCallEnd: () => void) {
  const unsubscribersRef = useRef<Array<() => void>>([]);

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

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

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

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

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

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

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

    // Cleanup
    return () => {
      unsubscribersRef.current.forEach((unsubscribe) => unsubscribe());
      unsubscribersRef.current = [];
    };
  }, [onCallEnd]);
}

export default useCallEvents;
```

## Related Documentation

* [Actions](/calls/react-native/actions) - Control the call programmatically
* [Session Settings](/calls/react-native/session-settings) - Configure event listeners
* [Participant Management](/calls/react-native/participant-management) - Manage participants