Щоб використовувати телефонію TotalVoice у Mavibot, потрібно отримати Access Token з панелі керування TotalVoice і ввести його в налаштуваннях інтеграції. TotalVoice — це бразильський телефонний сервіс, який тепер входить до групи Zenvia.
Бот може з'єднувати співробітника з клієнтом, переводити та завершувати дзвінки, отримувати записи дзвінків і надсилати події дзвінків у розмову. TotalVoice також надає вартість кожного дзвінка.
Отримання необхідних даних
- Створіть обліковий запис Zenvia Voice і поповніть баланс.
- Увійдіть до панелі керування. У нижньому лівому куті головного екрана, поруч із Access Token, натисніть значок копіювання.
Access Token — це єдиний ключ, який надає доступ до всього вашого облікового запису, включно зі здійсненням платних дзвінків. Не публікуйте його та не передавайте за межі вашої компанії.
Підключення
У налаштуваннях телефонії виберіть TotalVoice і введіть:
- Access Token — ключ з панелі керування TotalVoice.
-
Client-facing number — номер, який бачитиме клієнт, у форматі
+551140028922. Це поле необов'язкове. Якщо залишити його порожнім, буде використано номер за замовчуванням з вашого облікового запису TotalVoice.
Після збереження на сторінці підключення з'явиться notification 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 number is not specified" | Номер TotalVoice співробітника відсутній у його налаштуваннях. |
Статус nao_existe
|
Номер клієнта не існує. Перевірте формат. Бразильські мобільні номери використовують +55 + DDD + 9 цифр. |
Статус congestionado
|
Проблема з мережею оператора, не пов'язана з номером клієнта. Якщо проблема не зникає, зверніться до підтримки TotalVoice. |
| Немає посилання на запис | Дзвінок було створено з вимкненим записом або на дзвінок не відповіли. |