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, participant 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 participant voice-activity events

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

{
  "voice_activity_events": true
}

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

{
  "created_at": "2023-01-01T00:00:00Z",
  "participant_count": 0,
  "playback_operation_uuid": "string",
  "playback_status": "stopped",
  "playback_urls": [
    "string"
  ],
  "playback_volume": 0,
  "room_id": "string",
  "voice_activity_events": true
}

Properties

created_atdatetimeRequired

participant_countintegerRequired

Current number of participants in the room.

playback_operation_uuidstringRequired

playback_statusenumRequired

Allowed values:

playback_urlslist of stringsRequired

playback_volumeintegerRequired0-200Defaults to 0

Current room playback volume (0-200). A newly created room reports 0 until a room playback volume command sets an explicit value.

room_idstringRequired

voice_activity_eventsbooleanRequired

Whether participant voice activity webhooks are enabled for this room.

Lifecycle, participant, and playback events

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

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

Event envelope: Every room event also includes the required aud and timestamp fields. aud identifies the application that should receive the signed event. timestamp is the emission time as an RFC 3339 / ISO 8601 UTC string, such as "2026-06-28T14:30:00.000Z". Treat timestamp as event-time metadata, not as a total-order key.

Delivery requests carry W3C trace context in their headers.

Participant identity: Room participant events identify a participant 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	Application identifier. Required
`room_id`	string	Unique room identifier. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.created",
  "app_uuid": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "timestamp": "2026-06-28T14:30:00.000Z"
}

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	Application identifier. 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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.deleted",
  "app_uuid": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "reason": "closed",
  "timestamp": "2026-06-28T14:31:00.000Z"
}

room.participant.joined

The platform emits this event after a new participant joins a Room. POST /api/v1/rooms/{room_id}/participants returns 202 Accepted with status "joining" when it starts a join. Wait for room.participant.joined to confirm that the participant is in the Room. If the Session is already in the Room, the endpoint returns 200 OK with status "already_joined" and does not emit a new room.participant.joined event.

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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.joined",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "timestamp": "2026-06-28T14:32:00.000Z"
}

room.participant.left

The platform emits this event when a Session leaves a Room through DELETE /api/v1/rooms/{room_id}/participants/{uuid}, moves to another Room, hangs up, or is removed during stale-session cleanup.

The reason value identifies how the participant left:

"hangup" means the participant’s channel hung up.
"removed" means an explicit removal through the Room leave endpoint or a move to another Room.
"orphan" means the platform detected that the participant’s call had already gone away, typically because of a crash or dropped connection, and removed the stale participation. Treat this as an abnormal disconnect, not a clean leave.

Field	Type	Description
`event`	string	Always `"room.participant.left"`. Required
`session_uuid`	string	Session UUID of the departing participant. Required
`room_id`	string	Room identifier. Required
`reason`	string	Departure trigger. One of `"hangup"`, `"removed"`, or `"orphan"`. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.left",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "reason": "hangup",
  "timestamp": "2026-06-28T14:33:00.000Z"
}

room.participant.muted

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

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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.muted",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "timestamp": "2026-06-28T14:34:00.000Z"
}

room.participant.unmuted

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

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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.unmuted",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "timestamp": "2026-06-28T14:35:00.000Z"
}

room.participant.volume_changed

The platform emits this terminal success event after every direction requested by POST /v1/sessions/{uuid}/room/volume succeeds. For direction: "both", the event arrives only after both volume assignments succeed.

Field	Type	Description
`event`	string	Always `"room.participant.volume_changed"`. Required
`session_uuid`	string	Session UUID of the participant. Required
`room_id`	string	Room identifier. Required
`operation_uuid`	string	Correlation identifier from the accepted volume command. Required
`volume`	integer	Applied volume level from `1` through `9`. Required
`direction`	string	Requested direction: `"to_participant"`, `"from_participant"`, or `"both"`. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.volume_changed",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
  "volume": 7,
  "direction": "both",
  "timestamp": "2026-06-28T14:35:30.000Z"
}

room.participant.volume_change_failed

The platform emits this terminal failure event after a confirmed full or partial failure of an accepted participant-volume command. The direction lists show which assignments succeeded before the final result and which assignments failed.

Field	Type	Description
`event`	string	Always `"room.participant.volume_change_failed"`. Required
`session_uuid`	string	Session UUID of the participant. Required
`room_id`	string	Room identifier. Required
`operation_uuid`	string	Correlation identifier from the accepted volume command. Required
`volume`	integer	Requested volume level from `1` through `9`. Required
`direction`	string	Requested direction: `"to_participant"`, `"from_participant"`, or `"both"`. Required
`reason`	string	Stable failure category. Always `"execution_failed"`. Required
`applied_directions`	string[]	Directions applied before the final result. Each value is `"to_participant"` or `"from_participant"`. Required
`failed_directions`	string[]	Directions whose execution failed. Each value is `"to_participant"` or `"from_participant"`. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.volume_change_failed",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
  "volume": 7,
  "direction": "both",
  "reason": "execution_failed",
  "applied_directions": ["from_participant"],
  "failed_directions": ["to_participant"],
  "timestamp": "2026-06-28T14:35:45.000Z"
}

room.participant.voice_activity_changed

Emitted when a participant starts (talking: true) or stops (talking: false) speaking. These events can be frequent, so debounce them in your application.

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

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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.participant.voice_activity_changed",
  "session_uuid": "00000000-0000-4000-8000-000000000101",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "talking": true,
  "timestamp": "2026-06-28T14:36:00.000Z"
}

room.playback.file.ended

The platform emits this event when a finite URL file that started playing in a room completes or playback is stopped through the API. A single-file request also produces this event. For a playlist, use file_index to identify the entry in the original urls array; url repeats the original URL supplied for that entry. A file that fails or never starts does not produce this event. The file event arrives before the operation’s terminal room.playback.ended or room.playback.failed event. With loop: true, each completed repeat produces another file event with the same file_index and url.

Field	Type	Description
`event`	string	Always `"room.playback.file.ended"`. Required
`room_id`	string	Room identifier. Required
`operation_uuid`	string	Correlation identifier from the original play request’s `202 Accepted` response. Required
`file_index`	integer	Zero-based index in the original `urls` array. Required
`url`	string	Original URL supplied for this entry. Required
`reason`	string	`"completed"` when the file finishes, or `"stopped"` when playback is stopped through the API. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.playback.file.ended",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
  "file_index": 0,
  "url": "https://cdn.example.com/audio/announcement.wav",
  "reason": "completed",
  "timestamp": "2026-10-18T14:37:00.000Z"
}

room.playback.ended

This terminal event is emitted once after all files in the play request finish or playback is stopped through the API. It describes the whole play operation. Individual finite files that started have their own room.playback.file.ended events. Failures and start-confirmation timeouts produce 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 original file `urls` playlist in request order. For a live stream, this is `[]`; use `operation_uuid` to correlate the event with its play request. Required
`reason`	string	Why playback ended: `"completed"` when every source finished naturally, or `"stopped"` when interrupted through the API. Required

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.playback.ended",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
  "urls": ["https://cdn.example.com/audio/announcement.wav"],
  "reason": "completed",
  "timestamp": "2026-06-28T14:37:00.000Z"
}

room.playback.failed

The platform emits this event when room playback fails. A failure occurs when the platform reports a playback error, any audio file in the request’s urls array fails to play, or the platform does not receive start confirmation within 10 seconds.

One failed audio file 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 original file `urls` playlist in request order. For a live stream, this is `[]`; use `operation_uuid` to correlate the event with its play request. 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

{
  "aud": "app_3f9c0b2a-7d41-4e8b-9f12-2a6c5d0e7b34",
  "event": "room.playback.failed",
  "room_id": "00000000-0000-4000-8000-000000000301",
  "operation_uuid": "d4e5f6a7-b8c9-4123-8567-89abcdef0123",
  "urls": ["https://cdn.example.com/audio/announcement.wav"],
  "error": "playback_timeout",
  "timestamp": "2026-06-28T14:38:00.000Z"
}

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.participant.joined — POST /rooms/{room_id}/participants (asynchronous).
room.participant.left — DELETE /rooms/{room_id}/participants/{uuid}, a move to another Room, automatic hangup, or stale-session cleanup.
room.participant.muted — room/mute.
room.participant.unmuted — room/unmute.
room.participant.volume_changed — terminal success after all requested volume directions succeed.
room.participant.volume_change_failed — terminal failure after a full or partial volume execution failure.
room.participant.voice_activity_changed — automatic: VAD state change.
room.playback.file.ended — a finite URL file that started playing completes or playback is stopped through the API.
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, participant volume, and room playback play, pause, resume, stop, and volume commands, only the request’s 202 Accepted response acknowledges admission.