Agents

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} — the voice configuration is updated for subsequent calls. Test a new call after changing voice settings.

Language

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

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

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?"
  }'

{
  "id": "agt_abc123",
  "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": "custom_voice_ea22ba5fdfaa18f39c274851c1",
  "createdAt": "2025-01-15T10:30:00Z",
  "numbers": []
}

List agents

List all agents for this project.

GET /v1/agents

Query parameters

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

Deleting an agent does not release its phone numbers or stop their recurring charges. Release numbers separately when you no longer need them; see Phone numbers.

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.

Attaching changes how the number handles calls. An unassigned number reports voiceRouting.method as "ignore" and does not answer calls; once attached it reports "agent" and inbound calls are answered by that agent, in both hosted and webhook voice modes. To attach a number for messaging only, disable inbound calls on it first with PATCH /v1/numbers/{number_id}/inbound-calls; that setting is kept through attachment and later agent edits.

POST /v1/agents/{agent_id}/numbers

Request body

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"

The response is {"data": [...]} where each entry includes voice_id, voice_name, gender, accent, and a preview_audio_url. Use a returned voice_id in the voice field when creating agents, updating agents, or making outbound calls. These operations, including the per-call override, reject unknown IDs when the catalog is available. During a catalog outage the check is skipped, so use an ID returned by the current catalog rather than relying on validation to catch a typo.