Calls
How Sautikit call records work: direction, states and recording lifecycle. Outbound calls cost KES 3.00 a minute billed per second; inbound calls are free.
· Updated 2026-11-10
How Sautikit call records work: direction, states and recording lifecycle. Outbound calls cost KES 3.00 a minute billed per second; inbound calls are free.
Every phone call in Sautikit is a call record with a direction, a sequence of states, and an optional recording. The cost is worked out when the call ends, from the answered time, and taken from your KES wallet as one ledger entry. Outbound calls cost KES 3.00 a minute, billed per second after answer; inbound calls are free.
| Direction | Description |
|---|---|
inbound | A caller dials your Sautikit number. Sautikit POSTs the call to the number's voice_callback_url |
outbound | Your application calls POST /v1/calls. Sautikit dials the other party |
In both directions Sautikit POSTs the call state to your voice_callback_url, and your server answers with voice actions that say what happens next.
A call moves through states in order. A call does not have to visit every state.
| Status | Meaning |
|---|---|
ringing | The other party is being alerted; no audio yet |
answered | Both parties are connected and audio is flowing |
completed | The call was answered and ended normally |
failed | A carrier or platform error prevented connection |
no_answer | The other party did not answer within the timeout |
busy | The other party returned a busy signal |
canceled | The caller hung up before the other party answered |
completed, failed, no_answer, busy and canceled are final. Only completed calls are charged.
Set the number's voice_callback_url with PUT /v1/numbers/{id}/routing.
const res = await fetch("https://api.sautikit.com/v1/calls", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAUTIKIT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: "+254720000000",
to: ["+254720000001"],
}),
});
const call = await res.json();from is one of your own active Sautikit numbers.to is an array of strings. The first number is dialled.voice_callback_url set on the from number and runs the voice actions your server returns.In that callback the person you dialled is clientDialedNumber. destinationNumber is your own number.
| Call | Price |
|---|---|
| Outbound, answered | KES 3.00 a minute, billed per second from the moment the call is answered |
| Inbound | Free |
| Unanswered, busy, failed or cancelled | Free |
A 25-second outbound call costs KES 1.25. A 90-second call costs KES 4.50. Ring time is not charged.
The charge is taken from your wallet when the call ends, as a call_debit ledger entry. POST /v1/calls returns 402 wallet.insufficient_funds when the balance is zero, and a live call is ended when the balance runs out. See Wallet and billing.
GET /v1/calls lists call records (direction, status, cost_minor, duration_seconds and more). Filter by status, direction, date range or part of the other party's number.GET /v1/calls/{id} returns one call.call.started, call.answered, call.completed, call.failed, call.recording.ready) are POSTed to the number's events_url. See Webhooks.Record a call by including a record verb in your voice actions, or by setting record on a dial verb.
Recording is free to make and uses your workspace's recording storage. Every workspace gets 100 MB free, with recordings kept for 24 hours. Paid sizes keep them for up to 60 days (see /pricing).
GET /v1/calls/{call_id}/recording returns a download link that lasts 15 minutes. Request a fresh link each time you need the file. Recordings older than your retention period are deleted, and when a workspace is over its size the oldest recordings are deleted first. The API returns 410 calls.recording_expired for those.