Twilio is an international telecommunications provider. It allows the bot to call customers and connect them with your employees in any of the 100+ countries where Twilio offers phone numbers, including Mexico, Brazil, Turkey, Spain, Germany, France, the UAE, Thailand, Malaysia, and many others.

What you get after connecting Twilio:

  • call a customer with one click directly from the conversation card;
  • automated scenario-based calls — the bot calls the customer and reads a text message aloud;
  • group calls — the bot calls the customer and connects them to the first available employee;
  • recording of all calls, with a recording link stored in the order variables;
  • call events (ringing, answered, completed) directly in the conversation — you can use them to build scenarios.

Step 1. Create an Account and Buy a Number

  1. Sign up at twilio.com and complete the verification process.
  2. In the Twilio Console, open Phone Numbers → Buy a number and select a number in the country you need. Make sure Voice is enabled — some numbers support SMS only and cannot be used for calls.

Step 2. Copy Your Access Credentials

On the main page of the Twilio Console, under Account Info, you will find two values:

Item What it looks like
Account SID ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token hidden; click Show to reveal it

⚠️ Copy the Auth Token exactly as it appears, without any extra spaces before or after it. We use it to verify the authenticity of every request from Twilio. A single invisible extra character can result in calls working while call events do not appear in the conversation.

The Auth Token provides full access to your Twilio account and the funds in it. Do not send it through messengers or publish it anywhere.

Step 3. Connect Twilio in Your Account

Open Project → Integrations → Telephony → Twilio and fill in the three fields:

Field What to enter
Account SID from Step 2
Auth Token from Step 2
Twilio Number the number you purchased, in international format: +14155550100

The number must be entered in E.164 format: +, country code, and phone number, without spaces, parentheses, or hyphens.

After saving, a callback URL will appear on the page. Copy it. Then open the settings for your purchased number in the Twilio Console and, under Voice & Fax, configure:

  • A call comes in → Webhook → paste the copied URL and select HTTP POST.

Without this configuration, outgoing calls will work, but incoming calls and call events in the conversation will not.

To disconnect the integration, clear the Account SID field and save the settings.

Step 4. Add Employee Phone Numbers

Twilio calls employees on regular phone numbers — there are no internal extensions here.

Open the Team tab, select an employee, and fill in the Twilio Phone Number field with their full phone number in the same format:

+905551112233

Without this number, the call button in the customer card will not work for that employee.

Calling from the Customer Card

A call button will appear next to the customer's phone number in the conversation card. Clicking it starts the following sequence:

  1. Twilio calls the employee — the employee sees your Twilio number as the caller ID.
  2. The employee answers the call.
  3. Only then does Twilio call the customer and connect the two parties.

The order is intentional: the customer does not have to listen to ringing while the employee gets to their phone. If the employee does not answer, the customer is not called at all.

Calls from Bot Scenarios

Four methods are available in the calculator.

twilio_employee_call(client_phone, employee_phone, caller_id)

Connects an employee with a customer. It works the same way as the call button in the customer card: first the employee is called, and then the customer.

twilio_employee_call(client_phone, "+905551112233")

The third argument is optional. It specifies the phone number that the customer will see as the caller ID. By default, your Twilio number is used.

twilio_group_call(client_phone, employee_phones, caller_id)

Calls the customer and, once the customer answers, simultaneously calls all employees in the specified list. The call is connected to the first employee who answers.

twilio_group_call(client.phone, "+905551112233,+905554445566,+905557778899")

⚠️ The order is reversed here. Unlike the previous method, the customer answers first and may hear several seconds of silence while Twilio calls the employees. This is a Twilio limitation: calling a group simultaneously and connecting the first person who answers only works this way. If it is important that the customer does not have to wait, use twilio_employee_call.

twilio_play_message(client_phone, text, voice, language)

Calls the customer and reads the specified text using synthesized speech. This is useful for appointment reminders, order confirmations, and delivery notifications.

twilio_play_message(client.phone, "Hello! This is a reminder about your appointment tomorrow at 3:00 PM.", "alice", "en-EN")

The alice voice is universal and supports major languages, including tr-TR, es-ES, es-MX, pt-BR, de-DE, fr-FR, en-US, ru-RU, and ar-XA.

Always specify the language explicitly — otherwise Twilio may read the text using English pronunciation.

Do not include passwords, verification codes, or other sensitive information in the message: the call may be answered by voicemail.

Returns a link to the call recording. This is rarely needed because the link normally appears automatically (see the next section). It can be useful if the recording link was not received and needs to be requested again.

twilio_get_record_link()

If no argument is provided, the customer's most recent call is used.

Variables and Events

After each call, the bot stores the following variables in the customer's order:

Variable What it contains
twilio_call_id Twilio call identifier
twilio_call_disposition call result: completed, busy, no-answer, failed, canceled
twilio_call_duration call duration in seconds
twilio_record_link link to the recording
twilio_record_id Twilio recording identifier

Events in the format twilio_call_event <status> are sent to the conversation. You can use them as conditions in your scenarios:

Event When it is sent
twilio_call_event initiated the call has been created
twilio_call_event ringing the phone is ringing
twilio_call_event answered the call has been answered
twilio_call_event completed the call has ended
twilio_call_event busy / no-answer / failed / canceled the call could not be completed
twilio_call_event recording the call recording is ready

⚠️ Wait for the recording event before using the recording link, not the completed event. Twilio processes the recording file after the call has already ended. At the time the completed event is received, the twilio_record_link variable is still empty. A scenario that sends the recording to a manager or CRM must therefore be triggered by the recording event.

A typical "couldn't reach the customer — send them a message" scenario works like this: condition for twilio_call_event no-answer or busy → send a message to the customer.

Call Recordings

Recording is enabled by default for all calls involving an employee. Both sides of the conversation are recorded starting from the moment the call is answered. The files are stored in your Twilio account and are billed by Twilio.

⚠️ The twilio_record_link URL points directly to Twilio and is protected by your account credentials. You cannot simply open it in a browser or send it to a customer — an access error will be displayed. To download the recording, open the Twilio Console and go to Monitor → Logs → Calls, then find the call using its twilio_call_id.

⚖️ Call recording is regulated by law. In many countries — including Germany, France, Spain, and in many U.S. states — consent from both parties may be required, and in some cases a spoken notification must be played at the beginning of the call. As the owner of the Twilio account, you are responsible for complying with the applicable requirements. If these rules apply to you, begin the call with a recording notice or disable recording in your Twilio number settings.

Troubleshooting

The Call Is Not Created and an Authentication Error Is Returned

The Account SID or Auth Token is incorrect. Copy them again from the Twilio Console. The most common causes are an extra space or accidentally copying the Test Token instead of the main Auth Token.

Calls Work, but There Are No Events or Recordings in the Conversation

The callback URL has not been configured in the Twilio number settings (see Step 3), or it is configured with the wrong HTTP method. The method must be HTTP POST.

Another common cause is that the Auth Token was changed in Twilio but the old token is still configured in your account. In this case, request signatures no longer match, so all callbacks are rejected.

Error 21606 or "From number not valid"

The number entered in the Twilio Number field either was not purchased under your Twilio account or does not support voice calls.

Open Phone Numbers → Manage → Active numbers and make sure the number is listed and has Voice capability.

Error 21215 — Geo Permissions

By default, Twilio blocks calls to many countries as a fraud-prevention measure.

Open Voice → Settings → Geo Permissions and enable the destinations you need.

A Customer Calls, but a Conversation Card Is Created for the Employee's Number

The callback is configured with the wrong URL. Copy the callback URL from the integration page again, making sure to copy the entire URL, including everything after the question mark.

Trial Account: Twilio Plays a Voice Message Before the Call

This is standard behavior for Twilio trial accounts. Trial accounts can also call only verified phone numbers.

Add funds to your account and upgrade to a full Twilio account.