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 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

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/roomMethod 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/:roomIdMethod 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/:externalRoomIdMethod 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/speakMethod 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/statusMethod 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 (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/:roomIdMethod 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.

Updated 5 months ago