Telephony

Connect your voice AI agents to real phone numbers with Twilio. Inbound and outbound calls run through the exact same AI pipeline used for WebSocket sessions — same agent, same voice, same tools.

ℹ️

Twilio is the supported telephony provider. Bring your own Twilio account; you configure its credentials per agent.

Inbound Calls

To receive inbound calls, point your Twilio phone number's webhook at the UltraVoice inbound endpoint:

TEXT

https://ultravoice.us.inc/api/v1/telephony/inbound/twilio

Then attach your Twilio credentials to the agent that should answer:

BASH

curl -X PUT https://ultravoice.us.inc/api/v1/agents/{agent_id}/telephony \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "twilio_account_sid": "ACxxxxxxxxxx",
    "twilio_auth_token": "your_auth_token",
    "twilio_phone_number": "+18005551000"
  }'

Outbound Calls

Initiate an outbound call to any phone number. Pass dynamic_context to personalize the conversation at call time:

BASH

curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/outbound \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "to_number": "+1234567890",
    "dynamic_context": {
      "customer_name": "John",
      "reason": "appointment_reminder"
    }
  }'

JSON

{
  "call_id": "CA123...",
  "session_id": "f7e8d9c0-...",
  "status": "initiating",
  "to_number": "+1234567890"
}

Call Management

BASH

# Get call status
curl https://ultravoice.us.inc/api/v1/telephony/calls/{call_id} \
  -H "Authorization: Bearer $TOKEN"

# End a call
curl -X POST https://ultravoice.us.inc/api/v1/telephony/calls/{call_id}/end \
  -H "Authorization: Bearer $TOKEN"

# List active calls
curl https://ultravoice.us.inc/api/v1/telephony/calls \
  -H "Authorization: Bearer $TOKEN"

Human Transfer

Let the AI hand a live call to a human when the caller asks. Set one flag plus a destination number — no extra tools or code.

How it Works

When human transfer is enabled, the pipeline gives the LLM a built-in transfer function. When the caller says something like "let me speak to a person", the AI plays a short hold message, Twilio forwards the call to your number, and the AI disconnects.

Enable Human Transfer

Step 1 — Turn on transfer for the agent:

BASH

curl -X PUT https://ultravoice.us.inc/api/v1/agents/{agent_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_human_transfer": true
  }'

Step 2 — Set the destination number on the telephony config:

BASH

curl -X PUT https://ultravoice.us.inc/api/v1/agents/{agent_id}/telephony \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "twilio_account_sid": "ACxxxxxxxxxx",
    "twilio_auth_token": "your_auth_token",
    "twilio_phone_number": "+18005551000",
    "human_transfer_number": "+19175550042"
  }'

💡

human_transfer_number is where the caller is sent — your support desk, mobile, or any phone number.

⚠️

Human transfer requires telephony to be configured (a saved Twilio number). It has no effect on WebSocket/browser sessions.

What the Caller Hears

TEXT

Caller: "Can I speak to a real person please?"

AI:     "Of course — please hold while I connect you to a human agent."

        [Call forwarded to +19175550042]
        [AI disconnects from the call]

Twilio Setup

Sign up at twilio.com and buy a phone number.
Copy your Account SID and Auth Token from the Twilio Console.
Set the phone number's Voice webhook (A CALL COMES IN) to the inbound URL:

TEXT

https://ultravoice.us.inc/api/v1/telephony/inbound/twilio

Save the agent's Twilio credentials via the Agent Telephony API (PUT /agents/{agent_id}/telephony).
Place a test call to your Twilio number — the agent answers.