Para usar la telefonía de VoIPstudio en Mavibot, necesitas crear una clave API en tu cuenta de VoIPstudio, ingresarla en la configuración de la integración y configurar la entrega de eventos a la URL que Mavibot muestra después de conectar la integración.
VoIPstudio es una PBX en la nube con números de teléfono disponibles en más de 70 países. A diferencia de un operador de telecomunicaciones tradicional, admite usuarios internos, grupos de llamada, colas y menús de IVR, mientras que el bot opera sobre esta PBX.
El bot puede iniciar llamadas a clientes en nombre de los empleados, transferir y finalizar llamadas, guardar grabaciones y enviar eventos de llamada a la conversación.
Obtención de la información necesaria
- Regístrate en voipstudio.com y compra un número de teléfono en el país requerido.
- Crea usuarios en la PBX: uno para cada empleado que recibirá llamadas. Las llamadas se entregan a todos los dispositivos registrados de un usuario, por lo que no necesitas especificar un número de teléfono separado para cada empleado.
- Ve a Configuración → API, crea una Clave API y cópiala.
Conexión de la integración
En la configuración de telefonía, selecciona VoIPstudio e ingresa:
- Clave API: la clave de tu cuenta de VoIPstudio.
La integración ahora está conectada. Para desconectarla, borra el campo Clave API y guarda la configuración.
Después de guardar, aparecerá una URL de notificación en la página. Cópiala:
https://chatter.mavibot.ai/voipstudio_webhook/
No publiques esta URL ni la compartas con nadie. Si desconectas y vuelves a conectar la integración, la clave sigue siendo la misma, por lo que no necesitarás configurar las notificaciones nuevamente.
Luego, en tu cuenta de VoIPstudio, ve a Integraciones → Webhooks → Habilitar → Agregar webhook, pega la URL copiada y selecciona los siguientes eventos:
- Cambio de estado de llamada: o selecciona individualmente Llamada sonando, Llamada conectada, Llamada finalizada y Llamada perdida;
- Grabación de llamada lista: si necesitas grabaciones de llamadas.
Sin esta configuración, las llamadas salientes seguirán funcionando, pero los eventos de llamada no aparecerán en la conversación.
Empleados
En la configuración del empleado, completa el campo ID de usuario de VoIPstudio: el identificador numérico del usuario en tu PBX, por ejemplo 10002.
Ingresa el ID de usuario de la PBX, no un número de teléfono. Puedes encontrar el ID en la lista de usuarios de tu cuenta de VoIPstudio. Sin él, el botón de llamada en la tarjeta del cliente no funcionará para ese empleado.
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.
VoIPstudio primero llama al empleado en todos sus dispositivos registrados simultáneamente. Una vez que el empleado contesta, VoIPstudio llama al cliente y conecta a ambas partes.
Si el empleado no contesta, no se llamará al cliente.
Funciones de la calculadora
Llamada de empleado a cliente
voipstudio_employee_call(client_phone, employee_user_id, caller_id)
Parámetros:
- client_phone: el número de teléfono del cliente. Obligatorio.
- employee_user_id: el ID de usuario de VoIPstudio del empleado que debe recibir la primera llamada. Obligatorio.
-
caller_id: el número de teléfono que se muestra al cliente. Opcional. Puedes pasar
anonymouspara ocultar el identificador de llamada.
Transferir una llamada
voipstudio_transfer_call(phone, call_id)
Transfiere una llamada activa a otro número de teléfono.
Parámetros:
- phone: el número de teléfono al que se debe transferir la llamada. Obligatorio y debe ser el primer parámetro.
-
call_id: el identificador de la llamada. Opcional. Si se omite, se toma la llamada actual del cliente de la variable
voipstudio_call_id.
Finalizar una llamada
voipstudio_hangup_call(call_id)
Finaliza una llamada activa.
Parámetros:
- call_id: el identificador de la llamada. Opcional. Si se omite, se usa la llamada actual del cliente.
Obtener un enlace de grabación de llamada
voipstudio_get_record_link(call_id)
Devuelve un enlace a la grabación de la llamada. El enlace normalmente se guarda automáticamente cuando se recibe el evento de grabación lista. Esta función es útil si ese evento no se recibió.
Parámetros:
- call_id: el identificador de la llamada. Opcional. Si se omite, se usa la llamada actual del cliente.
La función busca las 100 grabaciones más recientes en la cuenta. Para una llamada más antigua en una PBX de alto volumen, es posible que no encuentre la grabación. En ese caso, recupera la grabación directamente desde tu cuenta de VoIPstudio.
Callbacks durante una llamada
A medida que avanza la llamada, se envían callbacks a la conversación en el siguiente formato:
voipstudio_call_event call.hangup
El nombre del evento se pasa exactamente como se recibe de VoIPstudio, por ejemplo call.ringing, call.connected, call.hangup y otros. Los eventos disponibles dependen de los eventos que seleccionaste al configurar las notificaciones.
Si no se proporciona un nombre de evento, se usa el estado de la llamada en su lugar:
INITIAL, RINGING, CONNECTED, ON_HOLD, HANGUP.
Se envía un callback separado cuando la grabación está lista:
voipstudio_call_event recording
Espera el callback
recordingantes de usar el enlace de grabación. La grabación se procesa después de que la llamada ha terminado, por lo que la variablevoipstudio_record_linkaún está vacía cuando se recibecall.hangup.
Si dos empleados dentro de tu propia PBX están hablando entre sí, no se envían callbacks a la conversación y no se crea una tarjeta de cliente.
Variables del cliente después de una llamada
| Variable | Valor |
|---|---|
| voipstudio_call_id | ID de llamada en VoIPstudio |
| voipstudio_call_state | Estado de la llamada: INITIAL, RINGING, CONNECTED, ON_HOLD, HANGUP
|
| voipstudio_call_duration | Duración de la llamada en segundos |
| voipstudio_call_cause | Motivo por el que terminó la llamada |
| voipstudio_terminated_by | Quién terminó la llamada: caller o callee
|
| voipstudio_record_link | Enlace a la grabación de la llamada |
| voipstudio_record_id | ID de grabación en VoIPstudio |
Grabaciones de llamadas
La grabación de llamadas se habilita en la configuración de VoIPstudio y es gestionada por la propia PBX. Si necesitas grabaciones, habilita la grabación de llamadas en tu cuenta de VoIPstudio y selecciona el evento Grabación de llamada lista al configurar las notificaciones.
La URL
voipstudio_record_linkestá protegida por una clave de acceso. No se puede abrir directamente en un navegador ni compartir con un cliente. Puedes descargar la grabación desde tu cuenta de VoIPstudio en la sección de historial de llamadas.
La grabación de llamadas está sujeta a las leyes aplicables. En Alemania, Francia, España y la mayoría de los estados de EE. UU., puede ser necesario el consentimiento de ambas partes, y en algunas jurisdicciones también puede ser necesario un aviso hablado al inicio de la llamada. El propietario de la cuenta de VoIPstudio es responsable de cumplir con estos requisitos.
Solución de problemas
| Error | Causa |
|---|---|
| Error de autorización al crear una llamada | La Clave API es incorrecta o ha expirado. Asegúrate de que la clave se creó en Configuración → API y no se obtuvo mediante una solicitud login. |
| Las llamadas funcionan, pero no aparecen callbacks en la conversación | No se ha creado un webhook en VoIPstudio, el interruptor Habilitar está desactivado o se ingresó una URL incorrecta. Copia la URL completa desde la página de integración, incluida la clave al final. |
| No se puede crear la llamada o los dispositivos del empleado no suenan | Se ingresó un número de teléfono en lugar del ID de usuario de VoIPstudio, o el usuario no tiene dispositivos registrados. |
No se recibe el callback recording
|
La grabación de llamadas no está habilitada en VoIPstudio, o no se seleccionó el evento Grabación de llamada lista. |
VoIPstudio se factura directamente por VoIPstudio: hay una tarifa de suscripción por cada usuario de la PBX, más cargos por llamada. Esto difiere de los operadores que cobran por minuto sin una suscripción recurrente. Al estimar costos, ten en cuenta el número de usuarios configurados, no solo el volumen de llamadas.