← All docs Channels

Twilio setup

Step-by-step Twilio number, SIP, and webhook configuration for phone.

Twilio phone setup

This guide walks you through connecting your own Twilio sub-account to BestAI so the AI receptionist can answer calls to your business number. It is a “bring your own carrier” setup — you keep ownership of the numbers and pay Twilio for carriage directly. BestAI manages the AI side.

If you have not used Twilio before, allow about 30 minutes for the full setup, including buying a number.

What you can do

  • Bring your own Twilio Account SID and Auth Token
  • Choose a Twilio region close to NZ
  • Add one or more E.164 phone numbers
  • Bind each number to a chatbot
  • Point Twilio’s voice webhook at BestAI

Before you start

You need:

  1. A Twilio account. We recommend creating a sub-account for BestAI so the billing stays separate. Sign up at twilio.com.
  2. A phone number on Twilio in E.164 format (for example +6499234567). NZ local, mobile, or toll-free numbers all work.
  3. A BestAI plan that includes phone — Starter, Professional, or Business. Chat-only plans do not include phone.
  4. At least one active chatbot that you want to bind the number to.

The included monthly minutes by plan:

PlanIncluded minutes per month
Starter ($49/month)100
Professional ($99/month)300
Business ($199/month)1000

Going over your included minutes does not cut your calls off. You will see a red progress bar in the admin and we will get in touch about an upgrade. Twilio’s own carriage charges are billed by Twilio directly, separate from your BestAI bill.

Step-by-step

1. Add your Twilio credentials in BestAI

  1. Sign in to BestAI as an Owner or Admin.
  2. Open Integrations, then Twilio.
  3. Fill in the form:
    • Account SID — the 34-character string from Twilio Console, starts with AC.
    • Auth Token — the 32-character string from Twilio Console under Auth Token. Click Show then copy.
    • Region — choose au1 for the lowest latency to NZ. Other options: ie1 (Europe), us1 (Americas), sg1 (Singapore).
    • Phone numbers — list each Twilio number in E.164 format, one per line.
  4. Click Test connection. BestAI checks that the SID looks right, the token is not empty, and the numbers are valid. This is a local check — it does not call Twilio’s paid API.
  5. Click Save. BestAI encrypts the Auth Token before storing it. From this point on, the admin only ever shows you a masked version like abcd****3456.

If you suspect your Auth Token is leaked, immediately roll it in Twilio Console, then re-enter the new token in BestAI.

2. Bind a phone number to a chatbot

  1. Open Phone numbers in the admin.
  2. Click Assign number.
  3. Pick a number from your Twilio list, then pick the chatbot to bind it to.
  4. Leave Direction as Inbound.
  5. Click Confirm.

A few rules:

  • Each phone number is bound to one chatbot. To change the chatbot, release the number and assign it again.
  • A phone number can only belong to one BestAI workspace at a time. Trying to bind a number that another customer is already using will fail.
  • Releasing a number does not delete past conversations. It just stops new calls coming in.

3. Configure the webhook in Twilio Console

  1. In Twilio Console, open Phone Numbers, then Manage, then Active numbers.
  2. Open the number you bound in step 2.
  3. Find the Voice Configuration section.
  4. Set A call comes in to Webhook.
  5. Set the URL to: 
    https://api.chat.yai.nz/public/twilio/<your-workspace-id>/voice
    For example, if your workspace ID is acme-cafe, the URL is https://api.chat.yai.nz/public/twilio/acme-cafe/voice.
  6. Set the HTTP method to POST.
  7. Leave Primary handler fails blank.
  8. Click Save Configuration.

BestAI checks the Twilio signature on every webhook request. If the signature does not match, the request is rejected. You do not need to configure anything extra for this.

4. Test an inbound call

  1. Pick up your phone and call your Twilio number.
  2. After a moment of ringing, you are connected to the AI receptionist.
  3. Have a normal conversation: “What are your opening hours?”, “Can I book in for next Friday?”.
  4. Hang up.
  5. Within 5 to 10 seconds, sign in to the BestAI admin and open Conversations.
  6. Set the channel filter to Phone.
  7. You should see your call, with caller ID, total seconds, and the full transcript.

If the conversation does not appear within 30 seconds:

  • In Twilio Console, open Monitor, then Logs, then Calls. Confirm Twilio recorded the inbound call. If it shows “failed”, check the error code there.
  • Re-check the webhook URL for typos in the workspace ID.
  • Confirm the Auth Token in BestAI matches the current token in Twilio Console.

Security and privacy

  • Encrypted at rest — your Twilio Auth Token is encrypted before being saved. Only the BestAI server can decrypt it during a request, and the original is never logged or shown.
  • Webhook signature — every Twilio request must carry a valid X-Twilio-Signature. Anything else is rejected.
  • Cross-workspace isolation — workspace ID, Twilio credentials, number binding, and stream tokens must all match the same workspace, otherwise the call is dropped.
  • Short-lived stream token — the audio stream token is valid for only 5 minutes, the minimum required to start the call.
  • Recording — BestAI does not record or save the call audio. We only save the text transcript and call metadata. If you need a recording for compliance, enable Call Recording in Twilio and store it in your own bucket. This approach respects the Privacy Act 2020 principle of data minimisation.

Fair use

  • One call is capped at 30 minutes. After that, BestAI hangs up cleanly.
  • A workspace can have up to 10 simultaneous calls.
  • Going over your monthly included minutes does not cut calls off — you only see a warning in the admin.

Troubleshooting

SymptomLikely causeFix
Twilio Console shows “webhook returned 403”Auth Token mismatch, or wrong Account SIDRe-enter the credentials in BestAI
Caller hears “This number is currently unavailable”Number not bound, or chatbot not activeOpen Phone numbers and check the binding; reactivate the chatbot
Call drops after a few secondsPlan does not include phone, or you are at the concurrent limitUpgrade or wait for other calls to end
Audio quality is poor or echoesTwilio region is far from NZ, or visitor’s network is unstableSwitch the region to au1
No transcript appearsSpeech recognition provider failureContact us — we will check the provider status

Common questions

Can I use SIP or another carrier instead of Twilio?

Today, BestAI supports Twilio Programmable Voice. Other SIP trunks and self-hosted PBX systems are on the roadmap.

Can the same Twilio account power more than one BestAI workspace?

No. Each phone number is unique to one BestAI workspace. Use Twilio sub-accounts to keep credentials separate per workspace.

Will BestAI use my Twilio credit?

Yes. Twilio bills you for the inbound call carriage and the Media Streams usage under your own Twilio agreement. BestAI tracks the minutes only for your plan usage display.

When will outbound calls be supported?

Outbound calling (the AI calling out from your number) is on the roadmap.

Can I store recordings in BestAI?

No. Enable Call Recording in Twilio and store the recordings in your own location.

Next steps