> ## Documentation Index
> Fetch the complete documentation index at: https://chatbase.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer phone calls with your AI agent using Twilio

> Connect your Twilio account and assign phone numbers so your AI agent can answer inbound calls

The Chatbase Twilio integration connects your Twilio account to an AI agent so the AI agent answers inbound calls to your Twilio phone numbers. It's for businesses that want callers to get the same answers, Actions and instructions as their chat AI agent, in a voice they choose. You connect Twilio once, import the numbers you want, and turn them on in the Phone channel.

> [card] What you can do:
>
> Have your AI agent pick up the phone with the same knowledge, same Actions, same instructions as your chat AI agent, in a voice you choose.

> [!NOTE]
>
> Don't use Twilio? You can also connect an existing number from your own PBX, SIP provider, or GSM gateway using the [SIP trunk method](https://chatbase.co/docs/user-guides/integrations/sip-trunk.md).

## Before you start

* A Twilio account. If you don't have one, [sign up for Twilio](https://www.twilio.com/try-twilio).
* At least one phone number purchased in your Twilio account.
* Your Twilio **Account SID** and **Auth Token**, available on your [Twilio Console dashboard](https://console.twilio.com/).
* A Chatbase AI agent set up with the voice settings you want callers to hear. Configure voice, language, and greeting on your AI agent's **Build > Voice** page.
* The Basic plan or higher.

## How to connect Twilio

**1. Connect your Twilio account**

1. Navigate to your [Chatbase dashboard](https://www.chatbase.co/dashboard/) and select the AI agent you want to enable phone calls for.
2. Go to the **Integrations** tab in the left sidebar.
3. Find the **Twilio** card and click **Connect**.
4. Enter your **Account SID** and **Auth Token** from the [Twilio Console](https://console.twilio.com/).
   * **Account SID** starts with `AC` followed by 32 characters (for example, `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`).
   * **Auth Token** is a 32-character string.
5. Click **Connect Twilio**.

Chatbase validates your credentials against the Twilio API. Once connected, your Account SID is displayed in a read-only field.

> [!NOTE]
>
> Your Twilio credentials are encrypted before being stored. Chatbase never displays your Auth Token after the initial connection. Each AI agent has its own Twilio connection, so you can use the same or different Twilio accounts for different AI agents.

**2. Import phone numbers**

1. On the same Twilio integration page, click **Import from Twilio**.
2. A dialog shows the phone numbers in your Twilio account. It lists the first 50 numbers in the account.
3. Select the numbers you want to import, up to 20 at a time. For each, you can optionally set a **friendly name** to help identify it later, such as "Sales line" or "Support US".
4. Click **Import selected**.

Chatbase automatically configures a SIP trunk on your Twilio account and registers each number for call routing. Imported numbers start turned off, so they don't take calls until you enable them in the next step.

> [!NOTE]
>
> Each phone number can only be imported to one AI agent at a time. Numbers that are already imported appear grayed out in the import dialog.

**3. Enable a phone number**

1. Navigate to your AI agent's **Channels** page and open the **Phone** channel.
2. Go to the **Connections** tab.
3. Under **Assign phone numbers**, click **Assign a new number**.
4. Choose **Twilio number**, then select one or more numbers from the list of imported numbers.
5. Click **Assign selected**.
6. Make sure each number's toggle is on. A number that is off shows as **Paused** and doesn't take calls.

Enabled numbers show the phone number, an **Active** status with the toggle on, and the friendly name if one was set.

> [!TIP]
>
> Call one of your enabled numbers and confirm your AI agent answers with the greeting from its voice settings.

## How calls work

Once a phone number is enabled for an AI agent:

* **Inbound calls** to that number are automatically routed to the assigned AI agent.
* The AI agent uses its configured **voice settings** (voice provider, model, and language) to speak with the caller.
* The AI agent greets the caller with the **first message** defined in its voice settings.
* The conversation follows the AI agent's instructions, knowledge base, and Actions, just like a chat conversation.
* Each call creates a conversation entry in **Activity > Conversations** with the source marked as **Phone**.
* A call lasts at most 15 minutes by default. You can raise this up to 60 minutes with **Max call duration** on the [Voice](https://chatbase.co/docs/user-guides/chatbot/voice.md#limits) page.
* If the caller asks for a person, the [Transfer to phone number](https://chatbase.co/docs/user-guides/chatbot/actions/transfer-to-phone.md) Action can hand the call to a human. Chatbase turns on call transfer on the Twilio trunk for you.

### Example call

This is an example of a call to an AI agent for a store called Acme:

> **AI agent:** Hi, thanks for calling Acme. How can I help?
>
> **Caller:** Hi, I want to know if you ship to Canada.
>
> **AI agent:** Yes, we ship to Canada. Standard delivery takes 5 to 7 business days. Is there anything else I can help with?

The greeting comes from the **Initial message** in the AI agent's voice settings, and the answer comes from its Data Sources.

## Credits and costs

A phone call has two bills:

* **Chatbase:** each call uses **6 message credits per minute**, plus the AI model's usual message credits for each reply. Minutes are billed in full 60-second blocks, and the first minute is billed when the call starts. Chatbase charges no fee for the number or the trunk. See [Credit Usage](https://chatbase.co/docs/user-guides/chatbot/voice.md#credit-usage).
* **Twilio:** Twilio bills you directly for the number and the call minutes on your Twilio account.

A call only starts if your workspace has more than 6 message credits left, or if auto-recharge is on.

## Call limits

| Plan | Concurrent calls per workspace | Max call duration |
| - | - | - |
| Basic | 10 | 60 minutes |
| Business | 20 | 60 minutes |
| Enterprise | 20 | 60 minutes |

You can set lower limits for one AI agent under **Limits** on the [Voice](https://chatbase.co/docs/user-guides/chatbot/voice.md#limits) page, including **Allowed no. of daily calls**. The daily calls limit counts every call the AI agent takes in a UTC day, across all callers.

### What callers hear when a limit is reached

* **The call can't start** (the number is off, credits are too low, a call limit is reached, or the plan doesn't include the Phone channel): the caller hears no message. The phone just rings until the call times out.
* **The call reaches its duration limit:** the AI agent says "This call will end now as it has reached the call duration limit." and hangs up.
* **Credits run out during the call:** the AI agent says "This call will end now as it has reached the call limit." and hangs up.
* **An error occurs:** the AI agent plays the **Error message** from its voice settings, or "The voice session encountered an error. Please try again." if none is set.

## Managing phone numbers

### Disable a number

1. Go to your AI agent's **Channels** page, open the **Phone** channel, and go to the **Connections** tab.
2. Turn off the number's toggle. A "Phone number unassigned" message confirms it.

The number stops receiving calls but remains imported to this AI agent. Turn the toggle back on at any time to re-enable it.

### Delete a number from the Phone channel

1. On the **Connections** tab, click the menu icon (**⋯**) on the number and select **Delete**.
2. Confirm in the **Delete phone number?** dialog.

### Remove a number from the AI agent

1. Go to your AI agent's **Integrations** tab and click **Manage** on the Twilio card.
2. In the phone numbers table, click the menu icon next to the number and select **Remove**.

The number is removed from this AI agent but remains in your Twilio account. You can import it again at any time.

### Disconnect Twilio

1. Go to your AI agent's **Integrations** tab and click **Manage** on the Twilio card.
2. Click **Disconnect** in the danger zone at the bottom.

> [!WARNING]
>
> Disconnecting Twilio from an AI agent removes all imported phone numbers and deletes the SIP trunk from your Twilio account. This action cannot be undone. Your phone numbers remain in your Twilio account, but you'll need to reconnect and re-import them to use them again with this AI agent.

## Limitations

* **One AI agent per number.** A phone number can only be imported to one AI agent at a time. Numbers that belong to another AI agent are skipped on import.
* **Import limits.** The import dialog lists the first 50 numbers in your Twilio account, and you can import up to 20 at a time.
* **Basic plan or higher.** The Phone channel isn't available on other plans.
* **Disconnecting is destructive.** It removes every imported number and deletes the SIP trunk from your Twilio account.

## Troubleshooting

> [accordion] Calls ring but the AI agent never answers
>
> Check these in order:
>
> 1. The number's toggle is on in the Phone channel. Imported numbers start turned off.
> 2. Your workspace is on the Basic plan or higher.
> 3. Your workspace has more than 6 message credits left, or auto-recharge is on.
> 4. No concurrent or daily call limit has been reached, on the plan or under **Limits** on the [Voice](https://chatbase.co/docs/user-guides/chatbot/voice.md#limits) page.

> [accordion] A number is missing from the import dialog
>
> The dialog only lists the first 50 numbers in your Twilio account. A number that's already imported to another AI agent appears grayed out and can't be imported again until it's removed from that AI agent.

> [accordion] My Studio flow or webhook stopped getting calls
>
> The number is attached to the Chatbase trunk, so Twilio sends its calls to your AI agent instead. Remove the number from the Twilio integration page to return it to your Studio flow or webhook.

## Frequently asked questions

> [accordion] Which plan do I need for Twilio phone calls?
>
> The Basic plan or higher. Basic allows 10 concurrent calls per workspace, and Business and Enterprise allow 20.

> [accordion] How much does a phone call cost?
>
> 6 message credits per minute, plus the AI model's message credits for each reply. The first minute is billed when the call starts, and every started minute counts as a full minute. Twilio bills you separately for the number and call minutes.

> [accordion] Can I use the same Twilio account for several AI agents?
>
> Yes. Each AI agent has its own Twilio connection, so you can connect the same or different Twilio accounts. Each number can only be imported to one AI agent at a time.

> [accordion] Why is my imported number paused?
>
> Imported Twilio numbers start turned off. Turn on the number's toggle in the Phone channel's **Connections** tab to start taking calls.

> [accordion] How long can a call last?
>
> 15 minutes by default. You can change **Max call duration** on the [Voice](https://chatbase.co/docs/user-guides/chatbot/voice.md#limits) page, up to 60 minutes.

> [accordion] Can the AI agent transfer a call to a person?
>
> Yes, with the [Transfer to phone number](https://chatbase.co/docs/user-guides/chatbot/actions/transfer-to-phone.md) Action. Chatbase turns on call transfer on the Twilio trunk when you import numbers.

## Next steps

> [card] [SIP trunk](https://chatbase.co/docs/user-guides/integrations/sip-trunk.md)
>
> Connect a number you already own from a PBX, SIP provider, or GSM gateway.

> [card] [Transfer to phone number](https://chatbase.co/docs/user-guides/chatbot/actions/transfer-to-phone.md)
>
> Let the AI agent hand a live call to a human.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.