Twilio — міжнародний телекомунікаційний провайдер. Він дозволяє боту телефонувати клієнтам і з'єднувати їх з вашими співробітниками в будь-якій з понад 100 країн, де Twilio пропонує телефонні номери, включаючи Мексику, Бразилію, Туреччину, Іспанію, Німеччину, Францію, ОАЕ, Таїланд, Малайзію та багато інших.

Що ви отримаєте після підключення Twilio:

  • дзвінок клієнту одним кліком безпосередньо з картки розмови;
  • автоматизовані дзвінки за сценарієм — бот телефонує клієнту та вголос зачитує текстове повідомлення;
  • групові дзвінки — бот телефонує клієнту та з'єднує його з першим доступним співробітником;
  • запис усіх дзвінків, з посиланням на запис, що зберігається в змінних замовлення;
  • події дзвінка (виклик, відповідь, завершення) безпосередньо в розмові — ви можете використовувати їх для побудови сценаріїв.

Крок 1. Створіть обліковий запис і придбайте номер

  1. Зареєструйтеся на twilio.com і пройдіть процес верифікації.
  2. У консолі Twilio відкрийте Phone Numbers → Buy a number і виберіть номер у потрібній країні. Переконайтеся, що Voice увімкнено — деякі номери підтримують лише SMS і не можуть використовуватися для дзвінків.

Крок 2. Скопіюйте свої облікові дані

На головній сторінці консолі Twilio, у розділі Account Info, ви знайдете два значення:

Пункт Як виглядає
Account SID ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Auth Token прихований; натисніть Show, щоб побачити його

⚠️ Скопіюйте Auth Token точно так, як він відображається, без зайвих пробілів до або після нього. Ми використовуємо його для перевірки автентичності кожного запиту від Twilio. Один непомітний зайвий символ може призвести до того, що дзвінки працюватимуть, але події дзвінків не з'являтимуться в розмові.

Auth Token надає повний доступ до вашого облікового запису Twilio та коштів на ньому. Не надсилайте його через месенджери та не публікуйте ніде.


Крок 3. Підключіть Twilio у своєму акаунті

Відкрийте Проєкт → Інтеграції → Телефонія → Twilio і заповніть три поля:

Поле Що ввести
Account SID з кроку 2
Auth Token з кроку 2
Twilio Number придбаний номер у міжнародному форматі: +14155550100

Номер потрібно вводити у форматі E.164: +, код країни та номер телефону, без пробілів, дужок або дефісів.

Після збереження на сторінці з'явиться callback URL. Скопіюйте його. Потім відкрийте налаштування придбаного номера в консолі Twilio та в розділі Voice & Fax налаштуйте:

  • A call comes in → Webhook → вставте скопійовану URL-адресу та виберіть HTTP POST.

Без цього налаштування вихідні дзвінки працюватимуть, але вхідні дзвінки та події дзвінків у розмові — ні.

Щоб відключити інтеграцію, очистіть поле Account SID і збережіть налаштування.


Крок 4. Додайте номери телефонів співробітників

Twilio телефонує співробітникам на звичайні телефонні номери — тут немає внутрішніх коротких номерів.

Відкрийте вкладку Команда, виберіть співробітника та заповніть поле Twilio Phone Number його повним номером телефону в тому ж форматі:

+905551112233

Без цього номера кнопка дзвінка в картці клієнта не працюватиме для цього співробітника.


Дзвінок з картки клієнта

Поруч із номером телефону клієнта в картці розмови з'явиться кнопка дзвінка. Натискання на неї запускає наступну послідовність:

  1. Twilio телефонує співробітнику — співробітник бачить ваш номер Twilio як ідентифікатор абонента.
  2. Співробітник відповідає на дзвінок.
  3. Лише тоді Twilio телефонує клієнту та з'єднує обидві сторони.

Такий порядок навмисний: клієнту не доведеться слухати гудки, поки співробітник добирається до телефону. Якщо співробітник не відповідає, клієнту взагалі не телефонують.


Дзвінки зі сценаріїв бота

У калькуляторі доступні чотири методи.

twilio_employee_call(client_phone, employee_phone, caller_id)

З'єднує співробітника з клієнтом. Працює так само, як кнопка дзвінка в картці клієнта: спочатку телефонують співробітнику, а потім клієнту.

twilio_employee_call(client_phone, "+905551112233")

Третій аргумент необов'язковий. Він вказує номер телефону, який клієнт бачитиме як ідентифікатор абонента. За замовчуванням використовується ваш номер Twilio.

twilio_group_call(client_phone, employee_phones, caller_id)

Телефонує клієнту та, коли клієнт відповідає, одночасно телефонує всім співробітникам зі вказаного списку. Дзвінок з'єднується з першим співробітником, який відповів.

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

⚠️ Тут порядок зворотний. На відміну від попереднього методу, клієнт відповідає першим і може чути кілька секунд тиші, поки Twilio телефонує співробітникам. Це обмеження Twilio: одночасний виклик групи та з'єднання з першим, хто відповів, працює лише так. Якщо важливо, щоб клієнт не чекав, використовуйте twilio_employee_call.

twilio_play_message(client_phone, text, voice, language)

Телефонує клієнту та зачитує вказаний текст за допомогою синтезованої мови. Це корисно для нагадувань про зустрічі, підтверджень замовлень і сповіщень про доставку.

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

Голос alice є універсальним і підтримує основні мови, включаючи tr-TR, es-ES, es-MX, pt-BR, de-DE, fr-FR, en-US, ru-RU та ar-XA.

Завжди явно вказуйте мову — інакше Twilio може прочитати текст з англійською вимовою.

Не включайте в повідомлення паролі, коди підтвердження або іншу чутливу інформацію: на дзвінок може відповісти автовідповідач.

Повертає посилання на запис дзвінка. Це рідко потрібно, оскільки посилання зазвичай з'являється автоматично (див. наступний розділ). Може бути корисним, якщо посилання на запис не було отримано і його потрібно запитати ще раз.

twilio_get_record_link()

Якщо аргумент не вказано, використовується останній дзвінок клієнта.


Змінні та події

Після кожного дзвінка бот зберігає наступні змінні в замовленні клієнта:

Змінна Що містить
twilio_call_id ідентифікатор дзвінка Twilio
twilio_call_disposition результат дзвінка: completed, busy, no-answer, failed, canceled
twilio_call_duration тривалість дзвінка в секундах
twilio_record_link посилання на запис
twilio_record_id ідентифікатор запису Twilio

Події у форматі twilio_call_event <статус> надсилаються в розмову. Ви можете використовувати їх як умови у своїх сценаріях:

Подія Коли надсилається
twilio_call_event initiated дзвінок створено
twilio_call_event ringing телефон дзвонить
twilio_call_event answered на дзвінок відповіли
twilio_call_event completed дзвінок завершено
twilio_call_event busy / no-answer / failed / canceled дзвінок не вдалося завершити
twilio_call_event recording запис дзвінка готовий

⚠️ Чекайте на подію recording перед використанням посилання на запис, а не на подію completed. Twilio обробляє файл запису після того, як дзвінок уже завершився. На момент отримання події completed змінна twilio_record_link ще порожня. Тому сценарій, який надсилає запис менеджеру або CRM, має запускатися подією recording.

Типовий сценарій "не вдалося додзвонитися до клієнта — надішліть йому повідомлення" працює так: умова для twilio_call_event no-answer або busy → надіслати повідомлення клієнту.


Записи дзвінків

Запис увімкнено за замовчуванням для всіх дзвінків за участю співробітника. Обидві сторони розмови записуються, починаючи з моменту відповіді на дзвінок. Файли зберігаються у вашому обліковому записі Twilio та тарифікуються Twilio.

⚠️ URL-адреса twilio_record_link вказує безпосередньо на Twilio і захищена обліковими даними вашого акаунта. Ви не можете просто відкрити її в браузері або надіслати клієнту — буде показано помилку доступу. Щоб завантажити запис, відкрийте консоль Twilio та перейдіть до Monitor → Logs → Calls, потім знайдіть дзвінок за його twilio_call_id.

⚖️ Запис дзвінків регулюється законом. У багатьох країнах — включаючи Німеччину, Францію, Іспанію та в багатьох штатах США — може знадобитися згода обох сторін, а в деяких випадках на початку дзвінка має відтворюватися усне повідомлення. Як власник облікового запису Twilio, ви несете відповідальність за дотримання застосовних вимог. Якщо ці правила застосовуються до вас, почніть дзвінок із повідомлення про запис або вимкніть запис у налаштуваннях вашого номера Twilio.


Усунення несправностей

Дзвінок не створюється, і повертається помилка автентифікації

Account SID або Auth Token неправильний. Скопіюйте їх ще раз із консолі Twilio. Найпоширеніші причини — зайвий пробіл або випадкове копіювання тестового токена замість основного Auth Token.

Дзвінки працюють, але в розмові немає подій або записів

Callback URL не налаштовано в налаштуваннях номера Twilio (див. Крок 3), або він налаштований з неправильним методом HTTP. Метод має бути HTTP POST.

Інша поширена причина — Auth Token було змінено в Twilio, але в акаунті все ще налаштовано старий токен. У цьому випадку підписи запитів більше не збігаються, тому всі зворотні виклики відхиляються.

Помилка 21606 або "From number not valid"

Номер, введений у полі Twilio Number, або не був придбаний у вашому обліковому записі Twilio, або не підтримує голосові дзвінки.

Відкрийте Phone Numbers → Manage → Active numbers і переконайтеся, що номер є в списку та має можливість Voice.

Помилка 21215 — Geo Permissions

За замовчуванням Twilio блокує дзвінки до багатьох країн як запобіжний захід проти шахрайства.

Відкрийте Voice → Settings → Geo Permissions і ввімкніть потрібні напрямки.

Клієнт телефонує, але картка розмови створюється для номера співробітника

Callback налаштовано з неправильною URL-адресою. Скопіюйте callback URL зі сторінки інтеграції ще раз, переконавшись, що ви скопіювали всю URL-адресу, включаючи все після знака питання.

Пробний акаунт: Twilio відтворює голосове повідомлення перед дзвінком

Це стандартна поведінка для пробних акаунтів Twilio. Пробні акаунти також можуть телефонувати лише на перевірені номери телефонів.

Поповніть баланс акаунта та оновіть його до повного акаунта Twilio.