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

# Telephony Connections

> Create and manage multiple named BYOP telephony connections with the V2 API

# Telephony Connections

Use V2 telephony connections when a partner needs more than one carrier account, trunk, or DID set for the same provider. Each connection has its own `connection_id`, editable `name`, credentials, and phone numbers.

<Note>
  The provider-specific `PUT /api/v2/config/telephony/*` endpoints remain backward compatible and update that provider's default connection. For new BYOP builds, prefer `POST /api/v2/telephony/connections` so every connection is named and addressable.
</Note>

## Supported providers

| Provider      | `provider` value  | Multiple named connections |
| ------------- | ----------------- | -------------------------- |
| Twilio        | `"twilio"`        | Yes                        |
| Exotel        | `"exotel"`        | Yes                        |
| Plivo         | `"plivo"`         | Yes                        |
| Vobiz         | `"vobiz"`         | Yes                        |
| Tata Smartflo | `"tata_smartflo"` | Yes                        |
| SIP           | `"sip"`           | Yes                        |
| VoiceLink     | `"voicelink"`     | Yes                        |
| MCube         | `"mcube"`         | Yes                        |

MCube connections take `jwt_token` and `exe_number` instead of account credentials — see [MCube Setup](/telephony/mcube-setup). The exenumber is stored as the connection's default phone number and may be in national format (no `+` required).

## Create a connection

Create a connection by passing a provider, a human-readable name, and the provider credentials. The response returns the stable `connection_id` to store in your own system.

```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": "plivo",
    "name": "Plivo India - Sales",
    "auth_id": "MAxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_plivo_auth_token",
    "from_number": "+918011223344"
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "connection": {
      "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "provider": "plivo",
      "provider_key": "PLIVO",
      "name": "Plivo India - Sales",
      "status": "ACTIVE",
      "is_default": true,
      "phone_numbers": [
        {
          "id": "f1a2c3d4-1111-2222-3333-444455556666",
          "phone_number": "+918011223344",
          "friendly_name": null,
          "status": "ACTIVE",
          "is_default": true,
          "inbound_enabled": false,
          "agent": null
        }
      ],
      "created_at": "2026-06-09T08:00:00.000Z",
      "updated_at": "2026-06-09T08:00:00.000Z"
    }
  }
}
```

## List connections

Use `GET /api/v2/telephony/connections` to retrieve the connections available to the authenticated partner. Pass `provider` to narrow the list.

```bash theme={null}
curl -X GET "https://api.vocobase.com/api/v2/telephony/connections?provider=plivo" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```

```json theme={null}
{
  "success": true,
  "data": {
    "connections": [
      {
        "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
        "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
        "provider": "plivo",
        "provider_key": "PLIVO",
        "name": "Plivo India - Sales",
        "status": "ACTIVE",
        "is_default": true,
        "last_verified_at": "2026-06-09T08:00:00.000Z",
        "last_error_message": null,
        "phone_numbers": [
          {
            "id": "f1a2c3d4-1111-2222-3333-444455556666",
            "phone_number": "+918011223344",
            "friendly_name": null,
            "status": "ACTIVE",
            "is_default": true,
            "inbound_enabled": false,
            "agent": null
          }
        ]
      }
    ]
  }
}
```

## Retrieve a single connection

Use `GET /api/v2/telephony/connections/{connection_id}` to fetch one connection by its ID, including every active DID on the connection and the agent linked to each. This is the endpoint to poll when you want to keep your own system in sync with the numbers and agent assignments shown in the Vocobase dashboard.

```bash theme={null}
curl -X GET https://api.vocobase.com/api/v2/telephony/connections/9b7f1c44-c87f-4f0c-9124-3c802a9c1a20 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```

```json theme={null}
{
  "success": true,
  "data": {
    "connection": {
      "id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
      "provider": "vobiz",
      "provider_key": "VOBIZ",
      "name": "Vobiz India - Sales",
      "status": "ACTIVE",
      "is_default": true,
      "last_verified_at": "2026-07-10T08:00:00.000Z",
      "last_error_message": null,
      "phone_numbers": [
        {
          "id": "f1a2c3d4-1111-2222-3333-444455556666",
          "phone_number": "+918011223344",
          "friendly_name": "Sales line",
          "status": "ACTIVE",
          "is_default": true,
          "inbound_enabled": true,
          "agent": {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "Sales Qualifier"
          }
        },
        {
          "id": "b2c3d4e5-2222-3333-4444-555566667777",
          "phone_number": "+918011223345",
          "friendly_name": null,
          "status": "ACTIVE",
          "is_default": false,
          "inbound_enabled": false,
          "agent": null
        }
      ],
      "created_at": "2026-07-10T08:00:00.000Z",
      "updated_at": "2026-07-10T08:00:00.000Z"
    }
  }
}
```

Only active DIDs are returned, each with its linked `agent` (`{ id, name }`) or `null` when the number is unassigned. The connection must be active and owned by the authenticated partner, otherwise the API returns `404 NOT_FOUND`.

<Note>
  The list endpoint returns this same connection shape for every connection at once. Use the single-connection endpoint when you already hold the `connection_id` and want the current DID → agent mapping for just that one connection.
</Note>

## Start calls with a connection

When a partner has one active connection for a provider, existing calls that pass only `provider` continue to work:

```json theme={null}
{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "to_number": "+919876543210",
  "provider": "plivo"
}
```

When a partner has multiple active connections for the same provider, pass `connection_id` so routing is deterministic:

```bash 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": "plivo",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'
```

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

`POST /api/v2/calls/start` does not accept a per-call `from_number` override. The caller ID is resolved from the selected connection: Twilio uses the connection default number, Exotel uses the saved caller ID, and Plivo, Vobiz, Tata Smartflo, SIP, and VoiceLink prefer an agent-bound active number before the connection default. The resolved value is returned as `from_number` in the response.

If `connection_id` is omitted while multiple active connections exist for that provider, the API returns `CONNECTION_AMBIGUOUS`.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "CONNECTION_AMBIGUOUS",
    "message": "connection_id is required because this partner has multiple active plivo connections."
  }
}
```

## Rename a connection

Only the display name is editable through this endpoint. To rotate credentials, create a new connection or use the provider-specific config endpoint for the default connection.

```bash theme={null}
curl -X PATCH https://api.vocobase.com/api/v2/telephony/connections/9b7f1c44-c87f-4f0c-9124-3c802a9c1a20 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Plivo India - Support" }'
```

## Disconnect a connection

Disconnecting a connection disables it for new outbound calls and inbound routing. Existing completed call records remain available.

```bash theme={null}
curl -X DELETE https://api.vocobase.com/api/v2/telephony/connections/9b7f1c44-c87f-4f0c-9124-3c802a9c1a20 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
```

## Phone-number ownership

A phone number can be active on multiple connections for outbound caller ID reuse. Vocobase only rejects a duplicate when more than one active row for the same DID is enabled for inbound routing.

For Plivo, Vobiz, and MCube inbound DIDs, pass `connection_id` when syncing numbers for a specific connection. Vobiz and MCube accept an explicit `numbers` array; MCube DIDs must use E.164 format:

```bash theme={null}
curl -X POST https://api.vocobase.com/api/v2/phone-numbers/sync \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "MCUBE",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "numbers": ["+918071844607", "+918071844608"]
  }'
```

Use `GET /api/v2/phone-numbers?provider=MCUBE&connection_id=...` to retrieve the new row IDs, then `PUT /api/v2/phone-numbers/{id}` with `agent_id` and `inbound_enabled: true` to make a DID inbound-ready.

## Dashboard visibility

Connections created through the V2 API appear in the Vocobase dashboard telephony settings with their connection name and ID. Use the same `connection_id` from the dashboard or API response when starting calls from partner systems.

## Next steps

<CardGroup cols={2}>
  <Card title="Bring Your Own Phone" icon="phone" href="/telephony/byop-setup">
    Review the BYOP provider overview.
  </Card>

  <Card title="Inbound Calls" icon="phone-incoming" href="/inbound-calls">
    Assign inbound numbers to agents.
  </Card>
</CardGroup>