Twilio Setup

This guide walks you through connecting your Twilio account to Vocobase for outbound calling.

Prerequisites

A Twilio account (free trial works for testing)
A Twilio phone number with voice capabilities
An approved Vocobase partner account with an API key

Step 1: Get your Twilio credentials

Find your Account SID and Auth Token

On the console dashboard, you will see your Account SID and Auth Token. Click the eye icon to reveal the Auth Token.

Account SID — Starts with AC, 34 characters total
Auth Token — 32-character hex string

Keep your Auth Token secret. Anyone with your SID and Token can make calls using your Twilio account.

Get your phone number

Navigate to Phone Numbers > Manage > Active Numbers in the Twilio Console. Copy the phone number you want to use as the caller ID.The number must be in E.164 format (e.g., +14155551234).

If you do not have a phone number, go to Phone Numbers > Buy a Number to purchase one. For testing, Twilio trial accounts include a free number.

Step 2: Configure Twilio in Vocobase

Send your Twilio credentials to the Vocobase config API:

This endpoint updates your default Twilio connection. To create multiple named Twilio connections, use POST /api/v2/telephony/connections and store the returned connection_id.

curl -X PUT https://api.vocobase.com/api/v2/config/telephony/twilio \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_twilio_auth_token_here",
    "from_number": "+14155551234"
  }'

const response = await fetch(
  "https://api.vocobase.com/api/v2/config/telephony/twilio",
  {
    method: "PUT",
    headers: {
      "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      account_sid: "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      auth_token: "your_twilio_auth_token_here",
      from_number: "+14155551234"
    })
  }
);
const result = await response.json();
console.log(result);

import requests

response = requests.put(
    "https://api.vocobase.com/api/v2/config/telephony/twilio",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "auth_token": "your_twilio_auth_token_here",
        "from_number": "+14155551234"
    }
)
print(response.json())

A successful response confirms your credentials were saved:

{
  "success": true,
  "data": {
    "account_sid": "ACxx****xxxx",
    "from_number": "+14155551234",
    "message": "Twilio credentials updated successfully."
  }
}

Your Auth Token is encrypted at rest and never returned in API responses. The Account SID is masked for security.

Step 3: Make a test call

Start an outbound call using the twilio provider. If your partner account has multiple active Twilio 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": "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"
  }
}

Passing only "provider": "twilio" remains valid while there is exactly one active Twilio connection.

Troubleshooting

”Twilio not configured” error

You will receive a 400 error if you try to make a call with "provider": "twilio" before configuring credentials. Run PUT /config/telephony/twilio with valid credentials.

`CONNECTION_AMBIGUOUS` error

Your account has multiple active Twilio connections. Call GET /api/v2/telephony/connections?provider=twilio and pass the desired connection_id in POST /api/v2/calls/start.

”Invalid Twilio credentials” error

Double-check your Account SID and Auth Token in the Twilio Console. Common issues:

Copying extra whitespace around the credentials
Using a subaccount SID instead of the main Account SID
Auth Token was rotated in Twilio but not updated in Vocobase

Calls fail with no answer

Verify the to_number is in E.164 format (e.g., +919876543210)
Check that your Twilio account has sufficient balance
If using a trial account, the destination number must be verified in Twilio first

Caller ID shows “Unknown”

Ensure the from_number in your Twilio config is a valid Twilio number you own
The number must have voice capabilities enabled in the Twilio Console

Geographic restrictions

Twilio trial accounts can only call verified phone numbers. Upgrade to a paid Twilio account to call any number. Additionally, some countries require regulatory compliance — check Twilio’s supported countries list.

Updating credentials

To update your Twilio credentials (e.g., after rotating your Auth Token), call PUT /config/telephony/twilio again with the new values. All three fields (account_sid, auth_token, from_number) are required each time.

Next steps

Telephony Connections

Create and manage multiple named connections.

MCube Setup

Configure MCube as an alternative telephony provider.

Quick Start

Create an agent and make your first call.

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Twilio Setup

Twilio Setup

Prerequisites

Step 1: Get your Twilio credentials

Step 2: Configure Twilio in Vocobase

Step 3: Make a test call

Troubleshooting

”Twilio not configured” error

`CONNECTION_AMBIGUOUS` error

”Invalid Twilio credentials” error

Calls fail with no answer

Caller ID shows “Unknown”

Geographic restrictions

Updating credentials

Next steps

Telephony Connections

MCube Setup

Quick Start

​Twilio Setup

​Prerequisites

​Step 1: Get your Twilio credentials

​Step 2: Configure Twilio in Vocobase

​Step 3: Make a test call

​Troubleshooting

​”Twilio not configured” error

​CONNECTION_AMBIGUOUS error

​”Invalid Twilio credentials” error

​Calls fail with no answer

​Caller ID shows “Unknown”

​Geographic restrictions

​Updating credentials

​Next steps

Telephony Connections

MCube Setup

Quick Start

Twilio Setup

Prerequisites

Step 1: Get your Twilio credentials

Step 2: Configure Twilio in Vocobase

Step 3: Make a test call

Troubleshooting

”Twilio not configured” error

`CONNECTION_AMBIGUOUS` error

”Invalid Twilio credentials” error

Calls fail with no answer

Caller ID shows “Unknown”

Geographic restrictions

Updating credentials

Next steps