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

# SIP (BYOP) Setup

> Bring your own SIP carrier for inbound and outbound calling.

# SIP (BYOP) Setup

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

<Note>
  **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.
</Note>

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

<Steps>
  <Step title="Log in to your SIP carrier's portal">
    Sign in to your carrier's dashboard (Vobiz, Tata Tele, Knowlarity, or whichever ITSP you use).
  </Step>

  <Step title="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.

    <Warning>
      Your SIP auth password grants outbound calling on your trunk. Treat it like any production secret.
    </Warning>
  </Step>

  <Step title="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>
</Steps>

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

Create a named SIP connection and store the returned `connection_id`.

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

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

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

## 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`.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

A successful response looks like:

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

<CardGroup cols={2}>
  <Card title="Telephony Connections" icon="settings" href="/telephony/connections">
    Create and manage multiple named connections.
  </Card>

  <Card title="Vobiz Setup" icon="phone" href="/telephony/vobiz-setup">
    Configure Vobiz as another telephony provider.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Create an agent and make your first call.
  </Card>
</CardGroup>