Receive a voice call

When someone calls one of your Dial numbers, Dial answers automatically with an AI voice, using the number’s inboundInstruction as the agent’s system prompt. You set this when you provision the number and can change it any time with dial number set. There’s nothing to place and nothing to accept — the conversation runs on its own, and you observe it once it finishes.

How it works

• The call is answered for you. Inbound calls are always on for a provisioned number that has an inboundInstruction; the AI handles the conversation in real time. (Numbers provisioned before this field existed reject inbound calls until you set one.)
• The agent speaks the caller’s language. By default the language is detected from the caller’s country prefix, and the agent handles both it and en-US. To pin every inbound call to a single language, set the number’s inboundLanguage.
• You’re notified when the call ends. Dial emits a call.ended event carrying direction: inbound. To react while the call is still live — as it rings or is answered — listen for call.status_changed instead.
• The outcome looks like an outbound call. Once it ends, the call’s status, duration, and transcript are available.

Wait for an inbound call to end

Block until an inbound call wraps up, matching on direction so you skip your own outbound calls:

$
dial wait-for call.ended --field direction=inbound --timeout 120 --json

The CLI’s --field and --regex flags filter on event fields, so you only wake for inbound calls. To keep a continuous listener instead of a single wait, open a live stream.

Read the transcript

The call.ended event tells you a call finished; the transcript and other details live on the call record. The transcript is produced a moment later — when it’s ready, Dial fires a separate call.transcribed event for that call (only for calls that produced a transcript; cancelled / no-answer / failed calls emit call.ended only). Wait for call.transcribed if you need the transcript itself, then fetch the call. GET /api/v1/calls returns both inbound and outbound calls, newest first — filter on the direction field to keep just the inbound ones:

$
curl https://api.getdial.ai/v1/calls \
>
  -H "Authorization: Bearer sk_live_..."

Each call carries its status, duration, and transcript — the same fields you get for an outbound call.

Next