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 User ID сотрудника, который получит звонок в своем приложении Aircall. Обязательный.
• number_id — ID номера Aircall, используемого для звонка. Необязательный. Если не указан, используется номер, настроенный в параметрах интеграции.

Получение ссылки на запись звонка

aircall_get_record_link(call_id)

Запрашивает актуальную ссылку на запись звонка.

Параметры:

• call_id — 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	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.