---
title: Speaker Role API
updatedAt: 2026-09-05T16:42:52.304Z
---

Fetch the complete documentation index at: https://docs.watchers.io/llms.txt

# 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](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/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)

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

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