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
- Navigate to your Chatbase dashboard and select the AI agent you want to enable phone calls for.
- Go to the Integrations tab in the left sidebar.
- Find the Twilio card and click Connect.
- Enter your Account SID and Auth Token from the Twilio Console.
- Account SID starts with
ACfollowed by 32 characters (for example,ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). - Auth Token is a 32-character string.
- Account SID starts with
- Click Connect Twilio.
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
- On the same Twilio integration page, click Import from Twilio.
- A dialog shows the phone numbers in your Twilio account. It lists the first 50 numbers in the account.
- 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”.
- Click Import selected.
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
- Navigate to your AI agent’s Channels page and open the Phone channel.
- Go to the Connections tab.
- Under Assign phone numbers, click Assign a new number.
- Choose Twilio number, then select one or more numbers from the list of imported numbers.
- Click Assign selected.
- Make sure each number’s toggle is on. A number that is off shows as Paused and doesn’t take calls.
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.
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
- Go to your AI agent’s Channels page, open the Phone channel, and go to the Connections tab.
- Turn off the number’s toggle. A “Phone number unassigned” message confirms it.
Delete a number from the Phone channel
- On the Connections tab, click the menu icon (⋯) on the number and select Delete.
- Confirm in the Delete phone number? dialog.
Remove a number from the AI agent
- Go to your AI agent’s Integrations tab and click Manage on the Twilio card.
- In the phone numbers table, click the menu icon next to the number and select Remove.
Disconnect Twilio
- Go to your AI agent’s Integrations tab and click Manage on the Twilio card.
- Click Disconnect in the danger zone at the bottom.
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
Calls ring but the AI agent never answers
Calls ring but the AI agent never answers
Check these in order:
- The number’s toggle is on in the Phone channel. Imported numbers start turned off.
- Your workspace is on the Basic plan or higher.
- Your workspace has more than 6 message credits left, or auto-recharge is on.
- No concurrent or daily call limit has been reached, on the plan or under Limits on the Voice page.
A number is missing from the import dialog
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.
My Studio flow or webhook stopped getting calls
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
Which plan do I need for Twilio phone calls?
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.
How much does a phone call cost?
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.
Can I use the same Twilio account for several AI agents?
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.
Why is my imported number paused?
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.
How long can a call last?
How long can a call last?
15 minutes by default. You can change Max call duration on the Voice page, up to 60 minutes.
Can the AI agent transfer a call to a person?
Can the AI agent transfer a call to a person?
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.