> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retell AI integration (API)

> Connect Retell AI to Vobiz SIP trunking via API - programmatic outbound and inbound call routing for AI voice agents across 130+ countries.

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](/integrations/retellai-dashboard) for a no-code integration method.
</Tip>

## Prerequisites

* **Retell AI account** → [Sign up](https://dashboard.retellai.com)
* **Vobiz account** with SIP trunk → [Create account](https://console.vobiz.ai/auth/signup)
* **Retell AI agent** created → [Create in dashboard](https://dashboard.retellai.com/agents)
* **Phone number** from Vobiz (for caller ID)

**Get Vobiz credentials:**

* **Console:** [Vobiz Console → Trunks](https://console.vobiz.ai)
* **API:** [Vobiz API reference](/trunks)

## Step 1: Get your API key

1. Go to [Retell Dashboard → Settings → API Keys](https://dashboard.retellai.com/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.
</Warning>

## Step 2: List available agents

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

```bash theme={null}
curl "https://api.retellai.com/list-agents" \
  -H "Authorization: Bearer key_abc123xyz789example"
```

Example response:

```json theme={null}
[
  {
    "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:

```bash theme={null}
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                         |

<Note>
  Get your Vobiz credentials from [Vobiz Console](https://console.vobiz.ai) → **Trunks** → your trunk.
</Note>

## Step 4: Make an outbound call

Trigger an outbound AI call programmatically:

```bash theme={null}
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:

```json theme={null}
{
  "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

<Check>
  **Call initiated!** The destination phone will ring, and when answered, the AI agent will speak.
</Check>

## Troubleshooting

### 401 Unauthorized

Invalid API key.

* Verify the API key in [Retell Dashboard → Settings](https://dashboard.retellai.com/settings/api-keys).
* 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](https://console.vobiz.ai).
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](https://console.vobiz.ai). See [account balance](/account/balance).

### Agent doesn't speak

Agent not configured or not published.

* Ensure the agent is published in [Retell Dashboard → Agents](https://dashboard.retellai.com/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

```bash theme={null}
# 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](https://docs.retellai.com)
* [Retell AI dashboard](https://dashboard.retellai.com)
* [Vobiz documentation](/introduction)
* [Vobiz Console](https://console.vobiz.ai)

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