---
title: "Create a room"
method: POST
path: "/rooms"
tags: ["Rooms"]
---

# Create a room

`POST /rooms`

## Request body

- RoomCreateRequest
  - `id` string, required — Custom room ID (auto-generated UUID if omitted)
  - `webhook_url` string, uri — Route all events for this room exclusively to this URL instead of global webhooks.
  - `webhook_secret` string — HMAC-SHA256 signing secret for the per-room webhook.
  - `app_id` string — Application identifier. Carried through to all events for this room. Use to filter the WebSocket event stream by app.
  - `sample_rate` integer — Mixer sample rate in Hz. Allowed values: 8000, 16000, 48000. Default: 16000.

## Response `201`

Room created

- Room
  - `instance_id` string — Instance identifier
  - `id` string, required — Room identifier
  - `app_id` string — Application identifier for event stream filtering.
  - `sample_rate` integer, required — Mixer sample rate in Hz (8000, 16000, or 48000).
  - `participants` Leg[], required — Legs currently in this room
    - `instance_id` string — Instance identifier
    - `id` string, required — Unique leg identifier (UUID)
    - `type` 'sip_inbound' | 'sip_outbound' | 'webrtc' | 'whatsapp_in' | 'whatsapp_out' | 'websocket_in' | 'websocket_out' | 'moq_in' | 'livekit_publish' | 'livekit_participant', required — Leg type
    - `state` 'ringing' | 'early_media' | 'connected' | 'held' | 'hung_up', required — Leg state
    - `room_id` string — Room ID if the leg is in a room, empty otherwise
    - `muted` boolean, required — Whether the leg is muted (cannot be heard by others)
    - `deaf` boolean, required — Whether the leg is deaf (cannot hear others)
    - `accept_dtmf` boolean, required — Whether the leg receives DTMF digits broadcast from other legs in the same room. Defaults to true.
    - `held` boolean, required — Whether the call is on hold (SIP legs only)
    - `role` string — Routing role used by the room's audio routing matrix (e.g. "customer", "agent", "supervisor"). Empty string means unroled (full mesh).
    - `app_id` string — Application identifier for event stream filtering.
    - `sip_headers` object — Deprecated: X-* headers from the inbound INVITE. Only present on sip_inbound legs. Use `headers` for new code; it carries the same map plus surfaces handshake headers for websocket legs.
    - `headers` object — Custom protocol headers exposed by the leg's transport — X-/P- headers from a SIP INVITE, the WebSocket upgrade request, or supplied at outbound dial time.
    - `custom_data` unknown

## Other responses

- `409` — Room ID already exists

## Changes

- **2026-09-01** `89ff267f0958` — 1 info
  - added the optional property `participants/items/custom_data` to the response with the `201` status
- **2026-06-08** `2c5256108234` — 3 warning
  - added the new `livekit_participant` enum value to the `participants/items/type` response property for the response status `201`
  - added the new `livekit_publish` enum value to the `participants/items/type` response property for the response status `201`
  - added the new `moq_in` enum value to the `participants/items/type` response property for the response status `201`
- **2026-05-21** `98f1f6130e2c` — 1 info
  - added the optional property `participants/items/role` to the response with the `201` status
- **2026-05-13** `97117ab6a5c4` — 2 warning, 1 info
  - added the new `websocket_in` enum value to the `participants/items/type` response property for the response status `201`
  - added the new `websocket_out` enum value to the `participants/items/type` response property for the response status `201`
  - added the optional property `participants/items/headers` to the response with the `201` status
- **2026-04-29** `6a046e0fe815` — 2 warning
  - added the new `whatsapp_in` enum value to the `participants/items/type` response property for the response status `201`
  - added the new `whatsapp_out` enum value to the `participants/items/type` response property for the response status `201`

[Full history](https://skmtc.dev/voiceblender/apis/voiceblender-api/changes/rooms/post.md)

---

[API](https://skmtc.dev/voiceblender/apis/voiceblender-api.md) · [All operations](https://skmtc.dev/voiceblender/apis/voiceblender-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/voiceblender/voiceblender-api/revisions/89ff267f0958/schema)