Join Session

Join CometChat Calls SDK v5 sessions on iOS 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 a container view in your layout and properly configured SessionSettings.

Container Setup

Create a container view where the call interface will be rendered. This can be done in your storyboard or programmatically:

Swift

// Programmatically
let callViewContainer = UIView()
callViewContainer.translatesAutoresizingMaskIntoConstraints = false
view.addSubview(callViewContainer)

NSLayoutConstraint.activate([
    callViewContainer.topAnchor.constraint(equalTo: view.topAnchor),
    callViewContainer.bottomAnchor.constraint(equalTo: view.bottomAnchor),
    callViewContainer.leadingAnchor.constraint(equalTo: view.leadingAnchor),
    callViewContainer.trailingAnchor.constraint(equalTo: view.trailingAnchor)
])

Storyboard

Add a UIView to your view controller and create an @IBOutlet:

@IBOutlet weak var callViewContainer: UIView!

The call UI will be dynamically added to this container when you join the session.

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.

Swift

let sessionId = "SESSION_ID"

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setDisplayName("John Doe")
    .setType(.video)
    .build()

CometChatCalls.joinSession(
    sessionID: sessionId,
    callSetting: sessionSettings,
    container: callViewContainer,
    onSuccess: { message in
        print("Joined session successfully")
    },
    onError: { error in
        print("Failed: \(error?.errorDescription ?? "")")
    }
)

Objective-C

NSString *sessionId = @"SESSION_ID";

SessionSettings *sessionSettings = [[[[CometChatCalls sessionSettingsBuilder]
    setDisplayName:@"John Doe"]
    setType:CallTypeVideo]
    build];

[CometChatCalls joinSessionWithSessionID:sessionId
                             callSetting:sessionSettings
                               container:self.callViewContainer
                               onSuccess:^(NSString * message) {
    NSLog(@"Joined session successfully");
} onError:^(CometChatCallException * error) {
    NSLog(@"Failed: %@", error.errorDescription);
}];

Parameter	Type	Description
sessionID	String	Unique identifier for the call session
callSetting	SessionSettings	Configuration for the session
container	UIView	Container view for the call UI
onSuccess	Closure	Closure called on successful join
onError	Closure	Closure called on failure

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.

Swift

let sessionId = "SESSION_ID"

CometChatCalls.generateToken(sessionID: sessionId, onSuccess: { token in
    print("Token generated: \(token ?? "")")
    // Store or use the token
}, onError: { error in
    print("Token generation failed: \(error?.errorDescription ?? "")")
})

Objective-C

NSString *sessionId = @"SESSION_ID";

[CometChatCalls generateTokenWithSessionID:sessionId 
                                 onSuccess:^(NSString * token) {
    NSLog(@"Token generated: %@", token);
    // Store or use the token
} onError:^(CometChatCallException * error) {
    NSLog(@"Token generation failed: %@", error.errorDescription);
}];

Parameter	Type	Description
sessionID	String	Unique identifier for the call session
onSuccess	Closure	Closure returning the generated token string
onError	Closure	Closure called on failure

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.

Swift

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setDisplayName("John Doe")
    .setType(.video)
    .build()

// Use the previously generated token
CometChatCalls.joinSession(
    callToken: generatedToken,
    callSetting: sessionSettings,
    container: callViewContainer,
    onSuccess: { message in
        print("Joined session successfully")
    },
    onError: { error in
        print("Failed: \(error?.errorDescription ?? "")")
    }
)

Objective-C

SessionSettings *sessionSettings = [[[[CometChatCalls sessionSettingsBuilder]
    setDisplayName:@"John Doe"]
    setType:CallTypeVideo]
    build];

// Use the previously generated token
[CometChatCalls joinSessionWithCallToken:generatedToken
                             callSetting:sessionSettings
                               container:self.callViewContainer
                               onSuccess:^(NSString * message) {
    NSLog(@"Joined session successfully");
} onError:^(CometChatCallException * error) {
    NSLog(@"Failed: %@", error.errorDescription);
}];

Parameter	Type	Description
callToken	String	Previously generated token string
callSetting	SessionSettings	Configuration for the session
container	UIView	Container view for the call UI
onSuccess	Closure	Closure called on successful join
onError	Closure	Closure called on failure

Complete Example

Swift

let sessionId = "SESSION_ID"

// Step 1: Generate token
CometChatCalls.generateToken(sessionID: sessionId, onSuccess: { [weak self] token in
    guard let self = self, let token = token else { return }
    
    // Step 2: Join with token
    let sessionSettings = CometChatCalls.sessionSettingsBuilder
        .setDisplayName("John Doe")
        .setType(.video)
        .build()

    CometChatCalls.joinSession(
        callToken: token,
        callSetting: sessionSettings,
        container: self.callViewContainer,
        onSuccess: { message in
            print("Joined session successfully")
        },
        onError: { error in
            print("Failed to join: \(error?.errorDescription ?? "")")
        }
    )
}, onError: { error in
    print("Token generation failed: \(error?.errorDescription ?? "")")
})

Objective-C

NSString *sessionId = @"SESSION_ID";

// Step 1: Generate token
[CometChatCalls generateTokenWithSessionID:sessionId 
                                 onSuccess:^(NSString * token) {
    // Step 2: Join with token
    SessionSettings *sessionSettings = [[[[CometChatCalls sessionSettingsBuilder]
        setDisplayName:@"John Doe"]
        setType:CallTypeVideo]
        build];

    [CometChatCalls joinSessionWithCallToken:token
                                 callSetting:sessionSettings
                                   container:self.callViewContainer
                                   onSuccess:^(NSString * message) {
        NSLog(@"Joined session successfully");
    } onError:^(CometChatCallException * error) {
        NSLog(@"Failed to join: %@", error.errorDescription);
    }];
} onError:^(CometChatCallException * error) {
    NSLog(@"Token generation failed: %@", error.errorDescription);
}];

Error Handling

Common errors when joining a session:

Error Code	Description
INIT ERROR	SDK not initialized - call init() first
AUTH TOKEN ERROR	User not logged in or auth token invalid
SESSION ID ERROR	Session ID is null or empty
API ERROR	Invalid call token or API error