Voice Calls API: Real-Time Audio in Clody Branches

Bots are not allowed on any voice-call REST endpoint (/api/calls/get, /api/calls/servers, /api/calls/token). Calls to these routes with a bot Authorization header return 400 Not Authorized. Voice is a human-session-only feature.

Clody voice calls combine a small set of REST endpoints with a dedicated Socket.IO namespace (/bcalls). You use REST to look up available voice servers, fetch the current call state for a Branch, and obtain a short-lived token for the WebRTC layer. Everything else — starting, joining, leaving, and managing calls — happens over Socket.IO so participants receive updates in real time.

The Call State Object

All endpoints and events that describe an active call return the same call state object.

integer

The Branch ID this call belongs to.

array of integers

User IDs of participants who are currently in the call.

array of integers

User IDs of Branch members who were notified of the call but have not yet joined.

array of integers

User IDs of participants whose microphone is currently muted.

Maps each screen-sharing user ID (string key) to an array of watcher user IDs. Empty object when nobody is sharing.

string | null

Hostname of the voice server this call is running on (e.g. "moscow.clody.lol"). null if no server was specified when the call started.

REST Endpoints

List voice servers — `GET /api/calls/servers`

Returns the available voice server regions. Call this before starting a call to let the user choose their preferred region. Response 200

{
  "Moscow, RU": "moscow.clody.lol",
  "Tel Aviv, IS": "israil.clody.lol"
}

The keys are human-readable region labels; the values are the hostnames you pass as server_addr when emitting start_call.

Get call state — `POST /api/calls/get`

Returns the current call state for a Branch, or null if there is no active call. Request body

integer

required

Branch ID to check.

Response 200 — call state object, or null.

{
  "id": 12,
  "members": [5, 9],
  "waiting": [14],
  "mic_off": [9],
  "sharing_screen": {},
  "server_addr": "moscow.clody.lol"
}

Error responses

Status	Meaning
`403`	You are not a member of this Branch.

Get a call token — `POST /api/calls/token`

Issues a short-lived token that authorises you to connect to the voice server’s WebRTC layer for the specified Branch call. Request body

integer

required

Branch ID of the active call you want to join.

Response 200

{ "token": "eyJ..." }

string

A signed token to pass to the voice server when establishing your WebRTC connection.

Error responses

Status	Meaning
`403`	You are not a member of this Branch.

Fetch a fresh token each time you join a call. Tokens are scoped to your user ID and the specific Branch, so you cannot reuse a token across calls.

Socket.IO — Main `/` Namespace

Client → Server Events

`start_call`

Starts a new voice call in a Branch. Emit this event on the main / namespace (not /bcalls). Every other Branch member is placed in the waiting list and receives a new_call event. Payload

integer

required

Branch ID to start the call in.

string

Hostname of the preferred voice server (must be a value from GET /api/calls/servers). Omit to start without a designated server.

Server emits back to you: started_call with the new call state object.
Server emits to other members: new_call with the call state object. Errors emitted: error — if the Branch already has an active call, if you are not a member, or if server_addr is not a recognised server.

Socket.IO — `/bcalls` Namespace

Connect to the /bcalls namespace with your session cookie before emitting any in-call events. The server automatically adds you to the Socket.IO room for any call you are already a member of.

Client → Server Events

`join_call`

Moves you from the waiting list into members, effectively picking up the call. Payload

integer

required

Branch ID of the call to join.

Server emits: update to all current call members with the updated call state.

`leave_call`

Removes you from the call. If you are the last member, the call ends and all waiting users receive a stop_call event. Payload

integer

required

Branch ID of the call to leave.

Server emits: update to remaining members, or stop_call to any waiting users if the call ends.

`reject_call`

Removes you from the waiting list without joining the call. Payload

integer

required

Branch ID of the call to reject.

Server emits: update to current call members reflecting the updated waiting list.

`mic_toggle`

Mutes or unmutes your microphone. Your user ID is added to or removed from the mic_off array accordingly. Payload

integer

required

Branch ID of the call.

boolean

required

true to mute; false to unmute.

Server emits: update to all call members.

`toggle_screen_sharing`

Starts or stops your screen share. When you start sharing, an empty watcher list is created for you. When you stop, the entry is removed. Payload

integer

required

Branch ID of the call.

boolean

required

false to start sharing; true to stop sharing.

Server emits: update to all call members.

`toggle_watching_screen_sharing`

Registers or unregisters you as a watcher of another participant’s screen share. Payload

integer

required

Branch ID of the call.

boolean

required

false to start watching; true to stop watching.

integer

required

User ID of the participant whose screen you want to watch or stop watching.

Server emits: update to all call members.

Server → Client Events (`/bcalls` namespace)

Event	Payload	When it fires
`update`	Call state object	Any change to call state — members joining/leaving, mic toggles, screen sharing changes.
`error`	`{ cause: string }`	An action you attempted failed (e.g. not a member, call already exists).

Server → Client Events (main `/` namespace)

These events are delivered on the main Socket.IO connection (/), not on /bcalls.

Event	Payload	When it fires
`new_call`	Call state object	A call started in a Branch you belong to — you are being called.
`started_call`	Call state object	Confirmation that the call you just started is active. Sent in response to emitting `start_call` on the main namespace.
`stop_call`	`{ id: integer }`	The call in Branch `id` has ended (last member left).

Auth & Users

Branches

Picnics

Interactions

Real-Time

Bots

Voice Calls API: Real-Time Audio in Clody Branches

The Call State Object

REST Endpoints

List voice servers — `GET /api/calls/servers`

Get call state — `POST /api/calls/get`

Get a call token — `POST /api/calls/token`

Socket.IO — Main `/` Namespace

Client → Server Events

`start_call`

Socket.IO — `/bcalls` Namespace

Client → Server Events

`join_call`

`leave_call`

`reject_call`

`mic_toggle`

`toggle_screen_sharing`

`toggle_watching_screen_sharing`

Server → Client Events (`/bcalls` namespace)

Server → Client Events (main `/` namespace)

​The Call State Object

​REST Endpoints

​List voice servers — GET /api/calls/servers

​Get call state — POST /api/calls/get

​Get a call token — POST /api/calls/token

​Socket.IO — Main / Namespace

​Client → Server Events

​start_call

​Socket.IO — /bcalls Namespace

​Client → Server Events

​join_call

​leave_call

​reject_call

​mic_toggle

​toggle_screen_sharing

​toggle_watching_screen_sharing

​Server → Client Events (/bcalls namespace)

​Server → Client Events (main / namespace)

The Call State Object

REST Endpoints

List voice servers — `GET /api/calls/servers`

Get call state — `POST /api/calls/get`

Get a call token — `POST /api/calls/token`

Socket.IO — Main `/` Namespace

Client → Server Events

`start_call`

Socket.IO — `/bcalls` Namespace

Client → Server Events

`join_call`

`leave_call`

`reject_call`

`mic_toggle`

`toggle_screen_sharing`

`toggle_watching_screen_sharing`

Server → Client Events (`/bcalls` namespace)

Server → Client Events (main `/` namespace)