Inbound Calls

Point a phone number at an agent and it picks up every inbound call. Phone calls are ordinary agent sessions: they appear in session history with caller attribution, they are stored and analyzed under the same per-agent settings as any other conversation, and they trigger the same webhooks.

Phone numbers

Get a number and manage its agent binding.

Conversation history

Review transcripts, tool calls, and recordings.

Webhooks

Get notified when calls end and analysis completes.

Set up inbound calling

Get a phone number

Add a number to your workspace — see Phone numbers. Numbers are stored and displayed in E.164 format (for example +15551234567).

Publish your agent

Calls connect to the agent’s published configuration, not the draft. Publish before pointing traffic at the number.

Bind the agent to the number

Bind in the console, or set agent_id on the number via the API:

curl --request PATCH https://api.fish.audio/v1/agent/phone-numbers/PHONE_NUMBER_ID \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": "YOUR_AGENT_ID" }'

curl --request PATCH https://api.fish.audio/v1/agent/phone-numbers/PHONE_NUMBER_ID \
  --header "Authorization: Bearer $FISH_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "agent_id": null }'

The number-to-agent binding is resolved on each incoming call, so a rebind takes effect on the next call — useful for moving a number from a staging agent to a production agent.

Phone sessions in history

Every answered call becomes a session with source: "phone" and two attribution fields:

Field	Description
`caller_number`	The caller’s number, E.164. `null` for non-phone sessions.
`dialed_number`	The workspace number that was called, E.164. `null` for non-phone sessions.

List calls with the standard sessions endpoint. The caller_number filter is an exact match; bare numbers are automatically prefixed with +, so 15551234567 matches +15551234567:

curl --request GET "https://api.fish.audio/v1/agent/sessions?agent_id=YOUR_AGENT_ID&caller_number=15551234567" \
  --header "Authorization: Bearer $FISH_API_KEY"

{
  "sessions": [
    {
      "session_id": "9c41f0d2e8a34b7f",
      "agent_id": "YOUR_AGENT_ID",
      "agent_name": "Support line",
      "status": "completed",
      "source": "phone",
      "caller_number": "+15551234567",
      "dialed_number": "+14155550100",
      "created_at": "2026-07-23T09:14:01Z",
      "started_at": "2026-07-23T09:14:02Z",
      "ended_at": "2026-07-23T09:16:45Z",
      "duration_seconds": 163,
      "metadata": {}
    }
  ],
  "has_more": false,
  "next_cursor": null
}

You can combine caller_number with the other list filters (agent_id, status, created_after, created_before) — see Conversation history for the full parameter list.

Phone sessions behave like any session

Nothing about a phone call needs special handling downstream:

Transcript and tool timeline — GET /v1/agent/sessions/{session_id} returns the conversation, including tool calls and results, when the agent stores transcripts. See Conversation history.
Recording — GET /v1/agent/sessions/{session_id}/recording returns signed URLs, one track per speaker, when the session was recorded.
Post-call analysis — summaries, data fields, and evaluation criteria run on phone sessions like any other. See Post-call analysis.
Webhooks — call.ended and call.analyzed fire for phone sessions too. See Webhooks.
Hang up via API — end an in-progress call with POST /v1/agent/sessions/{session_id}/end.

Going further

Phone numbers

Number management and agent bindings.

Versions & publishing

Control which configuration answers your calls.

Post-call analysis

Extract structured data from every call.

Webhooks

React to call lifecycle events from your backend.

Get Started

Build

Test

Deploy

Telephony

Monitor

Phone numbers

Conversation history

Webhooks

Set up inbound calling

Phone sessions in history

Phone sessions behave like any session

Going further

Phone numbers

Versions & publishing

Post-call analysis

Webhooks

Phone numbers

Conversation history

Webhooks

​Set up inbound calling

​Phone sessions in history

​Phone sessions behave like any session

​Going further

Phone numbers

Versions & publishing

Post-call analysis

Webhooks

Set up inbound calling

Phone sessions in history

Phone sessions behave like any session

Going further