Placing, answering and reading calls on an agent account's number. The steps are in the Calls guide.
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}'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.