/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.Maps each screen-sharing user ID (string key) to an array of watcher user IDs. Empty object when nobody is sharing.
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
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
Response 200 — call state object, or null.
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
Response 200
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
Hostname of the preferred voice server (must be a value from
GET /api/calls/servers). Omit to start without a designated server.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
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
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
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
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
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
Server emits: update to all call members.
Server → Client Events (/bcalls namespace)
Server → Client Events (main / namespace)
These events are delivered on the main Socket.IO connection (/), not on /bcalls.