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.

💡 Tip: 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

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

⚠️ Warning: 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:

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

Example response:

jsonCopy
[
  {
    "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:

bashCopy
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:

ℹ️ Note: Get your Vobiz credentials from Vobiz Console → Trunks → your trunk.

Step 4: Make an outbound call

Trigger an outbound AI call programmatically:

bashCopy
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:

Example response:

jsonCopy
{
  "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

✅ Success: 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:

1. Wrong SIP credentials - verify Vobiz username/password at Vobiz Console.
2. Wrong transport type - try "UDP" instead of "TCP" in the trunk config.
3. Incorrect SIP domain - must be the exact Vobiz domain (for example, abc123.sip.vobiz.ai); do not include the sip: prefix.
4. 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

Complete call flow

bashCopy
# 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

• Retell AI documentation
• Retell AI dashboard
• Vobiz documentation
• Vobiz Console

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