| name | join-session |
| description | Join a CometChat call session using CometChatCalls.joinSession with SessionSettingsBuilder and Widget container. Use when joining calls, configuring session settings, voice vs video calls. Triggers on "join session", "join call", "start call", "SessionSettingsBuilder", "Widget". |
| inclusion | manual |
CometChat Calls SDK v5 — Join Session (Flutter)
Overview
Join a call session using CometChatCalls.joinSession(). Returns a Widget that renders the call UI. Supports joining by session ID (token generated internally) or by a pre-generated CallToken.
Prerequisites
- Calls SDK initialized and user logged in
- A valid session ID (from Chat SDK's
Call.sessionId or your backend)
Key Imports
import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
Implementation
Join with Session ID
final settings = SessionSettingsBuilder()
.setTitle("Team Meeting")
.startVideoPaused(false)
.startAudioMuted(false)
.build();
CometChatCalls.joinSession(
sessionId: sessionId,
sessionSettings: settings,
onSuccess: (Widget? callWidget) {
// Navigate to a screen that displays callWidget
Navigator.push(context, MaterialPageRoute(
builder: (_) => Scaffold(body: callWidget),
));
},
onError: (CometChatCallsException e) {
debugPrint("Failed to join: ${e.message}");
},
);
Join with Pre-Generated Call Token
// First generate a token
CometChatCalls.generateCallToken(sessionId,
onSuccess: (CallToken token) {
// Then join with the token
CometChatCalls.joinSession(
callToken: token,
sessionSettings: settings,
onSuccess: (Widget? callWidget) {
// Display callWidget
},
onError: (e) => debugPrint("Join failed: ${e.message}"),
);
},
onError: (e) => debugPrint("Token generation failed: ${e.message}"),
);
Voice Call vs Video Call
// Video call
final videoSettings = SessionSettingsBuilder()
.setType(SessionType.video)
.startVideoPaused(false)
.startAudioMuted(false)
.build();
// Voice call
final voiceSettings = SessionSettingsBuilder()
.setType(SessionType.audio)
.startVideoPaused(true)
.startAudioMuted(false)
.build();
Register Listeners After Joining
CometChatCalls.joinSession(
sessionId: sessionId,
sessionSettings: settings,
onSuccess: (Widget? callWidget) {
final session = CallSession.getInstance();
session?.addSessionStatusListener(myStatusListener);
session?.addButtonClickListener(myButtonListener);
// Navigate to call screen
},
onError: (e) => debugPrint("Join failed: ${e.message}"),
);
Full Call Screen Example
class CallScreen extends StatefulWidget {
final String sessionId;
const CallScreen({super.key, required this.sessionId});
@override
State<CallScreen> createState() => _CallScreenState();
}
class _CallScreenState extends State<CallScreen>
implements SessionStatusListeners, ButtonClickListeners {
Widget? _callWidget;
@override
void initState() {
super.initState();
_joinSession();
}
void _joinSession() {
final settings = SessionSettingsBuilder()
.setTitle("CometChat Call")
.startVideoPaused(false)
.startAudioMuted(false)
.build();
CometChatCalls.joinSession(
sessionId: widget.sessionId,
sessionSettings: settings,
onSuccess: (Widget? callWidget) {
setState(() => _callWidget = callWidget);
final session = CallSession.getInstance();
session?.addSessionStatusListener(this);
session?.addButtonClickListener(this);
},
onError: (e) {
debugPrint("Join failed: ${e.message}");
Navigator.pop(context);
},
);
}
@override
void onSessionLeft() => Navigator.pop(context);
@override
void onConnectionClosed() => Navigator.pop(context);
@override
void onLeaveSessionButtonClicked() {
CallSession.getInstance()?.leaveSession();
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: _callWidget ?? const Center(child: CircularProgressIndicator()),
);
}
}
Gotchas
joinSession returns a Widget? — embed it in your widget tree
- Provide exactly one of
sessionId or callToken, not both
- All participants must use the same session ID to join the same call
- Call
joinSession only after SDK is initialized and user is logged in
- Register listeners in the
onSuccess callback of joinSession
Sample App Reference
lib/screens/call_screen.dart — Call screen with Widget rendering
lib/screens/home_screen.dart — Session ID input and call initiation