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
• Access to the CallSession instance

Get CallSession Instance

Session control methods are called on the CallSession singleton:

CallSession? callSession = CallSession.getInstance();

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

---

Check Session Status

Check if there is currently an active call session.

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

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

---

Leave Session

End your participation in the current call session.

await CallSession.getInstance()?.leaveSession();

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

Handling Session End

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

Flutter listeners are not lifecycle-aware. You must manually remove listeners in your widget’s dispose() method to prevent memory leaks.

---

End Call Session

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

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.

await CallSession.getInstance()?.raiseHand();

When you raise your hand, all participants receive the onParticipantHandRaised(Participant) callback on their ParticipantEventListener.

---

Lower Hand

Lower your previously raised hand.

await CallSession.getInstance()?.lowerHand();

When you lower your hand, all participants receive the onParticipantHandLowered(Participant) callback on their ParticipantEventListener.

---

Listen for Hand Raise Events

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

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:

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:

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:

SessionSettings sessionSettings = CometChatCalls.SessionSettingsBuilder()
    .setIdleTimeoutPeriod(300)  // 300 seconds (5 minutes)
    .build();

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

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

Session Status Listener

Handle all session lifecycle events

Button Click Listener

Handle all button click events