Video calls
Video calls
The Video calls module manages browser-based meeting rooms backed by LiveKit. This is the layer you use when speakers should join through a web interface, when you need a webinar-style guest view, or when a room should later feed another pipeline such as egress, recording, or restreaming.
Compared with transport-first modules, a video call is centered around room policy and participant experience: media mode, participant limit, chat, screen sharing, webinar restrictions, and optional room recording behavior. The room lifecycle and the public token flow work together, so the API is best understood as room provisioning + join preparation.
The private control methods manage the room object itself. The public helper methods complete the join flow: findLKRoomNameById resolves the LiveKit room name and room restrictions, and createToken mints the participant token used by the browser client.
If room lifecycle actions are driven from an operator workflow, the create, start, and stop examples below also include ready-to-adapt vMix Script tabs. The join and token helpers remain browser-facing rather than vMix-specific.
Examples by preset
The create payload naturally breaks into a few practical room presets. In practice, the most useful shapes are a standard team room, a webinar-friendly room, a lightweight audio room, and a room that is expected to record a composite output.
{
"name": "Team standup room",
"user_id": "USER_ID",
"mediaType": "MEDIA_TYPE_VIDEO_AUDIO",
"max_participants": 20,
"allow_webinar_mode": false,
"allow_chat": true,
"allow_share_screen": true,
"record": false,
"record_mode": "ROOM_COMPOSITE_GRID",
"active": true
}{
"name": "Guest webinar room",
"user_id": "USER_ID",
"mediaType": "MEDIA_TYPE_VIDEO_AUDIO",
"max_participants": 200,
"allow_webinar_mode": true,
"allow_chat": true,
"allow_share_screen": false,
"record": false,
"record_mode": "ROOM_COMPOSITE_GRID",
"active": true
}{
"name": "Audio briefing room",
"user_id": "USER_ID",
"mediaType": "MEDIA_TYPE_AUDIO_ONLY",
"max_participants": 50,
"allow_webinar_mode": false,
"allow_chat": true,
"allow_share_screen": false,
"record": false,
"record_mode": "ROOM_COMPOSITE_GRID",
"active": true
}{
"name": "Recorded speaker room",
"user_id": "USER_ID",
"mediaType": "MEDIA_TYPE_VIDEO_AUDIO",
"max_participants": 50,
"allow_webinar_mode": true,
"allow_chat": true,
"allow_share_screen": true,
"record": true,
"record_mode": "ROOM_COMPOSITE_SPEAKER",
"active": true
}Workflow examples
These scenarios explain why a room exists in a production design, not just what the create payload looks like.
Create a managed speaker room and distribute browser join links
Use a video call when guests should join from a browser instead of publishing through OBS or a standalone encoder. The room object becomes the stable meeting identity, while findLKRoomNameById and createToken power the actual speaker join step.
Run a webinar room with restricted audience behavior
When guests need a view-only or restricted-experience path, keep webinar mode enabled and decide whether chat and screen sharing should remain available. This keeps the room useful for public events without exposing full speaker privileges to everyone.
Use a room as the upstream for a downstream output
A room can feed another stage in the pipeline, such as a room composite egress or another module that depends on the meeting output. In that setup, the room object defines participant policy while the output side handles delivery.
Public join flow
The public side of the module is intentionally small but important. Resolve the room first, then mint the participant token.
findLKRoomNameById: maps your Callaba room id to the active LiveKit room name and returns room-level flags such as webinar mode, chat, screen sharing, and record settings.createToken: creates a participant token for the resolved room. The browser client uses that token to join.
Create a new managed video call room in Callaba Engine.
This method provisions the room object that the browser join flow depends on. The payload focuses on room policy rather than transport details: media mode, participant capacity, webinar restrictions, chat, screen sharing, recording behavior, and whether the room should be active right after creation.
Examples by preset are especially useful here because most real rooms fall into a few recognizable patterns: standard team rooms, webinar-style rooms, audio-only rooms, and recorded rooms for speaker-focused output.
Workflow-oriented use cases: create a stable browser room for speakers, pre-provision a webinar room before the event starts, or define a recorded room whose layout should later be used for composite output.
Use this when a small or medium team should join with full audio and video, chat, and screen sharing enabled.
Use this when the room should support guest or view-only behavior and keep speaker privileges more controlled.
Use this when the meeting should behave more like an audio briefing or lightweight discussion space.
Use this when the room should later feed a composite output workflow and recording is part of the room policy.
Dashboard label: Room Name.
Human-readable room name. The dashboard validates this field and shows the same character guidance used elsewhere in the product: A-Z, a-z, 0-9, and -.
Owner id of the room. The dashboard store does not ask for this explicitly because the backend injects the authenticated user id before create and update calls.
Dashboard label: Media type.
Supported room modes are MEDIA_TYPE_VIDEO_AUDIO, MEDIA_TYPE_VIDEO_ONLY, and MEDIA_TYPE_AUDIO_ONLY.
Dashboard label: Max participants.
Maximum number of participants allowed to join the meeting simultaneously.
Controls whether the room should support webinar-style guest behavior in addition to the speaker path.
Controls whether chat should remain available in the browser room experience.
Controls whether speakers should be allowed to share their screen inside the room.
Controls whether the room should be treated as record-enabled.
Composite recording mode for the room. Real product values include ROOM_COMPOSITE_GRID, ROOM_COMPOSITE_AND_CHAT, and ROOM_COMPOSITE_SPEAKER.
Dashboard label: Enabled.
Controls whether the room should be active right after provisioning.
Mongo-style identifier of the room object.
Convenience alias for _id.
Stored room name and owning user id.
Media mode and participant limit stored on the room object.
Room-level participant experience flags returned with the room object.
Recording intent and composite mode stored for the room.
Room runtime and timestamp fields returned by the backend.
The model exposes success: true as a virtual field in successful responses.
Return the total number of video call rooms visible to the authenticated user.
Use this with paginated listings when the dashboard or your own control panel needs the current room count before fetching room objects.
Total number of video call rooms currently visible to the authenticated user.
Return the list of video call rooms for the current user.
This is the normal control-plane listing method for management views. It returns the room objects themselves, not a wrapped envelope, so the response can be rendered directly as a room list.
Optional page size for the list query.
Optional offset for paginated listing.
Optional sort descriptor. The dashboard store defaults to { created: 1 }.
Optional filter object forwarded to the backend query.
The backend returns a bare array of room objects, not a wrapped object.
Load one video call room by its id.
Use this when an operator opens the room editor, when you need to inspect the current room policy, or before deciding whether to start, stop, or update the room.
Identifier of the room you want to load.
The backend returns the stored room object for the requested id.
Update an existing video call room.
The update contract mirrors create. In practice this is how you change room policy over time: webinar behavior, chat availability, screen sharing, recording mode, participant limit, or the active-state intent.
Identifier of the room being updated.
The update contract mirrors create and reuses the same room-policy fields.
The backend returns the updated room object.
Start a video call room by id.
Starting the room marks it active and ensures the LiveKit room exists for the join flow. Use this when the room should begin accepting participants again after being paused or prepared ahead of an event.
Identifier of the room to start.
The backend returns { success: true } when the room has been activated and the room-creation path completes successfully.
Stop a video call room by id.
Stopping the room marks it inactive and tears down the active LiveKit room state behind it. This is the operational counterpart to start when the meeting should no longer accept new participants.
Identifier of the room to stop.
The backend returns { success: true } when the room has been stopped successfully.
Remove a video call room by id.
This removes the stored room object and also attempts to clean up the runtime room and egress state tied to it. Use remove when the room should disappear from the control plane entirely, not just be stopped.
Identifier of the room to delete.
The backend returns { success: true } after the room object and linked runtime state have been removed.
Resolve the active LiveKit room name for a Callaba video call room id.
This is the first public helper in the browser join flow. Besides the room name itself, it returns the room-level behavior flags that the join UI needs to know, such as webinar mode, chat, screen sharing, and whether recording is enabled.
Identifier of the Callaba room you want to resolve into the active LiveKit room name.
LiveKit room name used by the browser join flow.
Room behavior flags needed by the join UI.
Recording-related room flags returned alongside the lookup result.
Indicates whether the active room could be resolved.
Create a participant token for the browser join flow.
This is the second public helper in the room-entry path. After the client knows the active LiveKit room name, it requests a participant token for a speaker, guest, or hidden egress-style participant and uses that token to join the room.
Callaba room id for the conference being joined.
Resolved LiveKit room name returned by findLKRoomNameById.
Stable participant identity used in the token grant.
Optional display name shown in the room UI.
Optional hidden-mode flag used for egress-style or non-visible participants.
Optional token used only when a hidden participant should be allowed into a room whose webinar-mode policy would otherwise block that path.
LiveKit participant token used by the browser client to join the room.
Echoes the LiveKit room name used for the token grant.
Indicates whether the token was created successfully.