Appearance
Calls
Calls placed from the server, their history and timelines.
Call history, newest first
GET /v1/calls
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
identity? | query | string | Either side — the identity that placed the call, or one it rang. 1–200 characters. |
from? | query | string | The identity that placed the call. 1–200 characters. |
to? | query | string | An identity the call rang. 1–200 characters. |
status? | query | string | One of ringing, active, completed, no_answer, rejected, cancelled, failed. |
type? | query | string | One of direct, queue, meeting. |
queue? | query | string (uuid) | |
createdAfter? | query | string (date-time) | Created at or after this instant. |
createdBefore? | query | string (date-time) | Created before this instant. |
Response 200 — A page of calls.
| Field | Type | Description |
|---|---|---|
data | Call[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
| Status | Code |
|---|---|
| 400 | validation_failed, token_ttl_too_long |
| 401 | unauthenticated, token_expired, token_replayed, token_not_yet_valid |
| 403 | permission_denied, app_suspended, quota_exhausted |
| 429 | rate_limited |
| 500 | internal |
Place a call from the server
POST /v1/calls
Creates the room, the call and its invite, and rings — with nobody connected to place it. from takes its seat by joining the returned roomSid with a token scoped to it; the invitee answers as for any call. Rings one invitee today: to of more than one is 501 unsupported. With queue instead of to, the queue's attempt loop chooses whom to ring, one member at a time; the answer then has no invites yet, and a queue that does not exist is 404. The answer is the call as it then stands — already no_answer when nobody could be rung. Counts against its own rate bucket, since each one rings a phone.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: calls, 60 a minute
Request body application/json
| Field | Type | Description |
|---|---|---|
from | string | The identity the call is placed for. 1–200 characters. |
to? | string[] | The identities to ring. One today; more is 501 unsupported. 1–16 items. |
queue? | string | A queue’s slug or id, instead of to. 1–200 characters. |
requiredSkills? | string[] | With queue, the skills a member must hold to be offered the call. At most 16 items. |
media? | string | One of audio, video. Default "audio". |
ringTimeoutSec? | integer | 5–120. Default 30. |
roomMetadata? | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
Response 201 — The call, with its invites.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^CS_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
type | string | One of direct, queue, meeting. |
from | string | The identity that placed the call. |
to | string[] | The identities it rang. |
media | string | One of audio, video. |
status | string | One of ringing, active, completed, no_answer, rejected, cancelled, failed. |
queueId | string (uuid) | null | |
createdAt | string (date-time) | |
ringStartedAt | string (date-time) | null | |
answeredAt | string (date-time) | null | |
endedAt | string (date-time) | null | |
durationSec | integer | null | From answer to end; null for a call never answered. |
billableSec | integer | null | The participants' billable seconds between answer and end, summed and rounded up to the tenant's increment — about twice durationSec for a 1:1 call, and 0 for one whose media never flowed. Null for a call never answered. |
endReason | string | null | Null until the call ends. The call's own record, the same for both sides: hangup when the identity that placed the call hung up, remote_hangup when the other side did. Every reason is described with the call.ended webhook. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
invites | Invite[] | On a read of one call, and in the answers of POST /v1/calls and …/end. |
Errors
Read one call, with every invite it sent
GET /v1/calls/{sid}
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 200 — The call.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^CS_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
type | string | One of direct, queue, meeting. |
from | string | The identity that placed the call. |
to | string[] | The identities it rang. |
media | string | One of audio, video. |
status | string | One of ringing, active, completed, no_answer, rejected, cancelled, failed. |
queueId | string (uuid) | null | |
createdAt | string (date-time) | |
ringStartedAt | string (date-time) | null | |
answeredAt | string (date-time) | null | |
endedAt | string (date-time) | null | |
durationSec | integer | null | From answer to end; null for a call never answered. |
billableSec | integer | null | The participants' billable seconds between answer and end, summed and rounded up to the tenant's increment — about twice durationSec for a 1:1 call, and 0 for one whose media never flowed. Null for a call never answered. |
endReason | string | null | Null until the call ends. The call's own record, the same for both sides: hangup when the identity that placed the call hung up, remote_hangup when the other side did. Every reason is described with the call.ended webhook. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
invites | Invite[] | On a read of one call, and in the answers of POST /v1/calls and …/end. |
Errors
The call's timeline, oldest first
GET /v1/calls/{sid}/events
Everything recorded about the call's room — the support-ticket endpoint.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string | |
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
Response 200 — A page of events.
| Field | Type | Description |
|---|---|---|
data | CallEvent[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
End a call
POST /v1/calls/{sid}/end
A call still ringing is cancelled as its caller would cancel it (cancelled), and then its room ends. Ending an ended call changes nothing and answers the same.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 200 — The call, as it now stands.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^CS_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
type | string | One of direct, queue, meeting. |
from | string | The identity that placed the call. |
to | string[] | The identities it rang. |
media | string | One of audio, video. |
status | string | One of ringing, active, completed, no_answer, rejected, cancelled, failed. |
queueId | string (uuid) | null | |
createdAt | string (date-time) | |
ringStartedAt | string (date-time) | null | |
answeredAt | string (date-time) | null | |
endedAt | string (date-time) | null | |
durationSec | integer | null | From answer to end; null for a call never answered. |
billableSec | integer | null | The participants' billable seconds between answer and end, summed and rounded up to the tenant's increment — about twice durationSec for a 1:1 call, and 0 for one whose media never flowed. Null for a call never answered. |
endReason | string | null | Null until the call ends. The call's own record, the same for both sides: hangup when the identity that placed the call hung up, remote_hangup when the other side did. Every reason is described with the call.ended webhook. One of hangup, remote_hangup, no_answer, rejected, cancelled, busy, reconnect_timeout, transport_failure, evicted, quota_exhausted, node_failure, max_duration. |
metadata | object | The tenant's own JSON, at most 4 096 bytes as UTF-8. The platform never reads it. |
invites | Invite[] | On a read of one call, and in the answers of POST /v1/calls and …/end. |
Errors