Vorbal API Documentation

A Room is a shared audio resource identified by room_id. The full resource returned by the get method reflects room playback and a room Recording.

When to use

Use a Room to connect two or more Sessions in one conversation, such as a caller and an agent or a group call.

Room lifecycle

Use the events on this page to react to creation, confirmed deletion, membership changes, and room playback outcomes. Use the get method to reconcile the latest Room state after a missed event.

Methods

The list method returns a RoomSummary projection for each room. Use the get method when you need the complete Room representation shown below.

Enable member voice-activity events

Room voice-activity events are opt-in. To receive room.member.voice_activity_changed events when members start and stop talking, create the Room with voice_activity_events set to true:

1 {
2   "voice_activity_events": true
3 }

If you omit voice_activity_events or set it to false, the Room does not emit voice-activity events. The voice_activity_events property on the Room resource reports the value selected when the Room was created.

Resource representation

The Room resource

1 {
2   "created_at": "2023-01-01T00:00:00Z",
3   "member_count": 0,
4   "playback_operation_uuid": "string",
5   "playback_status": "stopped",
6   "playback_urls": [
7     "string"
8   ],
9   "playback_volume": 0,
10   "room_id": "string",
11   "voice_activity_events": true
12 }

Properties

created_atdatetimeRequired

member_countintegerRequired

Current number of members in the room.

playback_operation_uuidstringRequired

playback_statusenumRequired

Allowed values:

playback_urlslist of stringsRequired

playback_volumeintegerRequired0-200Defaults to 0

room_idstringRequired

voice_activity_eventsbooleanRequired

Whether member voice activity webhooks are enabled for this room.

Lifecycle, member, and playback events

Use room events to track room lifecycle, membership, and playback.

Event ordering: All room.* events for this Room, including events for different members, are delivered in production order. Failures hold this Room, not other Rooms. See Ordering guarantees.

Event envelope: Every room event also includes a timestamp: the emission time as an RFC 3339 / ISO 8601 UTC string, such as "2026-06-28T14:30:00.000Z". Treat this value as event-time metadata, not as a total-order key.

Delivery requests carry W3C trace context in their headers.

Member identity: Room membership events identify a member by session_uuid. For an inbound Session, the caller number is available on its session.created webhook. For an outbound Session, use the caller number from your dial request.

room.created

The platform emits this event when POST /api/v1/rooms creates a room.

Field	Type	Description
`event`	string	Always `"room.created"`. Required
`app_uuid`	string	Platform-generated identifier (`app_<uuid-v4>`) of the application that owns the room. Required
`room_id`	string	Unique room identifier. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.created",
4   "app_uuid": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "timestamp": "2026-06-28T14:30:00.000Z"
7 }

room.deleted

The platform emits this event after processing a room deletion request. DELETE /api/v1/rooms/{room_id} first returns 202 Accepted with {"room_id": "...", "status": "deleting"}. This response only acknowledges that the request was admitted.

The event arrives when the platform confirms that the room is gone (reason: "closed") or when that confirmation times out (reason: "timeout"). The reason field is always present.

Field	Type	Description
`event`	string	Always `"room.deleted"`. Required
`app_uuid`	string	Platform-generated identifier (`app_<uuid-v4>`) of the application that owned the room. Required
`room_id`	string	Unique room identifier. Required
`reason`	string	Why the room was torn down. One of `"closed"` (normal confirmed teardown) or `"timeout"` (the room was reaped after teardown confirmation never arrived). Always present. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.deleted",
4   "app_uuid": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "reason": "closed",
7   "timestamp": "2026-06-28T14:31:00.000Z"
8 }

room.member.joined

The platform emits this event after a call joins a room. The join is asynchronous: POST /api/v1/rooms/{room_id}/members returns 202 Accepted with status "joining" when it accepts the request. Wait for room.member.joined to confirm that the member is in the room.

Field	Type	Description
`event`	string	Always `"room.member.joined"`. Required
`session_uuid`	string	Session UUID of the joining member. Required
`room_id`	string	Room identifier. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.member.joined",
4   "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "timestamp": "2026-06-28T14:32:00.000Z"
7 }

room.member.left

The platform emits this event when a call leaves a room through DELETE /api/v1/rooms/{room_id}/members/{uuid}, is kicked, or hangs up.

The reason value identifies how the member left:

"hangup" means the member’s channel hung up.
"removed" means an explicit leave or kick through the room leave endpoint.
"orphan" means the platform detected that the member’s call had already gone away, typically because of a crash or dropped connection, and removed the stale membership. Treat this as an abnormal disconnect, not a clean leave.

Field	Type	Description
`event`	string	Always `"room.member.left"`. Required
`session_uuid`	string	Session UUID of the departing member. Required
`room_id`	string	Room identifier. Required
`reason`	string	Departure trigger. Consumers should accept any string for forward compatibility. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.member.left",
4   "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "reason": "hangup",
7   "timestamp": "2026-06-28T14:33:00.000Z"
8 }

room.member.muted

The platform emits this event when the room/mute command mutes a member.

Field	Type	Description
`event`	string	Always `"room.member.muted"`. Required
`session_uuid`	string	Session UUID of the muted member. Required
`room_id`	string	Room identifier. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.member.muted",
4   "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "timestamp": "2026-06-28T14:34:00.000Z"
7 }

room.member.unmuted

The platform emits this event when the room/unmute command unmutes a member.

Field	Type	Description
`event`	string	Always `"room.member.unmuted"`. Required
`session_uuid`	string	Session UUID of the unmuted member. Required
`room_id`	string	Room identifier. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.member.unmuted",
4   "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "timestamp": "2026-06-28T14:35:00.000Z"
7 }

room.member.voice_activity_changed

The platform emits this event when a room member’s voice activity detection (VAD) state changes. talking: true marks speech onset, and talking: false marks the return to silence. During an active conversation, expect frequent events and debounce them in your application.

VAD state is delivered via this webhook. The member object returned by GET /api/v1/rooms/{room_id}/members/{uuid} contains only {uuid, muted}.

Field	Type	Description
`event`	string	Always `"room.member.voice_activity_changed"`. Required
`session_uuid`	string	Session UUID of the member whose VAD state changed. Required
`room_id`	string	Room identifier. Required
`talking`	boolean	`true` when the member started talking, `false` when they stopped. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.member.voice_activity_changed",
4   "session_uuid": "acW68-f47ac10b-58cc-4372-a567-0e02b2c3d479",
5   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
6   "talking": true,
7   "timestamp": "2026-06-28T14:36:00.000Z"
8 }

room.playback.ended

The platform emits this terminal event exactly once when room playback completes naturally or stops through the API. For a multi-source playlist, the platform emits one event after every source completes, not one event per source. Playback failures and start-confirmation timeouts emit room.playback.failed instead.

Field	Type	Description
`event`	string	Always `"room.playback.ended"`. Required
`room_id`	string	Room identifier. Required
`operation_uuid`	string	Correlation identifier echoed from the originating play request’s `202 Accepted` response. An API stop does not replace it with the stop command’s correlation UUID. Required
`urls`	string[]	The complete original `urls` playlist from the room playback request, in request order. Required
`reason`	string	Why playback ended: `"completed"` when every source finished naturally, or `"stopped"` when interrupted through the API. Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.playback.ended",
4   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
5   "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
6   "urls": ["https://cdn.example.com/audio/announcement.wav"],
7   "reason": "completed",
8   "timestamp": "2026-06-28T14:37:00.000Z"
9 }

room.playback.failed

The platform emits this event when room playback fails. A failure occurs when the platform reports a playback error, any source in a multi-source playlist fails, or the platform does not receive start confirmation within 10 seconds.

One failed source fails the entire operation. Playback that starts within the 10-second window can continue for longer without failing. This event resets playback_status to "stopped" so the room can accept a new play.

Field	Type	Description
`event`	string	Always `"room.playback.failed"`. Required
`room_id`	string	Room identifier. Required
`operation_uuid`	string	Non-empty lowercase UUID v4 echoed from the originating play request’s `202 Accepted` response. Required
`urls`	string[]	The complete original `urls` playlist from the room playback request, in request order. Required
`error`	string	Coarse-grained error bucket. One of `"playback_error"` (the platform reported a playback failure) or `"playback_timeout"` (playback start was not confirmed within 10 seconds). Required

1 {
2   "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
3   "event": "room.playback.failed",
4   "room_id": "acW68-room-550e8400-e29b-41d4-a716-446655440000",
5   "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
6   "urls": ["https://cdn.example.com/audio/announcement.wav"],
7   "error": "playback_timeout",
8   "timestamp": "2026-06-28T14:38:00.000Z"
9 }

Triggered by

These events are produced by the following endpoints:

room.created — POST /rooms.
room.deleted — automatic: fires on confirmed teardown after DELETE /rooms/{room_id} returns 202 Accepted (reason: "closed"), or with reason: "timeout" if confirmation never arrives.
room.member.joined — POST /rooms/{room_id}/members (asynchronous).
room.member.left — DELETE /rooms/{room_id}/members/{uuid}, or automatic on hangup.
room.member.muted — room/mute.
room.member.unmuted — room/unmute.
room.member.voice_activity_changed — automatic: VAD state change.
room.playback.ended — terminal: fires once when playback completes naturally or is stopped through the API.
room.playback.failed — automatic: fires on a playback failure or when the playback watchdog times out.

For room deletion, member volume, and room playback play, pause, resume, stop, and volume commands, only the request’s 202 Accepted response acknowledges admission.