SIP (BYOP) Setup

This guide walks you through connecting your own SIP carrier to Vocobase for inbound and outbound calling.

SIP is a Bring-Your-Own-Provider (BYOP) transport. You bring a carrier that supports standard SIP, and Vocobase manages the voice-agent connection for inbound and outbound calls.

Prerequisites

A Vocobase partner account with "SIP" present in allowed_telephony_providers (check GET /api/v2/config). If it is not listed, contact your Vocobase account manager to enable it.
An account with any SIP carrier, with the following details ready:
- SIP host — the carrier’s SIP server hostname (e.g., sip.your-carrier.com)
- Outbound auth username + password — the SIP credentials your carrier issues for INVITE authentication
- Source IPs — the carrier’s egress IPs from which inbound SIP INVITEs originate (used to allowlist inbound traffic)
- At least one DID (phone number in E.164 format) provisioned on the carrier for inbound and/or outbound voice
A Vocobase V2 API key

Step 1: Gather your carrier credentials

Locate your SIP trunk settings

Find the SIP trunk / SIP gateway section. You are looking for:

SIP host — typically a hostname like sip.carrier.com or pbx.carrier.com
Auth username and auth password — the credentials Vocobase will present when placing outbound INVITEs through your carrier
Source IPs — the IPs your carrier uses to send inbound INVITEs to subscribers. Most carriers publish these in their docs.

Your SIP auth password grants outbound calling on your trunk. Treat it like any production secret.

Confirm your DID(s)

From the carrier portal, note each phone number you plan to use, in E.164 format (e.g., +918011223344). These are the numbers Vocobase will use as caller IDs on outbound calls and bind to inbound routing on inbound calls.

Step 2: Add the SIP connection with the V2 API

Create a named SIP connection and store the returned connection_id.

curl -X POST https://api.vocobase.com/api/v2/telephony/connections \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "sip",
    "name": "Tata Tele India",
    "sip_host": "sip.your-carrier.com",
    "outbound_username": "carrier-user",
    "outbound_password": "carrier-password",
    "source_ips": ["203.0.113.10", "203.0.113.11"],
    "did_number": "+918011223344",
    "sip_transport": "UDP"
  }'

{
  "success": true,
  "data": {
    "connection": {
      "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "provider": "sip",
      "provider_key": "SIP",
      "name": "Tata Tele India",
      "status": "ACTIVE",
      "sip_host": "sip.your-carrier.com",
      "sip_transport": "UDP",
      "livekit_sip_uri": "sip:9b7f1c44-c87f-4f0c-9124-3c802a9c1a20@sip.vocobase.com",
      "phone_numbers": [
        {
          "phone_number": "+918011223344",
          "status": "ACTIVE",
          "is_default": true,
          "agent": null
        }
      ]
    }
  }
}

Paste the livekit_sip_uri into your carrier’s DID-origination or outbound routing setting so that calls to your DIDs are forwarded to Vocobase. The exact field name varies by carrier, often called origination URI, SIP termination URL, or destination SIP URI.

Connections created through the V2 API also appear in the Vocobase dashboard telephony settings with their name and connection ID.

Step 3: Make an outbound test call

Start an outbound call with "provider": "sip". If your partner account has multiple active SIP connections, include connection_id.

curl -X POST https://api.vocobase.com/api/v2/calls/start \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_number": "+919876543210",
    "provider": "sip",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

const response = await fetch(
  "https://api.vocobase.com/api/v2/calls/start",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      to_number: "+919876543210",
      provider: "sip",
      connection_id: "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
    })
  }
);
const result = await response.json();
console.log(result);

import requests

response = requests.post(
    "https://api.vocobase.com/api/v2/calls/start",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "to_number": "+919876543210",
        "provider": "sip",
        "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
    }
)
print(response.json())

A successful response looks like:

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "sip",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+918011223344",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Passing only "provider": "sip" remains valid while there is exactly one active SIP connection.

How it works

Outbound — Vocobase starts the call through your SIP carrier and connects the call to your selected agent.
Inbound — When a caller dials one of your DIDs, your carrier forwards the call to the SIP URI you configured and Vocobase routes it to the assigned agent.
Transfer — Transfers use the same configured carrier connection and include transfer metadata in the session.completed webhook.

Troubleshooting

Issue	Solution
`CONNECTION_AMBIGUOUS` error	Call `GET /api/v2/telephony/connections?provider=sip` and pass the desired `connection_id` in `POST /api/v2/calls/start`.
Inbound calls do not arrive	Confirm the carrier is forwarding the DID to the `livekit_sip_uri` returned by the connection API.
Caller ID is wrong	Confirm the DID belongs to this SIP connection and is active in `GET /api/v2/phone-numbers`.

Next steps

Telephony Connections

Create and manage multiple named connections.

Vobiz Setup

Configure Vobiz as another telephony provider.

Quick Start

Create an agent and make your first call.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

SIP (BYOP) Setup

SIP (BYOP) Setup

Prerequisites

Step 1: Gather your carrier credentials

Step 2: Add the SIP connection with the V2 API

Step 3: Make an outbound test call

How it works

Troubleshooting

Next steps

Telephony Connections

Vobiz Setup

Quick Start

​SIP (BYOP) Setup

​Prerequisites

​Step 1: Gather your carrier credentials

​Step 2: Add the SIP connection with the V2 API

​Step 3: Make an outbound test call

​How it works

​Troubleshooting

​Next steps

Telephony Connections

Vobiz Setup

Quick Start

SIP (BYOP) Setup

Prerequisites

Step 1: Gather your carrier credentials

Step 2: Add the SIP connection with the V2 API

Step 3: Make an outbound test call

How it works

Troubleshooting

Next steps