> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```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 |
| `onConnectionFailed` | Connection error | Failed to establish the connection to the session |
| `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('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) |

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

## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.