> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Join Session

> CometChat Calling SDK v5 - Join Session for Flutter

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 |

<Note>
  Both approaches require properly configured [SessionSettings](/calls/flutter/session-settings). The `joinSession` method returns a `Widget?` that you must place in your Flutter widget tree to render the call UI.
</Note>

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

```dart theme={null}
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.

```dart theme={null}
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            |

<Note>
  All participants joining the same call must use the same session ID.
</Note>

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

```dart theme={null}
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.

```dart theme={null}
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**

```dart theme={null}
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 |