Join Session - CometChat Docs

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

​Overview

​Rendering the Call UI

​Join with Session ID

​Join with Token

​Error Handling

Overview

Rendering the Call UI

Join with Session ID

Join with Token

Error Handling