Skip to main content
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.

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

Before you start

  • A Twilio account. If you don’t have one, sign up for Twilio.
  • At least one phone number purchased in your Twilio account.
  • Your Twilio Account SID and Auth Token, available on your Twilio Console dashboard.
  • 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 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.
    • 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.
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.
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.
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 page.
  • If the caller asks for a person, the Transfer to phone number 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.
  • 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

You can set lower limits for one AI agent under Limits on the Voice 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.
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

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

The Basic plan or higher. Basic allows 10 concurrent calls per workspace, and Business and Enterprise allow 20.
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.
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.
Imported Twilio numbers start turned off. Turn on the number’s toggle in the Phone channel’s Connections tab to start taking calls.
15 minutes by default. You can change Max call duration on the Voice page, up to 60 minutes.
Yes, with the Transfer to phone number Action. Chatbase turns on call transfer on the Twilio trunk when you import numbers.

Next steps

SIP trunk

Connect a number you already own from a PBX, SIP provider, or GSM gateway.

Transfer to phone number

Let the AI agent hand a live call to a human.