Agents | AgentPhone

Agents represent AI personas (e.g., Support Bot, Sales Agent) that can have phone numbers attached to them. Each agent can be configured with a voice mode, system prompt, greeting message, and voice selection.

Voice modes

Agents support two voice modes for handling calls:

webhook (default) — Forwards call transcripts to your configured webhook URL. You process the transcript with your own AI backend and return a response.
hosted — Uses a built-in LLM with the agent’s systemPrompt. No webhook is needed for voice conversations; the platform handles the AI interaction directly.

Voice tuning

Beyond the voice mode, a handful of agent fields shape how a call actually sounds and behaves. They apply to both webhook and hosted modes (the Calls guide describes the underlying engine). Set them on POST /v1/agents or change them anytime with PATCH /v1/agents/{id} — voice infrastructure re-provisions with no downtime.

Goal	Field(s)	Notes
Pick the voice	`voice`	A TTS voice identifier. List options with `GET /v1/agents/voices`.
Pace the speech	`voiceSpeed`	`1.0` normal, `0.5` slow, `2.0` fast. Slower can improve clarity for older callers or noisy lines.
Control interruptions	`interruptionSensitivity`	Higher = the agent yields to the caller faster (more natural, but cuts off on background noise). Lower = the agent holds the floor. Default `0.8`.
Backchanneling	`enableBackchannel`	Natural “uh-huh”/“mhmm” cues while the caller talks. Turn off for IVR-style or read-only flows.
Transcription quality	`sttMode`	`"fast"` (default) for lowest latency, `"accurate"` when names, addresses, or numbers must be exact (~200 ms slower).
Noisy callers	`denoisingMode`	`"noise-and-background-speech-cancellation"` for callers in cars, cafes, or near a TV. Adds a small surcharge.
Ambience	`ambientSound`	Subtle background (`office`, `coffee-shop`, `outdoor`) so silence between turns feels less synthetic.
Patience	`maxSilenceMs`	How long to wait on a silent line before hanging up. Raise for hold-music/IVR navigation.
Texting mid-call	`enableMessaging`	Lets a hosted agent send a follow-up text during the call (e.g. a confirmation link).
Voicemail	`voicemailMessage`	Spoken if an outbound call lands in voicemail.
Transfers	`transferNumber`	Where a `transfer` action routes the call. See Calls.

Good defaults for a natural-sounding assistant: leave interruptionSensitivity near 0.8, keep enableBackchannel on, and use sttMode: "accurate" only when you need exact capture of spelled-out details. Tune one field at a time and listen back with call recordings.

Language

Set language to a BCP-47 locale to run recognition and synthesis in that language. AgentPhone supports 63 locales, including:

Locale	Language	Locale	Language
`en-US`	English (US)	`es-ES`	Spanish (Spain)
`en-GB`	English (UK)	`es-419`	Spanish (Latin America)
`en-AU`	English (Australia)	`fr-FR`	French (France)
`en-IN`	English (India)	`pt-BR`	Portuguese (Brazil)
`de-DE`	German	`it-IT`	Italian
`ja-JP`	Japanese	`ko-KR`	Korean
`zh-CN`	Chinese (Mandarin)	`hi-IN`	Hindi

Pick a voice that matches the locale for the most natural result. The full list of accepted locale codes is in the API Reference under the agent language field.

Create agent

Create a new agent.

POST /v1/agents

Request body

Field	Type	Required	Description
`name`	string	Yes	Name of the agent
`description`	string or null	No	Description of what the agent does
`voiceMode`	string or null	No	Voice handling mode: `"webhook"` (default) or `"hosted"`
`systemPrompt`	string or null	No	System prompt for the built-in LLM (used when `voiceMode` is `"hosted"`)
`beginMessage`	string or null	No	Initial greeting message spoken when a call connects
`voice`	string or null	No	Voice identifier for text-to-speech (e.g., `"Polly.Amy"`)
`modelTier`	string or null	No	Quality/latency tradeoff for hosted-mode agents: `"turbo"` (lowest latency, best for simple tasks), `"balanced"` (default, good mix of speed and quality), or `"max"` (highest quality, best for complex reasoning)
`sttMode`	string or null	No	Speech-to-text mode: `"fast"` (default) optimizes for latency, `"accurate"` optimizes for transcription accuracy (~200ms additional latency)
`ambientSound`	string or null	No	Background ambience to mask synthetic silence between turns: `"none"` (default), `"office"`, `"coffee-shop"`, or `"outdoor"`
`denoisingMode`	string or null	No	Audio denoising level: `"noise-cancellation"` (default) or `"noise-and-background-speech-cancellation"` (more aggressive, for callers in cars, cafes, or near TVs). $0.005/min surcharge.
`transferNumber`	string or null	No	Phone number to transfer calls to when the agent triggers a transfer action
`voicemailMessage`	string or null	No	Message to play when a call goes to voicemail
`voiceSpeed`	number or null	No	Speech speed multiplier. `1.0` is normal pace, `0.5` is half speed, `2.0` is double. Range 0.5–2.0.
`interruptionSensitivity`	number or null	No	How easily callers can interrupt (barge in). `0` means the agent is never interrupted, `1` stops at the first sound. Default `0.8`. Range 0.0–1.0.
`enableBackchannel`	boolean or null	No	When `true`, the agent interjects short cues like “uh-huh” while the caller is speaking. Set `false` to stay silent until the caller finishes. Default `true`.
`maxSilenceMs`	integer or null	No	Hang up after this many milliseconds of caller silence. Default `600000` (10 min). Raise for IVR/hold-music flows, lower to fail fast on dead lines. Range 10000–3600000.
`enableMessaging`	boolean or null	No	When `true`, hosted-mode agents can send and read SMS/iMessage during a call. Default `true`.
`language`	string or null	No	BCP-47 locale for speech recognition and synthesis, e.g. `"en-US"`, `"es-ES"`, `"ja-JP"`. See Language.

See Voice tuning below for how the voice-related fields shape a call.

Example

$ curl -X POST "https://api.agentphone.ai/v1/agents" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Support Bot",
>     "description": "Handles customer support inquiries",
>     "voiceMode": "hosted",
>     "systemPrompt": "You are a helpful customer support agent for Acme Corp.",
>     "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?",
>     "voice": "Polly.Amy"
>   }'

1 {
2   "id": "agt_abc123",
3   "name": "Support Bot",
4   "description": "Handles customer support inquiries",
5   "voiceMode": "hosted",
6   "systemPrompt": "You are a helpful customer support agent for Acme Corp.",
7   "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?",
8   "voice": "Polly.Amy",
9   "createdAt": "2025-01-15T10:30:00Z",
10   "numbers": []
11 }

List agents

List all agents for this project.

GET /v1/agents

Query parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	20	Number of results to return (max 100)
`offset`	integer	No	0	Number of results to skip (min 0)

Example

$ curl -X GET "https://api.agentphone.ai/v1/agents?limit=10&offset=0" \
>   -H "Authorization: Bearer YOUR_API_KEY"

Get agent

Get a single agent with its attached numbers.

GET /v1/agents/{agent_id}

Example

$ curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123" \
>   -H "Authorization: Bearer YOUR_API_KEY"

Update agent

Update an agent’s configuration. Use this to change voice mode, system prompt, greeting, or voice.

PATCH /v1/agents/{agent_id}

All fields are optional. Only include the fields you want to update.

Example

$ curl -X PATCH "https://api.agentphone.ai/v1/agents/agt_abc123" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "systemPrompt": "You are a friendly sales assistant for Acme Corp.",
>     "voiceMode": "hosted"
>   }'

Delete agent

Delete an agent. Phone numbers, conversations, and calls associated with the agent will have their agent reference cleared but will not be deleted.

DELETE /v1/agents/{agent_id}

Example

$ curl -X DELETE "https://api.agentphone.ai/v1/agents/agt_abc123" \
>   -H "Authorization: Bearer YOUR_API_KEY"

Attach number to agent

Attach an existing phone number to an agent. The number must belong to the same project and must not be released.

POST /v1/agents/{agent_id}/numbers

Request body

Field	Type	Required	Description
`numberId`	string	Yes	The ID of the phone number to attach

Example

$ curl -X POST "https://api.agentphone.ai/v1/agents/agt_abc123/numbers" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"numberId": "num_xyz789"}'

List agent conversations

List all conversations for a specific agent.

GET /v1/agents/{agent_id}/conversations

Example

$ curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/conversations?limit=10" \
>   -H "Authorization: Bearer YOUR_API_KEY"

List agent calls

List all calls for a specific agent.

GET /v1/agents/{agent_id}/calls

Example

$ curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/calls?limit=5" \
>   -H "Authorization: Bearer YOUR_API_KEY"

List available voices

List all available TTS voices that can be used with the voice field when creating or updating agents.

GET /v1/agents/voices

Example

$ curl -X GET "https://api.agentphone.ai/v1/agents/voices" \
>   -H "Authorization: Bearer YOUR_API_KEY"

Use the returned voice identifiers (e.g., "Polly.Amy", "Polly.Joanna") in the voice field when creating agents, updating agents, or making outbound calls.