Core concepts
Three channels make up the whole platform. Once you know which one you are looking at, everything else. Which doc to read, which credential to use. Falls out of it.
The three channels
Section titled “The three channels”| Channel | Direction | Auth | Read next |
|---|---|---|---|
| REST API | You call us | API key (bearer) | API reference |
| Voice webhooks | We call you | HMAC signature | Voice webhooks |
| Event stream | We push to you, live | Short-lived stream token | Events & codes |
A fourth surface, the Browser SDK, is a thin client over the same webhook and event model. It just runs the “device” end of a call inside a tab instead of a physical phone.
The lifecycle of a call
Section titled “The lifecycle of a call”Every call. Inbound or outbound. Moves through the same three stages. The names in monospace
are what you will see in the payloads.
1. Something starts the call
Section titled “1. Something starts the call”A caller dials one of your numbers (inbound), you call
POST /calls/originate (outbound), or a browser or mobile end-user
places a call through the Browser SDK (also outbound). Either way, a Call
row is created and a call.initiated event fires.
2. We ask your server what to do
Section titled “2. We ask your server what to do”The instant the call needs instructions, we POST its details to a voice webhook URL.
Your server replies with a call-control document. XML verbs like <Say> and
<Dial>. And we execute it top to bottom. This can happen more than once per call: a
<Redirect> or a <Record action="..."> hands off to another webhook.
3. The call ends, and you get the full story three ways
Section titled “3. The call ends, and you get the full story three ways”When the call is over, all three channels agree, because they share the same dotted code:
- The event stream pushes a
call.completedorcall.failedevent withdata.reasonCode. - The Call object you fetch from the REST API has the same value in
reason_code. - If you are using status-callback webhooks, the terminal POST carries it too.
That means you never need three different parsers for three different shapes: END.0200 means
the same thing everywhere. See Events & codes for the full list.
Requests and responses, in short
Section titled “Requests and responses, in short”The full rules live on the API reference introduction. The short version:
- Everything is JSON in, JSON out, over HTTPS, at
https://api.sautipbx.com/api. - Every resource has a stable
uuid; calls also get a human-friendlysid. - Money is a KES decimal string, never cents. Timestamps are ISO-8601 UTC.
- Anything that spends money or places a call accepts an
Idempotency-Keyheader: see Rate limits & idempotency.