# Calls API

Placing, answering and reading calls on an agent account's number. The steps are in the Calls guide.

## Live calls

### POST /v1/accounts/:id/calls

```bash
curl -X POST https://api.getstack.run/v1/accounts/acct_123/calls \
  -H "Authorization: Bearer <access token>" -H "Content-Type: application/json" \
  -d '{"to":"+14155550123","greeting":"Hi, this is Acme Dental.","wait_seconds":20,"max_seconds":300}'
```

- to (E.164) is required. max_seconds is optional: it runs from 30 to 14,400 seconds, which is also the default and the longest Twilio allows. voice is optional: tts_provider (Google, Amazon or ElevenLabs), voice and language (a BCP-47 code such as en-US) for this call, over the account's own voice. reply_to_message is optional: the received message the call answers (see Send mail and texts).
- Without a brief, the agent holds the call. greeting is optional: the words spoken first, and without it nothing is spoken until the other side speaks; it has no length of STACK's, and the phone provider takes at most 4,000 characters of call instructions in all. wait_seconds (0 to 60, default 30) is how long the request waits, once the call is answered, for the other side's first finished sentence. Returns 201 with call and events.
- With on_behalf_of (a plain name, up to 60 letters, digits, spaces and . , & ' -) and brief (what the call is for and what to know), STACK holds the call with its own model. wait_seconds applies only when your agent runs the call. greeting is spoken only when your agent runs the call; on a call STACK holds, STACK opens with its own line. Returns 201 with the call at once.
- Any agent of the customer places a call with its own Passport under its Mission, or the owner places it without one.
- GET /v1/accounts/:id/calls?limit&cursor - the account's calls, newest first: { calls, next_cursor }. limit is 1 to 100, default 25.
- GET /v1/accounts/:id/calls/:callId - one call plus transcript: the transcript message, or null, and the lines said so far while the call runs. The agent's read marks it read.
- POST /v1/accounts/:id/calls/:callId/answer - answers a call ringing on the account's number. The body is the same as for a placed call, without to and reply_to_message, held either way. Returns 200 with call and events.
- POST /v1/accounts/:id/calls/:callId/decline - declines a ringing call. No body. Returns 200 with the call.
- POST /v1/accounts/:id/calls/:callId/say - on a call the agent holds: speaks text (leave it out to only wait), then waits up to wait_seconds for the other side's next finished sentence. Returns the call and every event since this caller's last call action. Not metered.
- POST /v1/accounts/:id/calls/:callId/keys - presses keys on the call: digits of 0-9, *, # and w (a pause). Not metered.
- POST /v1/accounts/:id/calls/:callId/voice - a new voice or language for the rest of the call: { voice }. Not metered.
- POST /v1/accounts/:id/calls/:callId/hang-up - hangs up a call, whoever holds it. STACK says nothing. Not metered.
- GET /v1/accounts/:id/calls/:callId/live - a WebSocket for a call the agent holds. The agent sends { type: text, token, last }, { type: keys, digits }, { type: voice, voice } and { type: hang_up }; each token is spoken as it arrives. It receives the call's events as they happen, and { type: error, code, message } for a message it cannot take.
- GET and PUT /v1/accounts/:id/phone/voice - the account's own call voice (tts_provider, voice, language) and voicemail_greeting. A field left out of the PUT is cleared. The owner, an admin or the account's own agent.
- say, keys and voice on a call STACK holds are CALL_HELD_BY_STACK (409); on a call that is not on the line, CALL_NOT_LIVE (409).

A call is `call_id`, `account_id`, `direction` (inbound, outbound), `state` (queued, ringing, in_progress, completed, failed, refused), `max_seconds`, `duration_seconds`, `end_reason`, `charged_cents`, `created_at`, `started_at`, `ended_at`, `held_by_stack` and `events`. A call that came in also has `decision` (answered, declined, voicemail, or `null` while it rings), `caller_attestation` (A, B or C as the carrier's STIR/SHAKEN check reports it, or `null`), `sender_tags` and `sender_resembles`, `caller` (the number calling, which anyone can fake, or `null` when it is withheld; it stays on the call after the ring, whatever became of it) and, while it rings, `answer_by` (when the ring runs out). A call the agent declined has `end_reason` `declined`.

A call the agent holds runs no model of STACK's and hears no words of STACK's: it opens with the `greeting` the agent gave, which the other side cannot talk over, or, without one, with silence until the other side speaks. The agent speaks with `say` or over the live stream, and hears the other side as `events`, each with `seq` and `at`: `heard` (a finished sentence), `keys`, `interrupted`, `paid_time_ends` and `ended`. A call STACK holds opens with STACK's line saying the other side is speaking with an AI on behalf of `on_behalf_of`, and STACK's model works from the brief, hangs up when the call is done, and, when the owner's `call_memory_access` memory setting allows it (on by default), searches the account's memory during the call; its transcript is written to memory afterwards. Each sentence the other side says is scanned for prompt injection: a flagged one is delivered with its flag, or withheld when your controls withhold it. Nothing said is changed or blanked. The call ends when it is hung up, when the other side hangs up, at `max_seconds`, when the wallet cannot pay the next 10 minutes, and as soon as the account, agent or Mission is revoked; a call STACK holds also ends, with STACK's goodbye, on a critical finding or when its model does not answer. Silence and repetition, as with hold music or a phone menu, do not end it. STACK sets no shorter limit: a call is paid for 10 minutes at a time. The first 10 minutes are held from the wallet when the call is placed and each next 10 about a minute before the paid time runs out. If the wallet cannot cover the next 10 minutes, or your spending limit for one action does not allow them, `events` gets a `paid_time_ends` entry with the seconds left (`in_seconds`), and the call ends when the paid time runs out with the end reason `budget_exhausted`. A call still running past its paid time is hung up. The minutes are charged at the billed duration. The transcript lands in the account's messages (channel `call`), scanned and kept like any inbound message, and the agent is woken when the call ends.

The first 10 minutes are held from the budget before the call, at Twilio's per-minute price to the destination plus the speech layer, and settle at Twilio's billed duration. On a call STACK holds, each model turn is charged at cost as it runs; a call the agent holds runs no model of STACK's.

A call to the account's number rings the agent for 30 seconds. The agent is woken with the source `incoming_call`, which needs no rule (a rule for it only gives the wake your own task), and the call has state `ringing`. The caller hears an ordinary ringing tone and no speech while the agent decides. The agent can answer, which goes on as a placed call does, held by the agent or, with a brief, by STACK; decline, which hangs up with nothing said; or do nothing, and the call goes to a transcribed voicemail when the ring runs out. Your do-not-contact list does not stop a call ringing. A caller on your blocked-callers list is turned away before it rings. No wake rate limits an incoming call: it takes no counter at all. With `ring_incoming_calls` off, with wake-ups off, in quiet hours, or when the agent has no live MCP session and no wake webhook, the call goes to voicemail at once and is never refused. If a wake that was accepted is refused when it is delivered (the meter refuses it, your decider denies it, or the agent is not an account agent), the caller waits the ring for nobody and the call goes to voicemail. A call to a paused account, or one the wallet or budget cannot cover, also goes to voicemail at once and is not refused, and so does one that meets a fault: STACK pays for that voicemail and nothing is charged to you. What it costs STACK counts toward the same monthly limit as texts STACK could not charge, and past that limit the account's phone number is released and the owner is told. Answering is one metered action and is put to your decider as `call.answer` with the caller's number, its attestation and `max_seconds`; declining is not metered. A call that is no longer ringing is refused with `CALL_NOT_RINGING` before it is metered or put to your decider. A caller becomes a known contact (sender tags) only after the agent answers a call whose attestation is A. The caller's number is kept with the call after the ring, whatever became of it (answered, declined, voicemail), so the agent can call a caller back; a voicemail's number also stays in the stored voicemail.

An answered call is paid for like a placed one: 10 minutes at a time, the next block held about a minute before the paid time runs out, with the same `paid_time_ends` entry in `events`, and the same hang-up for a call that runs past its paid time. A call that comes in is charged at cost for every started minute, from the moment it starts ringing. An answered call is charged the inbound rate for every started minute of the whole call, the ring included, and the speech relay rate for the minutes the relay ran. A declined call, or one the caller hangs up on while it rings, is charged the inbound rate only, and a voicemail the inbound rate plus transcription. All of it counts toward the month's included call minutes. While it rings, a call holds only the ring from the budget; the voicemail is held when it starts, and the first 10 minutes of the conversation are held when the agent answers.

- 403 RECIPIENT_OPTED_OUT - the number is on the do-not-contact list; details carry account_id. Texts to it are refused the same way.
- 422 DESTINATION_NOT_AVAILABLE - texts and calls to this number are not available: Twilio has no price for this destination (details.reason no_price), or does not allow them from this account's number (details.reason refused_by_twilio). Texts are refused the same way.
- 402 AGENT_BUDGET_EXCEEDED - the budget cannot cover the first 10 minutes of the call.
- 503 PROVIDER_CAPACITY_UNAVAILABLE - Twilio or OpenRouter itself declined for want of funds on STACK's account. Nothing is charged; retry in a few minutes.
- 502 ACCOUNT_CALL_FAILED - the call may have been placed. List the account's calls before retrying.
- 422 ACCOUNT_CALL_FAILED - the provider refused the call; nothing is charged. Do not retry it unchanged.
- 409 CALL_NOT_RINGING - on answer or decline: the call was answered, declined or sent to voicemail already, the ring ran out, or the caller hung up. It is not counted as an action. Read the call to see what happened to it.
