Vobiz Logo
Vobiz
|API Documentation
Console
← Back to Integrations

Retell AI - API Setup

Programmatically integrate Retell AI with Vobiz using REST API and curl commands for automated calling.

Prefer visual dashboard?

Check out the Dashboard Setup Guide for a no-code integration method.

Overview

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

Call flow:

Integration Flow
Your App → Retell AI API → Vobiz SIP → Phone Network → AI Conversation

Prerequisites

Before starting:

Get Vobiz Credentials:

Step 1: Get Your API Key

Via Dashboard:

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

⚠️ Keep this secret!

Never commit to git or share publicly. Store securely in environment variables.

Step 2: List Available Agents

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

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

Example Response:

JSON 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 name
  • voice_id - Which 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 command
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:

phone_number

Your Vobiz number in E.164 format: +countrycode + number

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 sip: prefix)
  • transport - "TCP" (recommended)
  • auth_username - Vobiz trunk username
  • auth_password - Vobiz trunk password

Get Vobiz credentials:

Vobiz Console → Trunks → Your Trunk

✓ Use this number as from_number when making calls

Step 4: Make an Outbound Call

Trigger an AI call programmatically:

curl command
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:

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:

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

What to extract:

  • call_id - Use this to retrieve call details later
  • call_status - Tracks call progress:
    • "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"

Cause: Invalid API key

Fix:

"Phone number not found"

Cause: Phone number not configured in Retell

Fix:

  • Run Step 3 to add phone number with SIP trunk
  • Verify number format is E.164 (+countrycode + number)

Call fails immediately

Possible causes:

1. Wrong SIP credentials

2. Wrong transport type

  • Try "UDP" instead of "TCP" in trunk config

3. SIP domain incorrect

  • Must be exact Vobiz domain (e.g., abc123.sip.vobiz.ai)
  • Do NOT include sip: prefix

4. Insufficient balance

Agent doesn't speak

Cause: Agent not configured or not published

Fix:

Quick Reference

API Endpoints

EndpointMethodPurpose
/list-agentsGETList all agents
/list-phone-numbersGETList configured numbers
/create-phone-numberPOSTAdd phone number with SIP trunk
/v2/create-phone-callPOSTMake outbound call
/get-call/{call_id}GETGet call details

Base URL: https://api.retellai.com

Authentication: Authorization: Bearer YOUR_API_KEY

Complete Call Flow (curl)

All steps in sequence
# 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"
  }'

Support Resources

Integration complete!

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

Retell AI (Dashboard Setup)
All Integrations