Speaker Role API

This guide explains how to grant a user the right to speak in a specific room — or take it away — using backend-to-backend communication. One endpoint assigns both roles: SPEAKER gives the user a microphone, GUEST takes it back.

⚠️

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

Endpoint https://chatbackend.watchers.io/external/talker/role

Method POST

Request Parameters

Required Headers

Example Request (cURL)

curl --location 'https://chatbackend.watchers.io/external/talker/role' \
--header 'x-api-key: {API KEY}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data '{
  "userId": "{unencrypted user id}",
  "roomId": "{existing room id}",
  "role": "SPEAKER"
}'

To revoke the role, send the same request with "role": "GUEST".

Example Success Response

HTTP/1.1 201 Created
{"success": true, "isNew": false}

isNew: true means the user has not joined the room yet — the role is saved and applies when they join. If the user is in the room, the change applies instantly. The request is safe to retry: sending it twice changes nothing.

Errors