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

# Session Control

Control the call session lifecycle and participant interactions. These methods allow you to leave the session, raise/lower your hand, and check session status.

## Prerequisites

* An active [call session](/calls/flutter/join-session)
* Access to the `CallSession` instance

## Get CallSession Instance

Session control methods are called on the `CallSession` singleton:

```dart theme={null}
CallSession? callSession = CallSession.getInstance();
```

<Note>
  `CallSession.getInstance()` returns `null` if no active session exists. Always use the null-aware `?.` operator when calling methods.
</Note>

***

## Check Session Status

Check if there is currently an active call session.

```dart theme={null}
bool? isActive = CallSession.getInstance()?.isCallSessionActive();

if (isActive == true) {
  debugPrint("Call session is active");
} else {
  debugPrint("No active call session");
}
```

| Return Type | Description                                                             |
| ----------- | ----------------------------------------------------------------------- |
| `bool?`     | `true` if a session is active, `false` otherwise, `null` if no instance |

<Note>
  Use this method to check session status before calling other `CallSession` methods, or to determine if you need to show call UI.
</Note>

***

## Leave Session

End your participation in the current call session.

```dart theme={null}
await CallSession.getInstance()?.leaveSession();
```

<Note>
  When you leave the session, the `onSessionLeft()` callback is triggered on your `SessionStatusListener`. Other participants will receive the `onParticipantLeft(Participant)` callback.
</Note>

### Handling Session End

```dart theme={null}
CallSession.getInstance()?.addSessionStatusListener(SessionStatusListeners(
  onSessionLeft: () {
    debugPrint("Successfully left the session");
    // Navigate away from call screen
    Navigator.of(context).pop();
  },
));
```

<Note>
  Flutter listeners are not lifecycle-aware. You must manually remove listeners in your widget's `dispose()` method to prevent memory leaks.
</Note>

***

## End Call Session

Alias for `leaveSession()`. Ends your participation and disconnects gracefully.

```dart theme={null}
await CallSession.getInstance()?.endCallSession();
```

***

## Raise Hand

Raise your hand to get attention from other participants. This is useful in meetings or webinars when you want to ask a question or make a comment.

```dart theme={null}
await CallSession.getInstance()?.raiseHand();
```

<Note>
  When you raise your hand, all participants receive the `onParticipantHandRaised(Participant)` callback on their `ParticipantEventListener`.
</Note>

***

## Lower Hand

Lower your previously raised hand.

```dart theme={null}
await CallSession.getInstance()?.lowerHand();
```

<Note>
  When you lower your hand, all participants receive the `onParticipantHandLowered(Participant)` callback on their `ParticipantEventListener`.
</Note>

***

## Listen for Hand Raise Events

Register a `ParticipantEventListener` to receive callbacks when participants raise or lower their hands:

```dart theme={null}
CallSession.getInstance()?.addParticipantEventListener(ParticipantEventListeners(
  onParticipantHandRaised: (Participant participant) {
    debugPrint("${participant.name} raised their hand");
    // Show hand raised indicator in UI
  },
  onParticipantHandLowered: (Participant participant) {
    debugPrint("${participant.name} lowered their hand");
    // Hide hand raised indicator in UI
  },
));
```

***

## Button Click Listeners

Listen for when users tap the leave or raise hand buttons:

```dart theme={null}
CallSession.getInstance()?.addButtonClickListener(ButtonClickListeners(
  onLeaveSessionButtonClicked: () {
    debugPrint("Leave button clicked");
    // Optionally show confirmation dialog before leaving
  },
  onRaiseHandButtonClicked: () {
    debugPrint("Raise hand button clicked");
    // Handle custom raise hand logic if needed
  },
));
```

***

## Hide Session Control Buttons

Control the visibility of session control buttons in the UI:

```dart theme={null}
SessionSettings sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .hideLeaveSessionButton(false)  // Show leave button
    .hideRaiseHandButton(false)     // Show raise hand button
    .hideShareInviteButton(true)    // Hide share invite button
    .build();
```

***

## Session Timeout

Configure the idle timeout period for when you're alone in a session:

```dart theme={null}
SessionSettings sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setIdleTimeoutPeriod(300)  // 300 seconds (5 minutes)
    .build();
```

When the timeout is reached, the `onSessionTimedOut()` callback is triggered:

```dart theme={null}
CallSession.getInstance()?.addSessionStatusListener(SessionStatusListeners(
  onSessionTimedOut: () {
    debugPrint("Session timed out due to inactivity");
    // Handle timeout - navigate away from call screen
    Navigator.of(context).pop();
  },
));
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Session Status Listener" icon="bell" href="/calls/flutter/session-status-listener">
    Handle all session lifecycle events
  </Card>

  <Card title="Button Click Listener" icon="hand-pointer" href="/calls/flutter/button-click-listener">
    Handle all button click events
  </Card>
</CardGroup>