Twilio

Use your existing Twilio phone numbers to handle inbound and outbound calls for your voice assistants. Keep full ownership of your numbers while powering conversations with AI.

Overview

Prerequisites

Before connecting Twilio, make sure you have:

• An active Twilio (opens in a new tab) account
• At least one phone number purchased in your Twilio console
• Your Account SID, API Key, and API Secret from the Twilio console

How to get the credentials

Follow these steps to get your credentials.

Create or log in to your Twilio account

1. Go to twilio.com/login (opens in a new tab).
2. Log in with your credentials or create a new account.
3. Complete email verification and any required setup steps.

Get your Account SID

Your Account SID is displayed on the Twilio Console dashboard homepage.

1. Navigate to the Twilio Console (opens in a new tab) dashboard.
2. Look for the Account Info section.
3. Copy your Account SID.

Get your API Key and Secret

1. Click Admin → Account Management in the top right corner.
2. Under Keys & Credentials, click API Keys & Tokens.
3. Click Create API Key.
4. Enter a Friendly name for the key (e.g., voice-assistant).
5. Select your Region and key type — choose Standard for most use cases.
6. Click Create and copy both the API Key (SID) and Secret immediately — the secret will not be shown again.

Purchase and configure a phone number

Purchase a number

1. Navigate to Phone Numbers → Manage → Buy a Number.
2. Select your country and choose capabilities (Voice, SMS).
3. Purchase the number.

Configure the webhook

1. Click on your purchased phone number to open its settings.
2. Under A call comes in, select Webhook from the dropdown.
3. Enter the following webhook URL:

   https://api.botphonic.ai/api/assistant/call/incoming/twillio
4. Set the HTTP method to HTTP POST.
5. Click Save.

Enable Geo Permissions

⚠️

This step is required for outbound calls to work correctly across different countries.

1. Go to Settings → Voice → Geo Permissions.
2. Open the Outbound tab.
3. Search for and enable (check) the relevant countries you need to call.

Setup

How it works

When a call arrives on your Twilio number, Twilio forwards it to our telephony bridge via a webhook. The assigned assistant takes over, handles the conversation, and can trigger downstream actions such as scheduling or CRM updates.

Incoming call → Twilio → Webhook → Telephony bridge → Voice assistant → Actions

For outbound calls, the assistant uses the Twilio REST API to dial out with your number as the caller ID.

Supported capabilities

Disconnecting

To remove the Twilio integration:

1. Go to Integrations in your dashboard.
2. Click Twilio → Disconnect.
3. Confirm the action.

Troubleshooting

Numbers are not importing after connecting. Verify that your Account SID and API Key belong to the same Twilio project. Sub-account credentials are not supported — use the master account credentials.

Calls connect but the assistant does not respond. Check your dashboard for any webhook delivery errors. Twilio logs failed webhook attempts under Monitor → Logs → Errors in the Twilio console.

The caller hears silence before the assistant speaks. This is typically a cold-start latency issue. Consider enabling assistant warm-up in your assistant settings to pre-initialize the model before the first utterance.

Outbound calls fail with a "21212" error. This Twilio error indicates the From number is not voice capable or is not owned by your account. Verify the number is active and voice-enabled in your Twilio console.

Outbound calls are not connecting to certain countries. Ensure the relevant countries are enabled under Settings → Voice → Geo Permissions → Outbound in your Twilio console.