Outbound Calls

Dial any allowed number from one of your workspace numbers and the agent takes the call the moment the callee picks up. Outbound calls are ordinary agent sessions with direction: "outbound": they appear in session history, they are stored and analyzed under the same per-agent settings as any other conversation, and they trigger the same webhooks plus one extra, phone_call.dial_finished, that reports how the dial attempt ended.

Phone numbers

Get a number that can place calls.

Webhooks

Get the dial outcome pushed to your backend.

Dynamic variables

Personalize the call with per-call values.

Place a call

Get a number that supports outbound

Any purchased number can place calls. An imported BYO number can too, once its termination is configured; the number object reports this as supports_outbound. The number you dial from is the caller ID the callee sees.

Publish your agent

Outbound calls run the agent’s published configuration, not the draft. Publish before dialing.

Create the phone call

curl --request POST https://api.fish.audio/v1/agent/phone-calls \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: order-4711-reminder-1" \
  --data '{
    "agent_id": "YOUR_AGENT_ID",
    "phone_number_id": "YOUR_PHONE_NUMBER_ID",
    "to_number": "+14155550123"
  }'

The request returns 201 as soon as the dial is dispatched:

{ "session_id": "9c41f0d2e8a34b7f", "status": "queued" }

This endpoint requires an API key; there is no anonymous variant. See the API reference for the full schema.

Request fields

Field	Description
`agent_id`	Required: the agent that speaks on the call. Must have a published version.
`phone_number_id`	Required: the workspace number to dial from.
`to_number`	Required: the destination in E.164, for example `+14155550123`.
`dynamic_variables`	Optional: per-call values for `{{placeholders}}` in the agent’s configured text, same rules as session creation. Up to 50 entries.
`overrides`	Optional: replace whole configuration fields for this call, subject to the agent’s override allowlist.
`metadata`	Optional: your own JSON object, returned verbatim on session reads and in webhook payloads. Never interpreted.
`llm_extra_body`	Optional: JSON object (at most 16 KB) forwarded to a custom LLM endpoint on every request as `fishaudio_extra_body`. Ignored on platform-model agents.

The session’s time and timezone context resolves from the destination number when the agent has no fixed timezone configured, so “tomorrow morning” means the callee’s morning.

Retry safely with an Idempotency-Key

Outbound dials spend money and ring real phones, so put an Idempotency-Key header on every create. For 24 hours, repeating the same key with the same body returns the call already placed instead of dialing again. The same key with a different body is refused with 422 idempotency_key_reuse, and a retry that races an in-flight first attempt gets 409 idempotency_key_conflict; back off and retry the same request. If the create fails with an ambiguous network error, retry with the same key: you get the placed session back if the first attempt went through.

The dial outcome

Ringing is never billed; metering starts when the callee answers. A call that is never answered is not billed and not analyzed. You learn how the dial ended in either of two ways:

Push: subscribe to the phone_call.dial_finished webhook. It fires exactly once per outbound call, whether or not anyone picked up, before call.ended.
Poll: read GET /v1/agent/sessions/{session_id} until dial_status is set.

curl https://api.fish.audio/v1/agent/sessions/9c41f0d2e8a34b7f \
  --header "Authorization: Bearer $FISH_API_KEY"

Two session fields carry the outcome:

Field	Values
`dial_status`	`answered`, `busy`, `no_answer`, or `failed`. `null` while the call is still ringing, and on inbound calls.
`answered_by`	Deprecated. Answering-machine detection has been removed, so new calls report `unknown` once answered (`null` before). Older sessions may still carry `human` or `voicemail`.

On outbound sessions the attribution fields are person-centric: caller_number is the human you dialed and dialed_number is your workspace number. The same values reach the agent as {{system.caller_number}} and {{system.dialed_number}}, so a CRM lookup tool can use https://crm.example.com/contacts?phone={{system.caller_number}} without a per-call variable; see System variables. Everything else about the session (transcript, recording, post-call analysis, call.ended and call.analyzed webhooks, hang-up via POST /v1/agent/sessions/{session_id}/end) works exactly as for inbound calls.

Allowed destinations

Calls from purchased numbers can reach fixed-line and mobile numbers in the US, Canada, Japan, the UK, Italy, Australia and Mexico. Premium-rate numbers (for example UK 09, Japan 0570 and 0990, Australia 19, Mexico 900) and other service numbers such as toll-free lines are refused. The phone surcharge depends on the country and on whether the number is fixed-line or mobile; see the pricing page. Calls from imported BYO numbers dial out through your own trunk, so the country allowlist does not apply. Numbers that live on the platform can never be dialed, so an agent cannot call another agent’s number.

Errors

Unlike most Agents API errors, phone-call errors carry a machine-readable reason alongside the message:

{
  "status": 422,
  "reason": "destination_not_allowed",
  "message": "Outbound calls are limited to numbers in the US, Canada, Japan, the UK, Italy, Australia and Mexico"
}

Status	Reason	Cause
`402`	`insufficient_credit`	Out of API credit; top up first.
`403`	`outbound_disabled`	Outbound calling is switched off for this workspace.
`404`	`number_not_found`, `agent_not_found`	The id doesn’t exist, isn’t yours, or the number was released.
`409`	`agent_not_published`	Publish the agent first.
`409`	`idempotency_key_conflict`	A request with this key is still in flight; back off and retry the same request.
`422`	`number_provider_unsupported`, `number_termination_missing`, `number_inactive`	The from-number can’t place calls; see which numbers support outbound.
`422`	`destination_invalid`, `destination_not_allowed`, `premium_destination_blocked`, `self_call_blocked`	The destination is refused; see allowed destinations.
`422`	`idempotency_key_reuse`	The key was already used with a different body; mint a fresh key per distinct call.

502 and 503 follow the general guidance: retrying is safe, especially with an Idempotency-Key.

Going further

Webhooks

The phone_call.dial_finished payload in full.

Transfers

Hand an answered call to a human; consult legs dial from the same number.

Bring your own SIP numbers

Place calls through your own trunk with your number as caller ID.

Conversation history

Transcripts, recordings, and session listing filters.

Get Started

Build

Test

Deploy

Telephony

Monitor

Phone numbers

Webhooks

Dynamic variables

Place a call

Request fields

Retry safely with an Idempotency-Key

The dial outcome

Allowed destinations

Errors

Going further

Webhooks

Transfers

Bring your own SIP numbers

Conversation history

Phone numbers

Webhooks

Dynamic variables

​Place a call

​Request fields

​Retry safely with an Idempotency-Key

​The dial outcome

​Allowed destinations

​Errors

​Going further

Webhooks

Transfers

Bring your own SIP numbers

Conversation history

Place a call

Request fields

Retry safely with an Idempotency-Key

The dial outcome

Allowed destinations

Errors

Going further