End a live call
Ends a live call immediately, tearing the connection down so a runaway agent or a call stuck on voicemail stops ringing and stops billing the moment this returns.
Ends a live call immediately, tearing the connection down so a runaway agent or a call stuck on voicemail stops ringing and stops billing the moment this returns. Before disconnecting, Dairo reads the call's final duration, transcript, and cost and settles them onto the row, then sets status to canceled. A call that was still queued and never dialed is canceled locally, so hanging up in that window is a true cancel-before-dial. A call that has already reached a terminal status returns 409. Requires the phone:call scope.
Scope: phone:call. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | The phone call's ID. |
Response
200 Success. Body: application/json, PhoneCall.
| Field | Type | Required | Description |
|---|---|---|---|
object | "phone_call" | yes | |
id | string (uuid) | yes | |
direction | "outbound", "inbound" | yes | outbound for calls placed with POST /v1/phone/calls, inbound for calls answered by a number's inbound agent. |
status | "queued", "initiating", "ringing", "in_progress", "completed", "failed", "no_answer", "busy", "canceled" | yes | Terminal: completed, failed, no_answer, busy, canceled. |
fromNumber | string | yes | |
toNumber | string | yes | |
instructions | string or null | no | |
greeting | string or null | no | |
voice | string or null | no | The Dairo Live voice id. |
model | string or null | no | Always dairo-live. |
language | string or null | no | |
maxDurationSeconds | integer or null | no | |
voicemailMessage | string or null | no | |
queuedAt | string (date-time) or null | no | |
startedAt | string (date-time) or null | no | |
answeredAt | string (date-time) or null | no | |
endedAt | string (date-time) or null | no | |
durationSeconds | integer or null | no | |
hangupCause | string or null | no | |
answeredBy | string or null | no | human or machine, from answering-machine detection. |
summary | string or null | no | |
notes | array of PhoneCallNote or null | no | Inbound calls: the caller's structured notes (tasks, notes, reminders, messages). |
costUsd | number or null | no | Billed per started minute: the $0.09/min Dairo Live rate plus the destination's telephony rate. Calls that never connect are free. |
error | string or null | no | |
metadata | object | no | |
idempotencyKey | string or null | no | |
createdAt | string (date-time) | yes |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
409 | The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Retrieve a call's recording
Returns a reference to the call's audio recording as { object: "phone_call.recording", callId, objectId }, where objectId is a Dairo storage object you download through storage's signed-link path rather than a raw, unauthenticated URL.
Mint a Slack "Add to Slack" install URL
Mints a signed https://slack.com/oauth/v2/authorize install URL — the "Add to Slack" button — for the account's one Slack app and returns it as url.