--- title: Room API updatedAt: 2026-04-02T15:34:31.000Z --- Fetch the complete documentation index at: https://docs.watchers.io/llms.txt # Room API You can also manage rooms via API. ## Create room > ⚠️ **Regional endpoints:** Replace `chatbackend.watchers.io` with the endpoint matching your project region. See [Supported Regions](https://docs.watchers.io/docs/supported-regions) for details. > | Region | Endpoint | > | :--- | :--- | > | Europe (default) | `chatbackend.watchers.io` | > | North America | `chatbackend.us.watchers.io` | > | South America | `chatbackend.sa.watchers.io` | > | Asia | `chatbackend.hk.watchers.io` | > | Africa | `chatbackend.za.watchers.io` | **Endpoint** `https://chatbackend.watchers.io/external/room`**Method** POST **Body** application/json | Parameter | Type | Required | Description | | ----------------- | ---------------------------- | -------: | --------------------------------------------------------------------------------------------- | | `roomId` | string | Yes | Unique room ID. | | `name` | string | Yes | Room name shown in the admin panel. | | `about` | string | Yes | Room description (e.g., used for scheduled rooms). | | `isSpeak` | boolean \| `"true"` \| `"1"` | No | Enables voice chat in the room. String values `"true"`/`"1"` are accepted and cast to `true`. | | `pic` | string | No | Optional. URL of the room picture/avatar. | | `startTime` | string (ISO 8601) | No | Planned room start time in UTC. Use format `YYYY-MM-DDTHH:mm:ss.sssZ`. | | `endTime` | string (ISO 8601) | No | Planned room end time in UTC. Use format `YYYY-MM-DDTHH:mm:ss.sssZ`. | | `streamUrl` | string | No | Optional. External livestream URL (Vimeo, YouTube Live, etc.). | | `sourceUrl` | string | No | Optional. Origin/ingest stream source (e.g., RTMP). | | `streamStartTime` | string (ISO 8601) | No | Optional. Actual/planned stream start time in UTC (`…Z`). | | `streamEndTime` | string (ISO 8601) | No | Optional. Actual/planned stream end time in UTC (`…Z`). | **Notes** * All time values must be in UTC (ISO 8601) with the Z suffix, e.g. 2025-08-14T09:00:00.000Z. * If startTime is provided, the room will be created with status SOON and will automatically switch to LIVE at the specified time. * If endTime is provided, the room will automatically switch to ENDED at the specified time. * If streamUrl is provided, an embedded video player will be shown in the room on the frontend. * If `sourceUrl` is provided, it is automatically converted to an embed-compatible URL. Supported platforms: **YouTube**, **Twitch**, **Kick**, **Facebook**, **Vimeo**. ```curl curl -X 'POST' 'https://chatbackend.watchers.io/external/room' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' -d '{ "roomId": "liveevent123", "name": "Live Conference", "about": "Annual keynote", "isSpeak": "true", "pic": "https://cdn.example.com/rooms/123.png", "startTime": "2025-08-14T09:00:00.000Z", "endTime": "2025-08-14T10:00:00.000Z", "streamUrl": "https://player.vimeo.com/video/12345678", "sourceUrl": "rtmp://origin.example.com/live/abc", "streamStartTime": "2025-08-14T09:02:15.000Z", "streamEndTime": "2025-08-14T09:58:44.000Z" }' ``` ## Get room **Endpoint** [https://chatbackend.watchers.io/external/room/:roomId](https://chatbackend.watchers.io/external/room/:roomId)**Method** GET > ℹ️ If a room with the given `roomId` does not exist, it will be **automatically created** with the project's default room name. This means the endpoint always returns a room object. **Path parameter** | Parameter | Type | Required | Description | | --------- | ------ | -------: | --------------- | | `roomId` | string | Yes | Unique room ID. | ```curl curl -X 'GET' 'https://chatbackend.watchers.io/external/room/321textroom321' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' ``` ## Update room **Endpoint** `https://chatbackend.watchers.io/external/room/:externalRoomId`**Method** PATCH **Body** application/json | Parameter | Type | Required | Description | | ----------------- | ----------------- | -------: | --------------------------------------------------------------------------------------------- | | `name` | string | No | Room name shown in the admin panel. | | `about` | string | No | Room description. | | `pic` | string | No | URL of the room picture/avatar. | | `streamUrl` | string | No | External livestream URL (Vimeo, YouTube Live, etc.). | | `sourceUrl` | string \| null | No | Origin/ingest stream source. Auto-converted to embed URL for YouTube, Twitch, Kick, Facebook, Vimeo. Pass `null` to clear. | | `streamStartTime` | string (ISO 8601) \| null | No | Planned stream start time in UTC. Pass `null` to clear. | | `streamEndTime` | string (ISO 8601) \| null | No | Planned stream end time in UTC. Pass `null` to clear. | | `enableModeration`| boolean | No | Enable or disable moderation for the room. | | `enableAntimat` | boolean | No | Enable or disable profanity filter for the room. | | `videoPosition` | string | No | Position of the video player in the room layout. | **Path parameter** | Parameter | Type | Required | Description | | ----------------- | ------ | -------: | -------------------- | | `externalRoomId` | string | Yes | Unique room ID. | ```curl curl -X 'PATCH' 'https://chatbackend.watchers.io/external/room/liveevent123' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' -d '{ "name": "Updated Room Name", "about": "New description", "streamUrl": "https://player.vimeo.com/video/99999999" }' ``` ## Enable Voice in room **Endpoint** [https://chatbackend.watchers.io/external/room/speak](https://chatbackend.watchers.io/external/room/speak)**Method** POST **Body** application/json
| Parameter | Type | Required | Description | | --------- | ---------------------------- | -------: | ---------------------------------------------------------------------------------------------------- | | `roomId` | string | Yes | Unique room ID. | | `isSpeak` | boolean \| `"true"` \| `"1"` | Yes | Enables or disables voice in the room. String values `"true"`/`"1"` are accepted and cast to `true`. | ```curl curl -X 'POST' 'https://chatbackend.watchers.io/external/room/speak' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' -d '{ "roomId": "321textroom321", "isSpeak": false }' ``` ## Change room status **Endpoint** [https://chatbackend.watchers.io/external/room/status](https://chatbackend.watchers.io/external/room/status)**Method** POST **Body** application/json | Parameter | Type | Required | Description | | ----------- | ------ | -------: | -------------------------------------------- | | `roomId` | string | Yes | Room ID. | | `status` | enum | Yes | One of: `LIVE`, `SOON`, `ENDED`, `DISABLED`, `RECORD`. | > To update `streamUrl` or other room properties along with a status change, use the [Update room](#update-room) (`PATCH`) endpoint. ```curl curl -X 'POST' 'https://chatbackend.watchers.io/external/room/status' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' -d '{ "roomId": "321textroom321", "status": "LIVE" }' ``` ## Delete room **Endpoint** [https://chatbackend.watchers.io/external/room/:roomId](https://chatbackend.watchers.io/external/room/:roomId)**Method** DELETE **Path parameter** | Parameter | Type | Required | Description | | --------- | ------ | -------: | --------------- | | `roomId` | string | Yes | Unique room ID. | ```curl curl -X 'DELETE' 'https://chatbackend.watchers.io/external/room/321textroom321' -H 'accept: application/json' -H 'Content-Type: application/json' -H 'x-api-key: {Api key of project from admin panel}' -H 'Authorization: Bearer {Bearer token from admin panel}' ``` *** ## Changelog (this version) * Added optional fields: pic, sourceUrl, streamStartTime, streamEndTime. * isSpeak made optional on Create room; accepts boolean or "true"/"1". * Clarified time format: ISO 8601 UTC YYYY-MM-DDTHH:mm:ss.sssZ. * Added PATCH /external/room/:externalRoomId endpoint for updating rooms. * Added `RECORD` to the list of valid room statuses. * Clarified that GET /external/room/:roomId auto-creates the room if it doesn't exist. * Documented `sourceUrl` auto-conversion to embed URL for supported platforms.