> ## 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.
# Twilio Setup
> Configure Twilio for outbound calling with the Vocobase API
# Twilio Setup
This guide walks you through connecting your Twilio account to Vocobase for outbound calling.
## Prerequisites
* A [Twilio account](https://www.twilio.com/try-twilio) (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
Go to [console.twilio.com](https://console.twilio.com) and sign in.
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.
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`.
```bash cURL theme={null}
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"
}'
```
```javascript JavaScript theme={null}
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);
```
```python Python theme={null}
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:
```json theme={null}
{
"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`.
```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": "twilio",
"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": "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](https://console.twilio.com). 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](https://www.twilio.com/en-us/voice).
## 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
Create and manage multiple named connections.
Configure MCube as an alternative telephony provider.
Create an agent and make your first call.