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 account with an API key

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.

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.

To rotate credentials later, send the same request again with the new values. Every field is required on each call — the endpoint replaces the stored credential set rather than patching it.

Make a test call

Start an outbound call with "provider": "twilio".

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

If your account has more than one active Twilio connection, also pass connection_id — omitting it returns CONNECTION_AMBIGUOUS. See Bring Your Own Phone for the full request and response shape.

Troubleshooting

”Twilio not configured” error

You will receive a 400 error if you try to make a call with "provider": "twilio" before configuring credentials. Send the PUT /api/v2/config/telephony/twilio request above first.

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

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

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Twilio Setup

Twilio Setup

Prerequisites

Get your Twilio credentials

Configure Twilio in Vocobase

Make a test call

Troubleshooting

”Twilio not configured” error

”Invalid Twilio credentials” error

Calls fail with no answer

Caller ID shows “Unknown”

Geographic restrictions

Next steps

Telephony Connections

MCube Setup

Quick Start

​Twilio Setup

​Prerequisites

​Get your Twilio credentials

​Configure Twilio in Vocobase

​Make a test call

​Troubleshooting

​”Twilio not configured” error

​”Invalid Twilio credentials” error

​Calls fail with no answer

​Caller ID shows “Unknown”

​Geographic restrictions

​Next steps

Telephony Connections

MCube Setup

Quick Start

Twilio Setup

Prerequisites

Get your Twilio credentials

Configure Twilio in Vocobase

Make a test call

Troubleshooting

”Twilio not configured” error

”Invalid Twilio credentials” error

Calls fail with no answer

Caller ID shows “Unknown”

Geographic restrictions

Next steps