API reference

Events & codes

Watch calls happen in real time over a WebSocket. Every event carries a stable code — the same code appears on the event stream, in webhooks, and on the call record — so you switch on one value everywhere.

Connecting

The socket is authenticated with a short-lived stream token, not your API key. Mint one on your backend, hand it to the browser, then open the socket:

// 1. your backend mints a token (keeps the API key private)
//    POST /api/stream/token  ->  { "token": "...", "ttl_seconds": 60 }

// 2. the browser opens the socket with that token
const ws = new WebSocket(
  "wss://sauti-pbx.services.co.ke/api/stream?token=" + token
);
ws.onmessage = (e) => {
  const ev = JSON.parse(e.data);
  console.log(ev.code, ev.event, ev.sid);
};

The token only lasts long enough to open the socket (see ttl_seconds), so mint it right before connecting. The socket is scoped to your account — you only ever receive your own events.

The event envelope

Every frame is a small JSON object. Keys that would be empty are simply left out:

{
  "code":      "CALL.0200",        // stable machine code — switch on this
  "event":     "call.answered",    // human-readable name
  "sid":       "call_...",         // present when the event is about a call
  "customPayload": { },              // present only if you set one on the call
  "createdAt": "2026-07-05T10:00:00Z",
  "data":      { }                    // code-specific fields
}

A call that ends carries its terminal outcome inside data — for example a call.completed event whose data includes reasonCode: "END.0200". That same reason code is stored on the call record (as reason_code).

Event codes

Codes pushed on the stream (and, where durable delivery matters, as webhooks). The numeric suffix mirrors familiar SIP/HTTP semantics so the meaning is guessable.

Rows marked ◆ are also terminal reason codes: you receive them as an event and they explain why a call ended.

Reason codes

Terminal call outcomes. Every call record's reason_code is one of these, and it is what a call.completed / call.failed event carries in data.reasonCode.