Place a voice call

Place an outbound voice call that an AI voice agent handles in real time. You provide an outbound instruction — the system prompt describing how the agent should behave — and a language for the conversation. The call is placed from one of your Dial numbers (fromNumberId).

$
dial call \
>
  --to +14155550123 \
>
  --outbound-instruction "You are confirming a dinner reservation for 7pm." \
>
  --language en-US \
>
  --from-number-id pn_123

The call returns immediately with a status of initiated. The conversation runs on its own; once it ends, the call’s final status, duration, and transcript are available via GET /api/v1/calls or by listening for the call.ended event. However the call ends — completed, failed, or cancelled — it emits exactly one call.ended carrying the terminal status, so a wait always resolves; a cancelled call additionally carries canceled: true.

Choosing the voice and prompt

You shape each call per request — the same number can run a reservation-confirming call and a survey call by sending a different outboundInstruction each time. (The number’s inboundInstruction is separate — it only governs calls into the number.)

• Outbound instruction — the system prompt for how the AI should behave on this call. This is the main lever you control.
• Language — a language tag such as en-US. The CLI defaults to en-US.
• Voice — each Dial number speaks with a preset voice, applied automatically; you don’t set it per call.

1
# Same number, different behavior per call.
2
await dial.make_call(
3
    to="+14155550123",
4
    from_number_id="pn_123",
5
    outbound_instruction="You are a friendly assistant running a 3-question survey.",
6
    language="en-US",
7
)

Transferring the call to a human

Pass a transferTo number (E.164) to have the agent forward the call to a person once the conversation reaches the right moment. The agent rides out hold music and automated menus, and cold-transfers the moment a real human is on the line — it won’t hand off to a recording or an IVR. The destination must differ from both to and the call’s from number.

When the hand-off happens, the call’s transferredAt timestamp is stamped; you can read it on the Call object via GET /api/v1/calls.

$
dial call \
>
  --to +14155550123 \
>
  --outbound-instruction "Greet the customer, then connect them to our agent." \
>
  --transfer-to +14155550100 \
>
  --from-number-id pn_123