Retell AI integration (API)

This guide shows how to integrate Retell AI with Vobiz using the API for automated outbound calling - ideal for developers building applications that trigger AI calls programmatically.

Prefer a visual dashboard? Check out the dashboard setup guide for a no-code integration method.

Prerequisites

Retell AI account → Sign up
Vobiz account with SIP trunk → Create account
Retell AI agent created → Create in dashboard
Phone number from Vobiz (for caller ID)

Get Vobiz credentials:

Console: Vobiz Console → Trunks
API: Vobiz API reference

Step 1: Get your API key

Go to Retell Dashboard → Settings → API Keys.
Click Create API Key.
Copy the key (it starts with key_).

Keep this key secret - never commit it to git or share publicly. Store it securely in environment variables.

Step 2: List available agents

Retrieve all agents to get the agent_id you’ll use for calls:

curl "https://api.retellai.com/list-agents" \
  -H "Authorization: Bearer key_abc123xyz789example"

Example response:

[
  {
    "agent_id": "agent_abc123example",
    "agent_name": "Customer Support Agent",
    "voice_id": "11labs-Rachel",
    "language": "en-US"
  }
]

What to extract:

agent_id - use this when making calls
agent_name - human-readable label
voice_id - the voice the agent uses

Copy the agent_id for the agent you want to use.

Step 3: Configure phone number with SIP trunk

Add your Vobiz phone number and SIP trunk configuration to Retell:

curl "https://api.retellai.com/create-phone-number" \
  -X POST \
  -H "Authorization: Bearer key_abc123xyz789example" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "phone_number_type": "custom",
    "nickname": "Vobiz Main Line",
    "outbound_agent_id": "agent_abc123example",
    "sip_outbound_trunk_config": {
      "termination_uri": "abc123.sip.vobiz.ai",
      "transport": "TCP",
      "auth_username": "your_username",
      "auth_password": "your_password"
    }
  }'

Required fields:

Field	Description
`phone_number`	Your Vobiz number in E.164 format
`phone_number_type`	Must be `"custom"` for SIP trunks
`outbound_agent_id`	Agent ID from Step 2
`sip_outbound_trunk_config.termination_uri`	Vobiz SIP domain (without the `sip:` prefix)
`sip_outbound_trunk_config.transport`	`"TCP"` (recommended)
`sip_outbound_trunk_config.auth_username`	Vobiz trunk username
`sip_outbound_trunk_config.auth_password`	Vobiz trunk password

Get your Vobiz credentials from Vobiz Console → Trunks → your trunk.

Step 4: Make an outbound call

Trigger an outbound AI call programmatically:

curl "https://api.retellai.com/v2/create-phone-call" \
  -X POST \
  -H "Authorization: Bearer key_abc123xyz789example" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+1234567890",
    "to_number": "+10987654321",
    "agent_id": "agent_abc123example"
  }'

Required parameters:

Field	Description
`from_number`	Your configured Vobiz number (caller ID)
`to_number`	Destination number to call (E.164 format)
`agent_id`	Which agent to use for the call

Example response:

{
  "call_id": "call_abc123xyz789",
  "call_status": "registered",
  "from_number": "+1234567890",
  "to_number": "+10987654321",
  "direction": "outbound"
}

Call status values:

registered - call initiated
ringing - phone is ringing
ongoing - call connected
ended - call finished

Call initiated! The destination phone will ring, and when answered, the AI agent will speak.

Troubleshooting

401 Unauthorized

Invalid API key.

Verify the API key in Retell Dashboard → Settings.
Ensure it starts with key_.

”Phone number not found”

Phone number not configured in Retell.

Run Step 3 to add the phone number with the SIP trunk.
Verify the number format is E.164.

Call fails immediately

Possible causes:

Wrong SIP credentials - verify Vobiz username/password at Vobiz Console.
Wrong transport type - try "UDP" instead of "TCP" in the trunk config.
Incorrect SIP domain - must be the exact Vobiz domain (for example, abc123.sip.vobiz.ai); do not include the sip: prefix.
Insufficient balance - check your Vobiz account has credits at Vobiz Console. See account balance.

Agent doesn’t speak

Agent not configured or not published.

Ensure the agent is published in Retell Dashboard → Agents.
Check the agent has a voice configured.
Verify the agent ID matches the phone number config.

Quick reference

API endpoints

Base URL: https://api.retellai.com Authentication: Authorization: Bearer YOUR_API_KEY

Endpoint	Method	Purpose
`/list-agents`	GET	List all agents
`/list-phone-numbers`	GET	List configured numbers
`/create-phone-number`	POST	Add phone number with SIP trunk
`/v2/create-phone-call`	POST	Make outbound call
`/get-call/{call_id}`	GET	Get call details

Complete call flow

# 1. List agents
curl "https://api.retellai.com/list-agents" \
  -H "Authorization: Bearer key_YOUR_KEY_HERE"

# 2. Configure phone number (one-time)
curl "https://api.retellai.com/create-phone-number" \
  -X POST \
  -H "Authorization: Bearer key_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "phone_number_type": "custom",
    "outbound_agent_id": "agent_YOUR_AGENT_ID",
    "sip_outbound_trunk_config": {
      "termination_uri": "abc123.sip.vobiz.ai",
      "transport": "TCP",
      "auth_username": "your_username",
      "auth_password": "your_password"
    }
  }'

# 3. Make a call
curl "https://api.retellai.com/v2/create-phone-call" \
  -X POST \
  -H "Authorization: Bearer key_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+1234567890",
    "to_number": "+10987654321",
    "agent_id": "agent_YOUR_AGENT_ID"
  }'

Resources

Your Retell AI agents can now make outbound calls through Vobiz programmatically - perfect for automated campaigns and application integrations.

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

Migrations

Retell AI integration (API)

Prerequisites

Step 1: Get your API key

Step 2: List available agents

Step 3: Configure phone number with SIP trunk

Step 4: Make an outbound call

Troubleshooting

401 Unauthorized

”Phone number not found”

Call fails immediately

Agent doesn’t speak

Quick reference

API endpoints

Complete call flow

Resources

​Prerequisites

​Step 1: Get your API key

​Step 2: List available agents

​Step 3: Configure phone number with SIP trunk

​Step 4: Make an outbound call

​Troubleshooting

​401 Unauthorized

​”Phone number not found”

​Call fails immediately

​Agent doesn’t speak

​Quick reference

​API endpoints

​Complete call flow

​Resources

Prerequisites

Step 1: Get your API key

Step 2: List available agents

Step 3: Configure phone number with SIP trunk

Step 4: Make an outbound call

Troubleshooting

401 Unauthorized

”Phone number not found”

Call fails immediately

Agent doesn’t speak

Quick reference

API endpoints

Complete call flow

Resources