Documentation

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.

RegionEndpoint
Europe (default)chatbackend.watchers.io
North Americachatbackend.us.watchers.io
South Americachatbackend.sa.watchers.io
Asiachatbackend.hk.watchers.io
Africachatbackend.za.watchers.io

Endpoint https://chatbackend.watchers.io/external/roomMethod POST Body application/json

ParameterTypeRequiredDescription
roomIdstringYesUnique room ID.
namestringYesRoom name shown in the admin panel.
aboutstringYesRoom description (e.g., used for scheduled rooms).
isSpeakboolean | "true" | "1"NoEnables voice chat in the room. String values "true"/"1" are accepted and cast to true.
picstringNoOptional. URL of the room picture/avatar.
startTimestring (ISO 8601)NoPlanned room start time in UTC. Use format YYYY-MM-DDTHH:mm:ss.sssZ.
endTimestring (ISO 8601)NoPlanned room end time in UTC. Use format YYYY-MM-DDTHH:mm:ss.sssZ.
streamUrlstringNoOptional. External livestream URL (Vimeo, YouTube Live, etc.).
sourceUrlstringNoOptional. Origin/ingest stream source (e.g., RTMP).
streamStartTimestring (ISO 8601)NoOptional. Actual/planned stream start time in UTC (…Z).
streamEndTimestring (ISO 8601)NoOptional. 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 -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

ParameterTypeRequiredDescription
roomIdstringYesUnique room ID.
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

ParameterTypeRequiredDescription
namestringNoRoom name shown in the admin panel.
aboutstringNoRoom description.
picstringNoURL of the room picture/avatar.
streamUrlstringNoExternal livestream URL (Vimeo, YouTube Live, etc.).
sourceUrlstring | nullNoOrigin/ingest stream source. Auto-converted to embed URL for YouTube, Twitch, Kick, Facebook, Vimeo. Pass null to clear.
streamStartTimestring (ISO 8601) | nullNoPlanned stream start time in UTC. Pass null to clear.
streamEndTimestring (ISO 8601) | nullNoPlanned stream end time in UTC. Pass null to clear.
enableModerationbooleanNoEnable or disable moderation for the room.
enableAntimatbooleanNoEnable or disable profanity filter for the room.
videoPositionstringNoPosition of the video player in the room layout.

Path parameter

ParameterTypeRequiredDescription
externalRoomIdstringYesUnique room ID.
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


ParameterTypeRequiredDescription
roomIdstringYesUnique room ID.
isSpeakboolean | "true" | "1"YesEnables or disables voice in the room. String values "true"/"1" are accepted and cast to true.
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

ParameterTypeRequiredDescription
roomIdstringYesRoom ID.
statusenumYesOne 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 -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

ParameterTypeRequiredDescription
roomIdstringYesUnique room ID.
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 about 1 month ago

What’s Next