Get startedQuickstart

Voice Agent Telephony

Give an agent a phone number for inbound and outbound calls

Agents is in beta. Shapes on /v1/agents/* may change before general availability.

Telephony connects an agent to the phone network so it can answer inbound calls and place outbound ones. This page covers adding a number, and placing single and batch outbound calls.

1

Set your API key

$export SPEECHIFY_API_KEY="your-api-key-here"
2

Add a phone number

Provision a number the agent will use:

POST
/v1/agents/phone-numbers
1curl -X POST https://api.speechify.ai/v1/agents/phone-numbers \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "e164": "+12025551234",
6  "provider": "livekit",
7  "label": "Trial inbound",
8  "agent_id": "agent_01HS..."
9}'
Try it
3

Place an outbound call

Have the agent call a number:

POST
/v1/agents/outbound-calls
1curl -X POST https://api.speechify.ai/v1/agents/outbound-calls \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "agent_id": "agent_01HS...",
6  "to": "+41791234567",
7  "caller_id_number": "+12025551234"
8}'
Try it

Inbound calls

Once a number is attached to an agent, inbound calls to it are answered by that agent automatically. Configure which agent answers by managing the number:

Batch outbound calls

To call many numbers in one job - reminders, campaigns, notifications - use batch calls:

POST
/v1/agents/batch-calls
1curl -X POST https://api.speechify.ai/v1/agents/batch-calls \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Appointment reminders",
6  "agent_id": "agent_01HS...",
7  "recipients": [
8    {
9      "phone": "+14155551234",
10      "dynamic_variables": {
11        "appointment_date": "May 5th at 2pm",
12        "first_name": "Alice"
13      }
14    },
15    {
16      "phone": "+14155555678",
17      "dynamic_variables": {
18        "appointment_date": "May 6th at 10am",
19        "first_name": "Bob"
20      }
21    }
22  ]
23}'
Try it

Track and control a batch:

ActionEndpoint
List batchesGET /v1/agents/batch-calls
Get a batchGET /v1/agents/batch-calls/{id}
Cancel a batchPOST /v1/agents/batch-calls/{id}/cancel

Next steps

Voice Agent API

Create an agent and start a conversation.

Knowledge base

Ground the agent’s answers in your content.