Чтобы использовать телефонию TotalVoice в Mavibot, необходимо получить Access Token из панели управления TotalVoice и указать его в настройках интеграции. TotalVoice — это бразильский телефонный сервис, который теперь входит в группу Zenvia.
Бот может соединять сотрудника с клиентом, переводить и завершать звонки, получать записи разговоров и отправлять события звонков в диалог. TotalVoice также предоставляет стоимость каждого звонка.
Получение необходимых данных
- Создайте аккаунт Zenvia Voice и пополните баланс.
- Войдите в панель управления. В левом нижнем углу главного экрана, рядом с Access Token, нажмите на иконку копирования.
Access Token — это единственный ключ, который предоставляет доступ ко всему вашему аккаунту, включая совершение платных звонков. Не публикуйте его и не передавайте за пределами вашей компании.
Подключение
В настройках телефонии выберите TotalVoice и укажите:
- Access Token — ключ из панели управления TotalVoice.
-
Номер для клиента — номер, который увидит клиент, в формате
+551140028922. Это поле необязательно. Если оставить пустым, будет использоваться номер по умолчанию из вашего аккаунта TotalVoice.
После сохранения на странице подключения появится URL уведомлений. Его нужно добавить в панель управления TotalVoice — см. следующий раздел.
Интеграция подключена. Чтобы отключить её, очистите поле Access Token и сохраните настройки.
Настройка уведомлений
В отличие от других интеграций телефонии, URL уведомлений необходимо настраивать вручную, потому что TotalVoice не предоставляет Mavibot возможности сделать это автоматически.
- Скопируйте URL, показанный на странице подключения.
- В панели управления TotalVoice откройте Desenvolvedores → Configurações da API.
- Вставьте тот же URL во все три поля вебхуков:
- Status Tempo Real — изменения статуса звонка во время его выполнения;
- Chamada - Fim — завершение звонка;
- DID - Fim de Chamada — завершение входящего звонка на ваш номер.
⏳ Уведомления могут начать приходить только через 20 минут после сохранения настроек. Это ограничение TotalVoice. Если события не появляются в диалоге сразу после настройки, просто подождите.
Если вы перегенерируете Access Token, URL уведомлений изменится. Сохраните новый токен в Mavibot и обновите URL в панели управления TotalVoice, иначе события звонков перестанут приходить.
Сотрудники
В настройках сотрудника укажите номер TotalVoice сотрудника.
Можно использовать либо внутренний добавочный номер (
ramal, обычно 3–4 цифры), либо обычный мобильный номер в формате+5511987654321. Это одна из немногих интеграций, где формат гибкий: если сотрудник не использует внутренний добавочный номер АТС, укажите его мобильный номер.
Звонок с карточки клиента
Рядом с номером телефона клиента в карточке диалога появится кнопка звонка. TotalVoice сначала звонит сотруднику, и только после того, как сотрудник ответит, звонит клиенту.
Такой порядок выбран намеренно: клиент не будет слышать тишину на линии, потому что сотрудник уже подключён, когда телефон клиента начинает звонить.
Функции калькулятора
Звонок сотрудника клиенту
totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)
Параметры:
-
client_phone— номер телефона клиента в формате+5511987654321. Обязательный. -
employee_number— номер сотрудника: либо внутренний добавочный, либо мобильный номер. Обязательный. -
bina— номер, который увидит клиент. Необязательный. Если не указан, используется номер из настроек подключения. -
gravar_audio— записывать ли звонок. Необязательный. Запись включена по умолчанию.
Перевод звонка
totalvoice_transfer_call(number, call_id, leg)
Параметры:
-
number— номер, на который нужно перевести звонок. Обязательный. -
call_id— идентификатор звонка. Необязательный. Если не указан, используется последний звонок клиента. -
leg— какая сторона звонка переводится:destino(клиент, значение по умолчанию) илиorigem(сотрудник).
Завершение звонка
totalvoice_hangup_call(call_id)
Параметры:
-
call_id— идентификатор звонка. Необязательный. Если не указан, используется последний звонок клиента.
Получение ссылки на запись звонка
totalvoice_get_record_link(call_id)
Обычно ссылка на запись приходит автоматически вместе с событием завершения звонка. Эта функция полезна, если уведомление не было получено или нужна запись более старого звонка.
Параметры:
-
call_id— идентификатор звонка. Необязательный. Если не указан, используется последний звонок клиента.
Обратные вызовы во время звонка
По мере развития звонка в диалог отправляются обратные вызовы в следующем формате:
totalvoice_call_event atendida
Возможные события:
| Событие | Когда срабатывает |
|---|---|
chamando |
Звонок звонит |
preparando |
Линия подготавливается к соединению |
atendida |
Звонок принят |
sem_resposta |
Нет ответа |
ocupado |
Занято |
cancelada |
Звонок отменён |
congestionado |
Перегрузка сети оператора |
falha |
Звонок не удалось завершить |
nao_existe |
Номер не существует |
Названия статусов приходят на португальском языке, потому что это названия статусов, используемые TotalVoice.
Типичный сценарий «нет ответа → отправить сообщение в мессенджере» можно построить, проверив переменную totalvoice_call_answered.
Уведомления о статусе звонка отправляются не чаще одного раза в 2 секунды на звонок. Для очень коротких звонков некоторые промежуточные статусы могут не успеть прийти. Событие завершения звонка отправляется всегда.
Переменные клиента после звонка
| Переменная | Значение |
|---|---|
totalvoice_call_id |
Идентификатор звонка |
totalvoice_call_status |
Статус звонка по определению TotalVoice |
totalvoice_call_answered |
1 — звонок был принят, 0 — нет |
totalvoice_call_duration |
Продолжительность звонка в секундах |
totalvoice_call_price |
Стоимость звонка в бразильских реалах |
totalvoice_hangup_reason |
Причина завершения звонка |
totalvoice_record_link |
Ссылка на запись звонка |
Продолжительность означает фактическое время разговора, без учёта времени ожидания ответа. Имейте в виду, что TotalVoice рассчитывает тарификацию иначе: оплачиваемое время округляется до следующей полной минуты, поэтому 24-секундный звонок будет тарифицирован как одна минута. Для проверки расходов используйте отчёт о тарификации в панели управления TotalVoice, а не эту переменную.
Записи звонков
Запись настраивается отдельно для каждого звонка и включена по умолчанию. Вы можете отключить её для конкретного звонка с помощью параметра gravar_audio в функции звонка.
Когда звонок завершается, ссылка на запись приходит вместе с событием и сохраняется в переменную totalvoice_record_link. Запрашивать её отдельно не нужно.
Запись звонков регулируется законодательством. В Бразилии она подпадает под требования LGPD: клиент должен быть проинформирован о том, что звонок записывается, и должно быть законное основание для хранения данных. Владелец аккаунта TotalVoice несёт ответственность за соблюдение этих требований.
Устранение неполадок
| Ошибка | Причина / Решение |
|---|---|
| Звонок не создаётся, сообщение об ошибке на португальском | TotalVoice возвращает причину в виде текста. Наиболее частые причины — недостаточный баланс или неверный формат номера телефона. |
| Звонки работают, но обратные вызовы не появляются в диалоге | URL уведомлений не добавлен в панель управления TotalVoice, не добавлен во все три вебхука или не прошло 20 минут с момента настройки. |
| Раньше всё работало, но события внезапно прекратились | Access Token был перегенерирован, что изменило URL уведомлений. Сохраните новый токен в Mavibot и обновите URL в панели управления TotalVoice. |
| «Номер TotalVoice не указан» | В настройках сотрудника отсутствует номер TotalVoice. |
Статус nao_existe
|
Номер клиента не существует. Проверьте формат. Бразильские мобильные номера используют +55 + DDD + 9 цифр. |
Статус congestionado
|
Проблема с сетью оператора, не связанная с номером клиента. Если проблема сохраняется, обратитесь в поддержку TotalVoice. |
| Нет ссылки на запись | Звонок был создан с отключённой записью или звонок не был принят. |