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: Replacechatbackend.watchers.iowith the endpoint matching your project region. See Supported Regions for details.
Region Endpoint Europe (default) chatbackend.watchers.ioNorth America chatbackend.us.watchers.ioSouth America chatbackend.sa.watchers.ioAsia chatbackend.hk.watchers.ioAfrica chatbackend.za.watchers.io
Endpoint https://chatbackend.watchers.io/external/talker/role
Method POST
Request Parameters
| Parameter | Description |
|---|---|
| userId | The unencrypted ID of the user |
| roomId | The ID of the existing chat room |
| role | SPEAKER to grant the right to speak, GUEST to revoke it |
Required Headers
| Parameter | Description |
|---|---|
| x-api-key | Your public API key used for the project |
| Authorization | Bearer token that you can get from the back office (Admin panel / Settings / Bearer tokens) for back-to-back integrations |
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
| Code | Description |
|---|---|
| 400 | role must be SPEAKER or GUEST |
| 404 | User or room not found |
Updated about 1 hour ago
Did this page help you?