Join Session

Join CometChat Calls SDK v5 sessions on Flutter with session IDs, call tokens, participant setup, and in-call UI launch.

Join a call session using one of two approaches: the quick start method with a session ID, or the advanced flow with manual token generation for more control.

Overview

The CometChat Calls SDK provides two ways to join a session:

Approach	Best For	Complexity
Join with Session ID	Most use cases - simple and straightforward	Low - One method call
Join with Token	Custom token management, pre-generation, caching	Medium - Two-step process

Both approaches require properly configured SessionSettings. The joinSession method returns a Widget? that you must place in your Flutter widget tree to render the call UI.

Rendering the Call UI

Unlike native platforms that use a container view, the Flutter SDK returns a Widget? from the joinSession call. You must place this widget in your Flutter widget tree to display the call interface:

Widget? callWidget;

// After joining successfully, place the widget in your tree
if (callWidget != null) {
  // Use it in your build method, e.g.:
  // return Scaffold(body: callWidget!);
}

The returned widget renders the full call UI including video tiles, controls, and participant views. It behaves like any other Flutter widget and can be placed inside a Scaffold, Container, or any layout widget.

Join with Session ID

The simplest way to join a session. Pass a session ID and the SDK automatically generates the token and joins the call.

String sessionId = "SESSION_ID";

final sessionSettings = (SessionSettingsBuilder()
    ..setDisplayName("John Doe")
    ..setType(SessionType.video))
  .build();

CometChatCalls.joinSession(
  sessionId: sessionId,
  sessionSettings: sessionSettings,
  onSuccess: (Widget? callWidget) {
    debugPrint("Joined session successfully");
    // Place callWidget in your widget tree to render the call UI
  },
  onError: (CometChatCallsException e) {
    debugPrint("Failed: ${e.message}");
  },
);

Parameter	Type	Description
sessionId	String	Unique identifier for the call session
sessionSettings	SessionSettings	Configuration for the session
onSuccess	Function(Widget?)	Callback returning the call UI widget
onError	Function(CometChatCallsException)	Callback for error handling

All participants joining the same call must use the same session ID.

Join with Token

For scenarios requiring more control over token generation, such as pre-generating tokens, implementing custom caching strategies, or managing token lifecycle separately.

Step 1: Generate Token

Generate a call token for the session. Each token is unique to a specific session and user combination.

String sessionId = "SESSION_ID";

CometChatCalls.generateToken(
  sessionId: sessionId,
  onSuccess: (CallToken token) {
    debugPrint("Token generated: ${token.token}");
    // Store or use the token
  },
  onError: (CometChatCallsException e) {
    debugPrint("Token generation failed: ${e.message}");
  },
);

Parameter	Type	Description
sessionId	String	Unique identifier for the call session
onSuccess	Function(CallToken)	Callback returning the generated token
onError	Function(CometChatCallsException)	Callback for error handling

Step 2: Join with Token

Use the generated token to join the session. This gives you control over when and how the token is used.

final sessionSettings = (SessionSettingsBuilder()
    ..setDisplayName("John Doe")
    ..setType(SessionType.video))
  .build();

// Use the previously generated token
CometChatCalls.joinSession(
  callToken: generatedToken,
  sessionSettings: sessionSettings,
  onSuccess: (Widget? callWidget) {
    debugPrint("Joined session successfully");
    // Place callWidget in your widget tree to render the call UI
  },
  onError: (CometChatCallsException e) {
    debugPrint("Failed: ${e.message}");
  },
);

Parameter	Type	Description
callToken	CallToken	Previously generated token object
sessionSettings	SessionSettings	Configuration for the session
onSuccess	Function(Widget?)	Callback returning the call UI widget
onError	Function(CometChatCallsException)	Callback for error handling

Complete Example

String sessionId = "SESSION_ID";

// Step 1: Generate token
CometChatCalls.generateToken(
  sessionId: sessionId,
  onSuccess: (CallToken token) {
    // Step 2: Join with token
    final sessionSettings = (SessionSettingsBuilder()
        ..setDisplayName("John Doe")
        ..setType(SessionType.video))
      .build();

    CometChatCalls.joinSession(
      callToken: token,
      sessionSettings: sessionSettings,
      onSuccess: (Widget? callWidget) {
        debugPrint("Joined session successfully");
        // Place callWidget in your widget tree to render the call UI
      },
      onError: (CometChatCallsException e) {
        debugPrint("Failed to join: ${e.message}");
      },
    );
  },
  onError: (CometChatCallsException e) {
    debugPrint("Token generation failed: ${e.message}");
  },
);

Error Handling

Common errors when joining a session:

Error Code	Description
ERROR_COMETCHAT_CALLS_SDK_INIT	SDK not initialized - call init() first
ERROR_AUTH_TOKEN	User not logged in or auth token invalid
ERROR_CALL_SESSION_ID	Session ID is null or empty
ERROR_CALL_TOKEN	Invalid or missing call token
ERROR_JSON_EXCEPTION	Invalid session settings or response parsing error