Aircall

Щоб використовувати телефонію Aircall у Mavibot, потрібно створити пару API-ключів у вашому акаунті Aircall і ввести їх у налаштуваннях інтеграції.

Aircall — це хмарна телефонна система для відділів продажів і підтримки, яка пропонує телефонні номери в понад 100 країнах. Вона розроблена для компаній, співробітники яких уже використовують застосунок Aircall: бот здійснює дзвінки від імені співробітника, а не з окремого номера бота.

Бот може з'єднати співробітника з клієнтом, отримувати записи дзвінків і надсилати події дзвінків у розмову.

Отримання необхідних даних

1. Зареєструйтеся на aircall.io, придбайте телефонний номер у потрібній країні та створіть користувачів Aircall для ваших співробітників.
2. Відкрийте Dashboard → Settings → Integrations & API → API Keys і створіть пару ключів:
   • API ID
   • API Token
3. Знайдіть Number ID для номера, який використовуватиметься для вихідних дзвінків, і User IDs для ваших співробітників. Ці ідентифікатори видно в адресному рядку, коли ви відкриваєте відповідні сторінки в панелі керування Aircall.

API Token показується лише один раз під час створення. Якщо ви його втратили, створіть нову пару API-ключів і відкличте стару.

Підключення

У налаштуваннях телефонії виберіть Aircall і введіть:

• API ID — ідентифікатор API-ключа.
• API Token — секретний API-токен.
• Number ID — числовий ідентифікатор лінії Aircall, яка використовуватиметься для вихідних дзвінків.

Інтеграцію підключено.

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

Співробітники

У налаштуваннях співробітника заповніть поле Aircall User ID числовим ідентифікатором акаунта Aircall співробітника.

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

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

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

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

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

Функції калькулятора

Дзвінок співробітника клієнту

aircall_employee_call(client_phone, employee_user_id, number_id)

Параметри:

• client_phone — номер телефону клієнта в міжнародному форматі E.164. Обов'язковий.
• employee_user_id — ідентифікатор користувача Aircall співробітника, який отримає дзвінок у своєму застосунку Aircall. Обов'язковий.
• number_id — ідентифікатор номера Aircall, який використовується для здійснення дзвінка. Необов'язковий. Якщо пропущено, використовується номер, налаштований у параметрах інтеграції.

Отримати посилання на запис дзвінка

aircall_get_record_link(call_id)

Запитує свіже посилання на запис дзвінка.

Параметри:

• call_id — ідентифікатор дзвінка Aircall. Необов'язковий. Якщо пропущено, використовується останній дзвінок клієнта.

Зворотні виклики під час дзвінка

Під час дзвінка в розмову надсилаються зворотні виклики у такому форматі:

aircall_call_event call.answered

Можливі події:

Подія	Коли спрацьовує
call.created	Дзвінок створено
call.ringing_on_agent	Співробітник отримує дзвінок
call.answered	Дзвінок прийнято
call.hungup	Одна зі сторін завершила дзвінок
call.ended	Дзвінок повністю завершено
call.voicemail_left	Клієнт залишив голосове повідомлення

Типовий сценарій «немає відповіді → надіслати повідомлення в месенджер» можна запустити за допомогою call.ended і перевірки змінної aircall_missed_reason.

Змінні клієнта після дзвінка

Після дзвінка для клієнта доступні такі змінні:

Змінна	Значення
aircall_call_id	Ідентифікатор дзвінка Aircall
aircall_call_direction	Напрямок дзвінка: inbound або outbound
aircall_call_status	Статус дзвінка: initial, answered або done
aircall_call_duration	Тривалість дзвінка в секундах
aircall_missed_reason	Причина, чому дзвінок не було завершено
aircall_record_link	Посилання на запис дзвінка

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

Запис дзвінків має бути ввімкнено в налаштуваннях Aircall. Записи зберігаються у вашому акаунті Aircall.

⏳ Посилання на записи Aircall доступні обмежений час — зазвичай лише кілька годин після дзвінка. Після цього посилання перестають працювати. Це особливість роботи Aircall, а не обмеження Mavibot.

Що це означає:

• У сценарії, який надсилає запис дзвінка, викликайте aircall_get_record_link() у момент надсилання запису, а не використовуйте раніше збережене посилання.
• Якщо потрібно зберегти запис назавжди, збережіть файл у власному сховищі одразу після дзвінка.
• Архів записів залишається доступним у панелі керування Aircall, де записи можна відтворювати та завантажувати пізніше.

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

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

Помилка	Причина / Рішення
Помилка авторизації під час здійснення дзвінка	Пара API ID / API Token неправильна. Токен показується лише один раз під час створення. Якщо його втрачено, створіть нову пару в розділі API Keys і відкличте стару.
Дзвінок не створюється або співробітник не отримує дзвінок	Співробітник офлайн у застосунку Aircall, уже розмовляє по іншому дзвінку або не призначений на вибраний номер у налаштуваннях Aircall.
«Aircall User ID не вказано»	Поле Aircall User ID у налаштуваннях співробітника порожнє або замість числового ідентифікатора користувача введено номер телефону.
Дзвінки працюють, але в розмові не з'являються зворотні виклики	Вебхук не зареєстровано. Збережіть налаштування інтеграції Aircall ще раз, щоб зареєструвати його.
Посилання на запис не відкривається	Термін дії посилання минув. Запитайте свіже посилання за допомогою aircall_get_record_link() або відкрийте запис безпосередньо в панелі керування Aircall.