joinSession static method

Future<void> joinSession({
  1. String? sessionId,
  2. CallToken? callToken,
  3. required SessionSettings sessionSettings,
  4. required dynamic onSuccess(
    1. Widget?
    ),
  5. required dynamic onError(
    1. CometChatCallsException
    ),
})

Joins a call session using either a sessionId or a pre-generated callToken.

Provide exactly one of sessionId or callToken:

  • With sessionId: The SDK generates a token internally, then joins.
  • With callToken: Joins directly using the provided token.

sessionSettings is required and configures the call UI/behavior.

Example usage:

// Join with session ID (token generated automatically)
CometChatCalls.joinSession(
  sessionId: 'my-session-123',
  sessionSettings: settings,
  onSuccess: (widget) { /* render widget */ },
  onError: (error) { /* handle error */ },
);

// Join with a pre-generated call token
CometChatCalls.joinSession(
  callToken: token,
  sessionSettings: settings,
  onSuccess: (widget) { /* render widget */ },
  onError: (error) { /* handle error */ },
);

Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6

Implementation

static Future<void> joinSession({
  String? sessionId,
  CallToken? callToken,
  required SessionSettings sessionSettings,
  required Function(Widget?) onSuccess,
  required Function(CometChatCallsException) onError,
}) async {
  // Validate that exactly one of sessionId or callToken is provided
  if (sessionId == null && callToken == null) {
    onError(CometChatCallsException(
      ErrorCodeConstants.codeInvalidParameter,
      'Either sessionId or callToken must be provided',
      'Provide exactly one of sessionId or callToken to joinSession',
    ));
    return;
  }

  if (sessionId != null && callToken != null) {
    onError(CometChatCallsException(
      ErrorCodeConstants.codeInvalidParameter,
      'Provide either sessionId or callToken, not both',
      'Only one of sessionId or callToken should be provided to joinSession',
    ));
    return;
  }

  if (sessionId != null) {
    // Path 1: Join with session ID — generate token first
    final sessionIdError = InputValidator.validateSessionId(sessionId);
    if (sessionIdError != null) {
      onError(sessionIdError);
      return;
    }

    try {
      generateCallToken(
        sessionId,
        onSuccess: (CallToken token) {
          _joinWithCallToken(token, sessionSettings, onSuccess, onError);
        },
        onError: onError,
      );
    } catch (e) {
      onError(CometChatCallsException.wrapUnhandled(e));
    }
  } else {
    // Path 2: Join with pre-generated call token
    _joinWithCallToken(callToken!, sessionSettings, onSuccess, onError);
  }
}