API reference

Calls API

Create, list, fetch, and update calls. Outbound calls accept inline TwiML or a TwiML URL; every call reports status via webhooks.

Call resource

{
  "sid": "CA…",
  "account_sid": "AC…",
  "parent_call_sid": null,
  "phone_number_sid": "PN…",
  "to": "+2348000000001",
  "from": "+2348000000002",
  "status": "queued",
  "direction": "outbound-api",
  "duration": null,
  "start_time": null,
  "end_time": null,
  "uri": "/2010-04-01/Accounts/AC…/Calls/CA…"
}

Status values

Status	Description
`queued`	Ready and waiting (rate-limited).
`ringing`	Ringing the destination.
`in-progress`	Answered and in progress.
`completed`	Answered and ended normally.
`busy`	Destination busy.
`no-answer`	No answer or rejected.
`failed`	Could not be completed as dialed.
`canceled`	Canceled via API while ringing.

Create a call

POST/2010-04-01/Accounts/{AccountSid}/Calls

Create an outbound call. Provide either Twiml (inline) or Url (fetched at answer time).

Parameter	Type	Description
`To` required	`string`	The number to call in E.164 (e.g. +234…), or a SIP URI like `sip:agent-1001@sip.ruut.chat`.
`From` required	`string`	Your caller ID — an E.164 number you own, or an agent extension identifier.
`Twiml` optional	`string`	Inline TwiML instructions (max 4000 chars). Ignored if `Url` is present.
`Url` optional	`string`	Absolute URL returning TwiML. Fetched when the call connects.
`Method` optional	`string`	HTTP method for `Url`: `GET` or `POST`. Default `POST`.
`StatusCallback` optional	`string`	URL to receive call status webhooks.
`StatusCallbackMethod` optional	`string`	HTTP method for the callback: `GET` or `POST`. Default `POST`.

Example

curl -X POST "https://voice.ruut.chat/2010-04-01/Accounts/$RUUT_ACCOUNT_SID/Calls" \
  -u "$RUUT_ACCOUNT_SID:$RUUT_AUTH_TOKEN" \
  --data-urlencode "To=+2348000000001" \
  --data-urlencode "From=+2348000000002" \
  --data-urlencode "Twiml=<Response><Say>Hello!</Say></Response>"

Response — 201 Created

{ "sid": "CA…", "status": "queued", "direction": "outbound-api", "to": "+2348000000001" }

List calls

GET/2010-04-01/Accounts/{AccountSid}/Calls

Return calls for the account, optionally filtered.

Parameter	Type	Description
`To` optional	`string`	Filter by destination number.
`From` optional	`string`	Filter by caller ID.
`Status` optional	`string`	Filter by call status.
`Page` optional	`integer`	0-indexed page. Default 0.
`PageSize` optional	`integer`	Records per page (max 1000). Default 50.

Response

{
  "calls": [ { "sid": "CA…", "status": "completed", … } ],
  "page": 0, "page_size": 50,
  "next_page_uri": "/2010-04-01/Accounts/AC…/Calls?Page=1&PageSize=50"
}

Fetch a call

GET/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}

Return a single call resource.

Response — 200 OK

{ "sid": "CA…", "status": "completed", "duration": "42", … }

Update a call

POST/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}

Modify a live call — end it, cancel it, or redirect it to new TwiML.

Parameter	Type	Description
`Status` optional	`string`	Set to `completed` to end the call, or `canceled` to cancel while ringing.
`Url` optional	`string`	Redirect the call to a new TwiML URL.
`Twiml` optional	`string`	Redirect with inline TwiML.
`Method` optional	`string`	HTTP method for `Url`: `GET` or `POST`.