Getting started

Core concepts

Three channels make up the whole platform. Once you know which one you're looking at, everything else — which doc to read, which credential to use — falls out of it.

The three channels

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

Every call — inbound or outbound — moves through the same three stages. The names in monospace are what you'll see in the payloads.

1. Something starts the call

A caller dials one of your numbers (inbound), you call POST /calls/originate (outbound), or a browser/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

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

When the call is over, all three channels agree, because they share the same dotted code:

• The event stream pushes a call.completed or call.failed event with data.reasonCode.
• The Call object you fetch from the REST API has the same value in reason_code.
• If you're 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 reason codes for the full list.

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://sauti-pbx.services.co.ke/api.
• Every resource has a stable uuid; calls also get a human-friendly sid.
• Money is a KES decimal string, never cents. Timestamps are ISO-8601 UTC.
• Anything that spends money or places a call accepts an Idempotency-Key header — see Rate limits & idempotency.