Bring Your Own Phone (BYOP)

Bring your own telephony provider account and start calls through the Vocobase V2 API. This page is a provider-neutral overview; use the provider-specific guides for exact credential fields.

Supported providers

Provider	V2 setup guide	Start-call value
Twilio	Twilio Setup	`"twilio"`
MCube	MCube Setup	`"mcube"`
Exotel	Exotel Setup	`"exotel"`
Plivo	Plivo Setup	`"plivo"`
Vobiz	Vobiz Setup	`"vobiz"`
Tata Smartflo	Tata Smartflo Setup	`"tata_smartflo"`
SIP	SIP Setup	`"sip"`
VoiceLink	VoiceLink Setup	`"voicelink"`

Check provider access

Your account must be allowed to use a provider before you can start calls with it.

curl -X GET https://api.vocobase.com/api/v2/config \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

The response includes allowed_telephony_providers and a telephony object that shows which providers are configured.

{
  "success": true,
  "data": {
    "allowed_telephony_providers": ["twilio", "plivo", "vobiz", "tata_smartflo"],
    "telephony": {
      "twilio": { "configured": true, "from_number": "+14155551234" },
      "plivo": { "configured": false, "from_number": null },
      "vobiz": { "configured": false, "from_number": null },
      "tata_smartflo": {
        "configured": false,
        "email": null,
        "base_url": null,
        "from_number": null,
        "agent_number": null,
        "click_to_call_api_key_set": false
      }
    }
  }
}

If the provider you need is missing from allowed_telephony_providers, contact Vocobase support to enable it for your account.

Configure credentials

For new BYOP integrations, create named connections with the V2 telephony connections API:

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

The response includes a stable connection_id. Store it when you need to choose between multiple connections for the same provider. Each provider also has a backward-compatible V2 credential endpoint that updates that provider’s default connection:

Provider	Endpoint
Twilio	`PUT /api/v2/config/telephony/twilio`
MCube	`PUT /api/v2/config/telephony/mcube`
Exotel	`PUT /api/v2/config/telephony/exotel`
Plivo	`PUT /api/v2/config/telephony/plivo`
Vobiz	`PUT /api/v2/config/telephony/vobiz`
Tata Smartflo	`PUT /api/v2/config/telephony/tata-smartflo`
VoiceLink	`PUT /api/v2/config/telephony/voicelink`

Use the provider-specific setup page for the required fields and examples, or see Telephony Connections for the multi-connection flow.

Start a call

After the provider is enabled and configured, start a call with POST /api/v2/calls/start and pass the provider value. If the account has multiple active connections for that provider, also pass 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": "twilio",
    "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": "twilio",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Existing integrations that pass only provider keep working while there is exactly one active connection for that provider. When more than one active connection exists, the API returns CONNECTION_AMBIGUOUS until connection_id is supplied.

Inbound numbers

For inbound calling with Plivo or Vobiz, use the V2 phone-numbers API to sync DIDs and assign agents. MCube DIDs can be registered the same way — its inventory is added manually, so it takes an explicit E.164 numbers array — but MCube inbound is not currently available; registering the DID does not make it ring. See Inbound Calls.

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

A DID can be active on multiple connections for outbound caller ID reuse. Inbound routing stays deterministic because only one active row per DID can have inbound_enabled: true. See Inbound Calls for the full DID assignment flow.

Troubleshooting

Symptom	Action
Provider is not allowed	Ask Vocobase support to enable the provider for your account.
Provider is allowed but not configured	Send the provider’s V2 credential setup request again.
`CONNECTION_AMBIGUOUS` from `/calls/start`	Pass the `connection_id` returned by `GET /api/v2/telephony/connections`.
Calls fail immediately	Confirm the provider credentials, from-number, and destination number format.
Inbound DID does not route to the expected agent	Re-check the DID assignment with `GET /api/v2/phone-numbers`.

Next steps

Quick Start

Create an agent and start your first call.

Inbound Calls

Assign inbound numbers to agents.

Telephony Connections

Create and manage multiple named connections.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Bring Your Own Phone

Bring Your Own Phone (BYOP)

Supported providers

Check provider access

Configure credentials

Start a call

Inbound numbers

Troubleshooting

Next steps

Quick Start

Inbound Calls

Telephony Connections

​Bring Your Own Phone (BYOP)

​Supported providers

​Check provider access

​Configure credentials

​Start a call

​Inbound numbers

​Troubleshooting

​Next steps

Quick Start

Inbound Calls

Telephony Connections

Bring Your Own Phone (BYOP)

Supported providers

Check provider access

Configure credentials

Start a call

Inbound numbers

Troubleshooting

Next steps