Guides

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.

Create agent

Create a new agent.

POST /v1/agents

Request body

FieldTypeRequiredDescription
namestringYesName of the agent
descriptionstring or nullNoDescription of what the agent does
voiceModestring or nullNoVoice handling mode: "webhook" (default) or "hosted"
systemPromptstring or nullNoSystem prompt for the built-in LLM (used when voiceMode is "hosted")
beginMessagestring or nullNoInitial greeting message spoken when a call connects
voicestring or nullNoVoice identifier for text-to-speech (e.g., "Polly.Amy")

Example

$curl -X POST "https://api.agentphone.to/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

ParameterTypeRequiredDefaultDescription
limitintegerNo20Number of results to return (max 100)
offsetintegerNo0Number of results to skip (min 0)

Example

$curl -X GET "https://api.agentphone.to/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.to/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.to/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.to/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

FieldTypeRequiredDescription
numberIdstringYesThe ID of the phone number to attach

Example

$curl -X POST "https://api.agentphone.to/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.to/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.to/v1/agents/agt_abc123/calls?limit=5" \
>  -H "Authorization: Bearer YOUR_API_KEY"