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.

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.

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

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"
  }'

{
  "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.

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

{
  "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.

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

{
  "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.

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.

Start calls with a connection

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

{
  "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:

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"
  }'

{
  "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.

{
  "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.

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.

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:

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.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Telephony Connections

Telephony Connections

Supported providers

Create a connection

List connections

Retrieve a single connection

Start calls with a connection

Rename a connection

Disconnect a connection

Phone-number ownership

Dashboard visibility

Next steps

Bring Your Own Phone

Inbound Calls

​Telephony Connections

​Supported providers

​Create a connection

​List connections

​Retrieve a single connection

​Start calls with a connection

​Rename a connection

​Disconnect a connection

​Phone-number ownership

​Dashboard visibility

​Next steps

Bring Your Own Phone

Inbound Calls

Telephony Connections

Supported providers

Create a connection

List connections

Retrieve a single connection

Start calls with a connection

Rename a connection

Disconnect a connection

Phone-number ownership

Dashboard visibility

Next steps