Para usar la telefonía de Aircall en Mavibot, necesitas crear un par de claves API en tu cuenta de Aircall e ingresarlas en la configuración de la integración.

Aircall es un sistema telefónico basado en la nube para equipos de ventas y soporte, que ofrece números de teléfono en más de 100 países. Está diseñado para empresas cuyos empleados ya usan la aplicación Aircall: el bot realiza llamadas en nombre de un empleado, no desde un número de bot separado.

El bot puede conectar a un empleado con un cliente, recuperar grabaciones de llamadas y enviar eventos de llamada a la conversación.

Obtención de los datos necesarios

  1. Regístrate en aircall.io, compra un número de teléfono en el país requerido y crea usuarios de Aircall para tus empleados.
  2. Abre Dashboard → Settings → Integrations & API → API Keys y crea un par de claves:
    • API ID
    • API Token
  3. Encuentra el Number ID para el número que se usará para llamadas salientes y los User IDs para tus empleados. Estos IDs son visibles en la barra de direcciones cuando abres las páginas correspondientes en el panel de Aircall.

API Token se muestra solo una vez cuando se crea. Si lo pierdes, crea un nuevo par de claves API y revoca el anterior.

Conexión

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

  • API ID — el identificador de la clave API.
  • API Token — el token API secreto.
  • Number ID — el ID numérico de la línea de Aircall que se usará para llamadas salientes.

La integración ahora está conectada.


Para desconectar la integración, limpia el campo API ID y guarda la configuración.

Empleados

En la configuración del empleado, completa el campo Aircall User ID con el ID numérico de la cuenta de Aircall del empleado.

Ingresa el ID de usuario, no el número de teléfono del empleado. Sin este ID, 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.

Aircall primero inicia la llamada en la aplicación Aircall del empleado — en escritorio o móvil. Una vez que el empleado contesta, Aircall llama al cliente y conecta a ambas partes.

La llamada no se realizará si el empleado está sin conexión, ya en otra llamada, o no está asignado al número seleccionado en Aircall. Esta es una limitación de Aircall: las llamadas solo se pueden realizar a través de un usuario disponible.

Funciones de la Calculadora

Llamada de Empleado a Cliente

aircall_employee_call(client_phone, employee_user_id, number_id)

Parámetros:

  • client_phone — el número de teléfono del cliente en formato internacional E.164. Obligatorio.
  • employee_user_id — el ID de usuario de Aircall del empleado que recibirá la llamada en su aplicación Aircall. Obligatorio.
  • number_id — el ID del número de Aircall utilizado para realizar la llamada. Opcional. Si se omite, se usa el número configurado en la configuración de la integración.

Obtener Enlace de Grabación de Llamada

aircall_get_record_link(call_id)

Solicita un enlace nuevo a la grabación de la llamada.

Parámetros:

  • call_id — el ID de la llamada de Aircall. 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:

aircall_call_event call.answered

Posibles eventos:

Evento Cuándo se activa
call.created La llamada ha sido creada
call.ringing_on_agent El empleado está recibiendo la llamada
call.answered La llamada ha sido contestada
call.hungup Una de las partes ha colgado
call.ended La llamada ha terminado por completo
call.voicemail_left El cliente dejó un mensaje de voz

Un escenario típico de "no respuesta → enviar un mensaje en el messenger" se puede activar con call.ended y verificando la variable aircall_missed_reason.

Variables del Cliente Después de una Llamada

Después de una llamada, las siguientes variables están disponibles para el cliente:

Variable Valor
aircall_call_id ID de la llamada de Aircall
aircall_call_direction Dirección de la llamada: inbound o outbound
aircall_call_status Estado de la llamada: initial, answered o done
aircall_call_duration Duración de la llamada en segundos
aircall_missed_reason Razón por la que la llamada no se completó
aircall_record_link Enlace a la grabación de la llamada

Grabaciones de Llamadas

La grabación de llamadas debe estar habilitada en tu configuración de Aircall. Las grabaciones se almacenan en tu cuenta de Aircall.

⏳ Los enlaces de grabación de Aircall están disponibles por tiempo limitado — típicamente solo por varias horas después de la llamada. Después de eso, los enlaces dejan de funcionar. Así funciona Aircall y no es una limitación de Mavibot.

Lo que esto significa:

  • En un escenario que envía una grabación de llamada, llama a aircall_get_record_link() en el momento en que se envía la grabación en lugar de usar un enlace guardado previamente.
  • Si necesitas conservar una grabación permanentemente, guarda el archivo en tu propio almacenamiento inmediatamente después de la llamada.
  • El archivo de grabaciones permanece disponible en el panel de Aircall, donde las grabaciones se pueden reproducir y descargar más tarde.

La grabación de llamadas está regulada por la ley. En Alemania, Francia, España y muchos estados de EE. UU., puede ser necesario el consentimiento de ambas partes, y en algunas jurisdicciones también puede ser necesaria una notificación verbal al inicio de la llamada. El propietario de la cuenta de Aircall es responsable de cumplir con las leyes y regulaciones aplicables.

Solución de Problemas

Error Causa / Solución
Error de autorización al realizar una llamada El par API ID / API Token es incorrecto. El token se muestra solo una vez cuando se crea. Si se ha perdido, crea un nuevo par en API Keys y revoca el anterior.
La llamada no se crea o el empleado no recibe la llamada El empleado está sin conexión en la aplicación Aircall, ya está en otra llamada, o no está asignado al número seleccionado en la configuración de Aircall.
"Aircall User ID no especificado" El campo Aircall User ID en la configuración del empleado está vacío, o se ingresó un número de teléfono en lugar del ID de usuario numérico.
Las llamadas funcionan, pero no aparecen callbacks en la conversación El webhook no fue registrado. Guarda la configuración de la integración de Aircall nuevamente para registrarlo.
El enlace de grabación no se abre El enlace ha expirado. Solicita un enlace nuevo usando aircall_get_record_link() o abre la grabación directamente en el panel de Aircall.