STACK
MENU
DOCS / THE ACCOUNT / CALLS

Calls

How an agent places a call, answers one that rings on its number, speaks on it or hands the conversation to STACK, and how voicemail works. What calls are and what they cost is on Services.

Before you start

The account needs a phone number: see Phone number and texts. Calls need no carrier approval. Any agent of yours can use the number, under its own Passport. An agent you set to read only can answer a call but cannot place one.

Place a call the agent holds

prompt
Call +1 415 555 0123 from the assistant account and book a table for two at seven.

The client calls stack_place_account_call, then stack_call_say for each thing it says. STACK runs no model on this call: the agent hears what is said as text and decides every word.

typescript
const turn = await stack.accounts.calls.place('acct_123', {
  to: '+14155550123',
  greeting: 'Hello, this is the assistant calling for Acme.',
}, { passportToken });
// turn.call.call_id, turn.events: what the other side said first

const next = await stack.accounts.calls.say('acct_123', turn.call.call_id, {
  text: 'I would like a table for two at seven tonight.',
}, { passportToken });

await stack.accounts.calls.hangUp('acct_123', turn.call.call_id, { passportToken });
  • place returns when the call is answered, with what the other side says first, or when it ends unanswered.
  • say speaks the text, waits up to wait_seconds for the reply and returns it.
  • stack_call_press_keys sends key tones, for a phone menu. stack_call_set_voice changes the voice for the rest of the call.
  • For a continuous stream, stack.accounts.calls.live() opens a WebSocket on the call.
  • From the terminal: account call, account call-say, account call-keys, account hang-up.

Let STACK hold the call

Give a brief and a name to speak for, and STACK's model has the whole conversation. The call returns at once, and the transcript is on the call when it ends.

typescript
await stack.accounts.calls.place('acct_123', {
  to: '+14155550123',
  on_behalf_of: 'Acme',
  brief: 'Confirm the booking for two at seven tonight. Ask for a window table.',
}, { passportToken });
  • on_behalf_of and brief go together. One without the other is refused.
  • The call opens by telling the other side they are speaking with an AI on behalf of that name.
  • The agent cannot speak on a call STACK holds. It can hang up and read it.

Answer a call that rings

A call to the number rings for 30 seconds and wakes the agent. No rule is needed. The agent answers, declines, or does nothing and lets it go to voicemail.

typescript
const turn = await stack.accounts.calls.answer('acct_123', callId, {
  greeting: 'Acme, this is the assistant.',
}, { passportToken });

// or
await stack.accounts.calls.decline('acct_123', callId, { passportToken });
  • The tools are stack_answer_account_call and stack_decline_account_call.
  • A call rings only an agent with an open MCP session or a webhook. Otherwise it goes straight to voicemail. It also goes to voicemail during quiet hours and while wake-ups are switched off.
  • To send every call to voicemail, turn ringing off: wake settings set <agent> --no-ring-incoming-calls.
  • A blocked caller is turned away before it rings. stack_add_blocked_caller adds a number; only the owner or an admin removes one.

Voicemail and the voice

bash
npx @getstackrun/cli account call-voice-settings acct_123 \
  --voicemail-greeting "You have reached Acme. Leave a message." --language en-US
  • A voicemail is transcribed and kept as a message of the account, on the channel voicemail. It is at most two minutes.
  • It wakes the agent only if you set a rule for voicemail. See Wake-ups.
  • The tools are stack_get_call_voice and stack_set_call_voice. A field left out when setting is cleared.

Read calls

stack_list_account_calls lists calls, newest first, and stack_get_account_call reads one with its transcript and how it ended. STACK keeps no audio.

What the other side says is content from outside. With controls on, a flagged line is withheld from the agent.

What counts as an action

Placing a call and answering one are one action each. Speaking, keys, hanging up, declining and reading are free. Minutes are charged from credit at the carrier's price, ten minutes at a time, and a call ends when the credit cannot cover the next ten.

When it is refused

  • 403 RECIPIENT_OPTED_OUT - the number is on the do-not-contact list.
  • 422 DESTINATION_NOT_AVAILABLE - the carrier has no price for the destination, or refuses it.
  • 409 CALL_NOT_RINGING - the call was answered, declined, sent to voicemail, or the caller hung up. It is not counted as an action.
  • 409 CALL_NOT_LIVE - the call is not answered yet, or has ended.
  • 409 CALL_HELD_BY_STACK - the agent tried to speak on a call STACK holds.
  • 502 ACCOUNT_CALL_FAILED - the call may have been placed. Read the call list before trying again.
  • 422 ACCOUNT_CALL_FAILED - the carrier refused the call. Trying again will not help.
  • 403 MESSAGES_READ_ONLY - you set this agent to read only. It cannot place a call.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as call.start, and as call.answer with the caller's number.

Reference

Every field is on Calls. Every tool is in the tool reference.

Calls | Docs