# 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](/services).

## Before you start

The account needs a phone number: see [Phone number and texts](/docs/account/phone). 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

```text
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](/docs/api/account-calls). Every tool is in the [tool reference](/docs/mcp-tools).
