Para usar la telefonía de TotalVoice en Mavibot, necesitas obtener un Access Token desde el panel de TotalVoice e ingresarlo en la configuración de la integración. TotalVoice es un servicio de telefonía brasileño que ahora forma parte del grupo Zenvia.

El bot puede conectar a un empleado con un cliente, transferir y finalizar llamadas, recuperar grabaciones de llamadas y enviar eventos de llamada a la conversación. TotalVoice también proporciona el costo de cada llamada.

Obtención de los datos necesarios

  1. Crea una cuenta de Zenvia Voice y agrega fondos a tu saldo.

  1. Inicia sesión en el panel. En la esquina inferior izquierda de la pantalla principal, junto a Access Token, haz clic en el ícono de copiar.

Access Token es la única clave que proporciona acceso a toda tu cuenta, incluida la realización de llamadas de pago. No lo publiques ni lo compartas fuera de tu empresa.

Conexión

En la configuración de telefonía, selecciona TotalVoice e ingresa:

  • Access Token — la clave del panel de TotalVoice.
  • Número visible para el cliente — el número que verá el cliente, en el formato +551140028922. Este campo es opcional. Si se deja vacío, se usará el número predeterminado de tu cuenta de TotalVoice.


Después de guardar, aparecerá una URL de notificación en la página de conexión. Debes agregarla al panel de TotalVoice; consulta la siguiente sección.

La integración ahora está conectada. Para desconectarla, limpia el campo Access Token y guarda la configuración.

Configuración de notificaciones

A diferencia de otras integraciones de telefonía, la URL de notificación debe configurarse manualmente porque TotalVoice no proporciona una forma para que Mavibot lo haga automáticamente.

  1. Copia la URL que se muestra en la página de conexión.

  1. En el panel de TotalVoice, abre Desenvolvedores → Configurações da API.
  2. Pega la misma URL en los tres campos de webhook:
    • Status Tempo Real — cambios de estado de la llamada mientras está en curso;
    • Chamada - Fim — fin de una llamada;
    • DID - Fim de Chamada — fin de una llamada entrante a tu número.

⏳ Las notificaciones pueden tardar hasta 20 minutos en comenzar a llegar después de guardar la configuración. Esta es una limitación de TotalVoice. Si no aparecen eventos en la conversación inmediatamente después de la configuración, solo espera.

Si regeneras tu Access Token, la URL de notificación cambiará. Guarda el nuevo token en Mavibot y actualiza la URL en el panel de TotalVoice; de lo contrario, los eventos de llamada dejarán de llegar.

Empleados

En la configuración del empleado, ingresa el número de TotalVoice del empleado.


Puedes usar una extensión interna (ramal, generalmente de 3 a 4 dígitos) o un número móvil regular en el formato +5511987654321. Esta es una de las pocas integraciones donde el formato es flexible: si el empleado no usa una extensión de PBX interna, ingresa su número móvil.

Llamar desde la tarjeta del cliente

Aparecerá un botón de llamada junto al número de teléfono del cliente en la tarjeta de conversación. TotalVoice primero llama al empleado, y solo después de que el empleado contesta, llama al cliente.

Este orden es intencional: el cliente no escuchará silencio en la línea porque el empleado ya está conectado cuando el teléfono del cliente comienza a sonar.

Funciones de la calculadora

Llamada de empleado a cliente

totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)

Parámetros:

  • client_phone — el número de teléfono del cliente en el formato +5511987654321. Obligatorio.
  • employee_number — el número del empleado: ya sea una extensión interna o un número móvil. Obligatorio.
  • bina — el número que verá el cliente. Opcional. Si se omite, se usa el número de la configuración de conexión.
  • gravar_audio — si se debe grabar la llamada. Opcional. La grabación está habilitada por defecto.

Transferir llamada

totalvoice_transfer_call(number, call_id, leg)

Parámetros:

  • number — el número al que se debe transferir la llamada. Obligatorio.
  • call_id — el identificador de la llamada. Opcional. Si se omite, se usa la llamada más reciente del cliente.
  • leg — qué lado de la llamada transferir: destino (el cliente, valor predeterminado) o origem (el empleado).

Finalizar llamada

totalvoice_hangup_call(call_id)

Parámetros:

  • call_id — el identificador de la llamada. Opcional. Si se omite, se usa la llamada más reciente del cliente.

Obtener enlace de grabación de llamada

totalvoice_get_record_link(call_id)

Normalmente, el enlace de grabación se recibe automáticamente con el evento de fin de llamada. Esta función es útil si no se recibió la notificación o si necesitas una grabación de una llamada más antigua.

Parámetros:

  • call_id — el identificador de la llamada. Opcional. Si se omite, se usa la llamada más reciente del cliente.

Callbacks durante una llamada

A medida que avanza la llamada, se envían callbacks a la conversación en el siguiente formato:

totalvoice_call_event atendida

Posibles eventos:

Evento Cuándo se activa
chamando La llamada está sonando
preparando La línea se está preparando para la conexión
atendida La llamada ha sido contestada
sem_resposta Sin respuesta
ocupado Ocupado
cancelada La llamada fue cancelada
congestionado Congestión de la red del operador
falha La llamada no pudo completarse
nao_existe El número no existe

Los nombres de los estados se reciben en portugués porque son los nombres de estado utilizados por TotalVoice.

Se puede construir un escenario típico de "sin respuesta → enviar un mensaje en el messenger" verificando la variable totalvoice_call_answered.

Las notificaciones de estado de llamada se envían como máximo una vez cada 2 segundos por llamada. Para llamadas muy cortas, algunos estados intermedios pueden no llegar a tiempo. El evento de fin de llamada siempre se envía.

Variables del cliente después de una llamada

Variable Valor
totalvoice_call_id Identificador de la llamada
totalvoice_call_status Estado de la llamada según TotalVoice
totalvoice_call_answered 1 — la llamada fue contestada, 0 — no fue contestada
totalvoice_call_duration Duración de la llamada en segundos
totalvoice_call_price Costo de la llamada en reales brasileños
totalvoice_hangup_reason Razón por la que terminó la llamada
totalvoice_record_link Enlace a la grabación de la llamada

La duración significa tiempo real de conversación, excluyendo el tiempo de espera para que la llamada sea contestada. Ten en cuenta que TotalVoice calcula la facturación de manera diferente: el tiempo facturable se redondea al minuto completo siguiente, por lo que una llamada de 24 segundos se facturará como un minuto. Para verificar los cargos, usa el informe de facturación en el panel de TotalVoice en lugar de esta variable.

Grabaciones de llamadas

La grabación se configura por separado para cada llamada y está habilitada por defecto. Puedes deshabilitarla para una llamada específica usando el parámetro gravar_audio en la función de llamada.

Cuando termina la llamada, el enlace de grabación se recibe con el evento y se guarda en la variable totalvoice_record_link. No necesitas solicitarlo por separado.

La grabación de llamadas está regulada por la ley. En Brasil, está sujeta a los requisitos de la LGPD: el cliente debe ser informado de que la llamada está siendo grabada, y debe haber una base legal para almacenar los datos. El propietario de la cuenta de TotalVoice es responsable de cumplir con estos requisitos.

Solución de problemas

Error Causa / Solución
La llamada no se crea y el mensaje de error está en portugués TotalVoice devuelve la razón como texto. Las causas más comunes son saldo insuficiente o un formato de número de teléfono inválido.
Las llamadas funcionan, pero no aparecen callbacks en la conversación La URL de notificación no se ha agregado al panel de TotalVoice, no se ha agregado a los tres webhooks, o no han pasado 20 minutos desde la configuración.
Todo funcionaba antes, pero los eventos se detuvieron repentinamente El Access Token fue regenerado, lo que cambió la URL de notificación. Guarda el nuevo token en Mavibot y actualiza la URL en el panel de TotalVoice.
"Número de TotalVoice no especificado" Falta el número de TotalVoice del empleado en su configuración.
Estado nao_existe El número del cliente no existe. Verifica el formato. Los números móviles brasileños usan +55 + DDD + 9 dígitos.
Estado congestionado Hay un problema con la red del operador y no está relacionado con el número del cliente. Si el problema persiste, contacta al soporte de TotalVoice.
Sin enlace de grabación La llamada se creó con la grabación deshabilitada, o la llamada no fue contestada.