Twilio

Buy a Twilio number through PolyAI, or connect your own Twilio account and route its numbers to your agent.

For basic Twilio number and SMS setup, see Voice > Numbers > Twilio.

Agent Studio gives you two ways to use Twilio. Both start in the same place:

1. Open your project in Agent Studio and go to Integrations.
2. Open the Telephony tab and click Add number.
3. In the Add a number panel, under Transfer or buy a number, choose a Twilio option.

Option	Who owns the number	Use it when
Buy Twilio number	PolyAI buys and manages the number for you.	You need a new number and don’t want to manage a Twilio account.
Connect Twilio account	The number stays in your own Twilio account.	You already own Twilio numbers that callers know.

If an option shows Coming soon, contact your PolyAI account manager.

Buy Twilio number

PolyAI buys the number, manages it, and routes it to your agent. Calls reach the agent as soon as the number is bought. Usage is billed through PolyAI at 1.5¢ per minute.

Buy a number

1. Open the buy panel

   In the Add a number panel, click Buy Twilio number.

2. Choose a country

   Pick a Country: United Kingdom, United States, Canada, Australia or Ireland.

   Some countries need regulatory approval before you can buy. See Regulatory approval below.

3. (Optional) Enter an area code

   For United States and Canada, an Area code field appears. Enter three digits, such as 415.

   PolyAI only searches the area code you enter. It does not fall back to a nearby one. If that area code is sold out, the purchase fails. Leave the field blank to take any available number in the country.

4. Choose an environment

   Pick the Environment that should answer calls on this number. This field is required.

5. (Optional) Choose a variant

   If your agent has variants, a Variant field appears. Pick one to send calls on this number to that variant. Leave it as Default (no variant) to use the default agent.

6. Buy the number

   Click Buy number. When the purchase finishes, the panel closes and the number appears in the Telephony table with its environment and variant. Calls to it go straight to your agent.

   If the purchase fails, Agent Studio shows Couldn’t buy the number with the reason. Try again, or try without an area code.

Use separate numbers for each environment so test calls never reach Live.

Regulatory approval

On some accounts, local regulations require an approved regulatory bundle before you can buy a number in the United Kingdom, Australia or Ireland. If this applies to you, a warning appears after you choose the country, and Buy number stays disabled.

Message	What it means	What to do
[Country] needs regulatory approval	No approved bundle exists for this country yet.	Click Go to Numbers, submit your bundle on the Voice > Numbers page, then come back.
[Country] approval is under review	Your bundle is submitted and waiting for approval.	Wait. Review usually takes 1 to 7 business days. You can buy once it’s approved.
Couldn’t check regulatory approval for [Country]	Agent Studio couldn’t check your bundle status.	Click Try again. Buying stays blocked until the check succeeds.

A bundle covers every project in your account, so you only submit it once per country.

If your account is on a trial that can’t go live yet, the panel shows an upgrade prompt instead of the form.

Delete a bought number

1. In the Telephony table, open the actions menu on the number.
2. Click Delete number and confirm.

Calls to the number stop reaching your agent and the number is released. You can’t undo this.

Connect Twilio account

Use phone numbers you already own. They stay in your Twilio account. You bring your Twilio API credentials and your numbers. PolyAI uses the credentials to create the SIP trunks your Twilio account needs to send calls to your agent. You don’t write TwiML, raise a PolyAI ticket, or negotiate a shared SIP trunk.

Only one telephony integration can be connected to a project at a time. If the project already has one, the Connect Twilio account option is disabled, and the card shows why:

• Twilio is already connected to this project.
• Only one telephony integration can be connected to a project at a time, and this project already has one.

Before you start

In the Twilio Console, collect:

• Account SID: shown in the Account Info panel on the console dashboard.
• API key and API secret: go to Account > API keys & tokens and click Create API key. Use a Standard key. Twilio shows the secret only once, so copy it before you close the dialog.

Also make a list of the Twilio numbers you want to route to PolyAI, and decide which environment each one should serve.

Connect your account

1. Open the Twilio setup

   In the Add a number panel, click Connect Twilio account.

2. Enter your Twilio credentials

   On Step 1: Twilio account credentials, fill in all three fields:

   • Api Key
   • API Secret
   • Account SID

   Click Continue.

3. Add your numbers to each environment

   On Step 2: Inbound routing, add the Twilio numbers that should reach your agent in each environment. You can add more than one number per environment.

   • Live: numbers that reach your published agent.
   • Pre-release (shown as Staging in some projects): numbers for testing before you go live.
   • Sandbox: leave this empty. Sandbox has no channel connections, so test there with an in-app call instead.

   Enter each number in E.164 format: a +, the country code, then the number, with no spaces (for example, [phone]).

4. Connect

   Click Connect. PolyAI creates the SIP trunk on your Twilio account and routes each number to the environment you chose.

5. Set up handoffs

   After you connect, Agent Studio asks you to Update handoff configuration. Click Take me there to set up transfers to your human agents now, or Dismiss to do it later.

Configure handoffs

Twilio hands calls back to your agents with a SIP REFER. You don’t choose the handoff method for Twilio. Set up transfer destinations in Handoffs. See Call handoffs for the full reference.

Remove a number

1. In the Telephony table, open the actions menu on the number.
2. Click Delete number and confirm.

Calls to the number stop reaching your agent. You can’t undo this.

Related pages

• Voice > Numbers > Twilio: basic Twilio number and SMS setup
• Buy a number from PolyAI: buying numbers from the Numbers page
• Call handoffs: configure transfer destinations
• Environments: how Sandbox, Pre-release and Live receive calls
• Voice integrations: other voice platforms