Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Call status webhooks

Ruut Voice notifies your StatusCallback URL whenever a call's state changes, so you can track calls in real time and drive your application's UI or analytics.

Configure

Set StatusCallback (and optional StatusCallbackMethod) when creating a call, or configure the callback on an incoming phone number so all inbound calls report status.
const call = await client.calls.create({
  to: "+2348000000001",
  from: "+2348000000002",
  twiml: "<Response><Say>Hello</Say></Response>",
  statusCallback: "https://app.example.com/calls/status",
  statusCallbackMethod: "POST",
});

Payload

The webhook is a form-encoded POST with the following parameters:
ParameterTypeDescription
CallSid optionalstringUnique identifier for the call.
AccountSid optionalstringYour account SID.
CallStatus optionalstringNew status: queued, ringing, in-progress, completed, busy, no-answer, failed, canceled.
From optionalstringCaller ID of the initiating party.
To optionalstringDestination of the call.
Direction optionalstringinbound, outbound-api, or outbound-dial.
ApiVersion optionalstringAPI version (2010-04-01).
CallDuration optionalstringCall duration in seconds (on terminal events).

Example request

POST /calls/status HTTP/1.1
Host: app.example.com

CallSid=CA2e9f6b3c&CallStatus=completed&From=%2B2348000000002
&To=%2B2348000000001&Direction=outbound-api&ApiVersion=2010-04-01
&CallDuration=42

Handling and verification

The platform call-status callback job currently sends this payload without an X-Twilio-Signature header. Do not use this callback alone as proof that a call changed state. Restrict access to the endpoint and verify important state against the authenticated Calls API.
Delivery errors are logged by the call-status job; it does not retry failed HTTP requests itself. Build reconciliation into your integration rather than relying on every notification arriving.
import { parseWebhook, isTerminalWebhook } from "@ruut/voice-sdk";

const payload = parseWebhook(req.body);
if (isTerminalWebhook(payload)) {
  // Confirm the state through the authenticated API before taking action.
}

Status values

See the Calls API status table for a full description of each status.