Centro de ayuda de Aircall | Widgets de Smartflows: documentación técnica de Llamar a (mediante API)

El widget Distribución inteligente: Llamar a (mediante API) utiliza una respuesta de la API para determinar a qué usuario, equipo, número interno o número externo de Aircall se debe dirigir una llamada, en función de los datos almacenados fuera de Aircall.

Este widget ofrece funciones de distribución dinámica potentes y flexibles al conectar Aircall con sistemas de terceros, como CRM o centros de ayuda.

Importante: El widget Llamar a (mediante API) solo está disponible en el plan Professional. Para actualizar tu plan, ponte en contacto con tu gestor de cuenta de Aircall.

Requisitos previos

Antes de configurar el widget, asegúrate de que se cumplen los siguientes requisitos.

Credenciales de autenticación

El método de autenticación depende de la plataforma externa cuyos datos quieras recuperar. Los métodos compatibles incluyen:

Autenticación básica
Token de portador
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integraciones > Claves API en el Panel de control de Aircall.
Genera una nueva clave API.
Guarda tanto el ID de la clave API como el token.
En la configuración del widget Llamar a (mediante API), ve a Credenciales y establece:
- Nombre de usuario = ID de la clave API
- Contraseña = token de la API

Obtén más información sobre cómo encontrar tu clave API de Aircall en nuestro artículo Dónde encontrar mi clave API de Aircall.

Conocimiento de la API de la plataforma

Debes conocer la estructura y los endpoints de la API pública de la plataforma externa.

Aunque Dónde encontrar mi clave API de Aircall utiliza la API de Aircall como ejemplo, también puedes usar plataformas como HubSpot, Salesforce, Zendesk, Intercom, Pipedrive o CRM internos.

Conocimiento de JSON

El widget utiliza JSON (notación de objetos de JavaScript) para intercambiar datos con las API. Debes estar familiarizado con las estructuras básicas de JSON para configurar correctamente las rutas de datos.

Consejo: Si necesitas ayuda para configurar el widget, nuestro equipo técnico puede ofrecerte asistencia de consultoría e implementación. Ponte en contacto con nuestro equipo de gestión de cuentas.

Consideraciones de uso

El widget Llamar a (mediante API) permite la distribución dinámica («inteligente») de llamadas basada en datos externos. Puede consultar cualquier sistema compatible con API REST y métodos de autenticación estándar.

Nota: Las solicitudes realizadas por Llamar a (mediante API) agotarán el tiempo de espera después de 10 segundos. Asegúrate de que tu endpoint responda dentro de este límite de tiempo; de lo contrario, es posible que el widget no pueda recuperar el destino de distribución.

La respuesta de la API debe devolver los datos en un formato que Aircall pueda interpretar para la distribución. Los tipos de respuesta compatibles incluyen:

Tipo de respuesta	Descripción
Usuario	Dirige la llamada a un agente específico mediante su ID de usuario de Aircall o su correo electrónico.
Equipo	Dirige la llamada a un equipo específico de Aircall mediante su ID de equipo.
Número de Aircall	Dirige la llamada internamente a otro número de Aircall mediante su ID de número.
Número externo	Dirige la llamada externamente a un número de teléfono (debe estar en formato internacional E.164).
Destino dinámico (ID)	Permite que tu API externa especifique dinámicamente tanto el tipo de destino como el ID de destino.

Al utilizar Destino dinámico (ID), debes definir dos rutas JSON en el widget:

Ruta al tipo de destino (usuario, equipo, número o externo)
Ruta al valor de destino (el ID único del destino)

Nota: Para las respuestas de Destino dinámico, el widget solo acepta los siguientes valores para el tipo de destino: agent, team, internal y external.

Si el destino resuelto es un equipo, se aplican las reglas de llamada estándar. Si es un usuario o un número, estas reglas no se aplican.

Cualquier lógica avanzada (por ejemplo, distribución condicional o priorización) debe procesarse en tu sistema externo antes de devolver la respuesta de la API.

Pasos de configuración

El widget determina si debe llamar a un Usuario, Equipo, Número de Aircall, Número externo o Destino dinámico (ID) en función de la llamada a la API configurada.

Pasos:

En el editor de Smartflows, añade un widget Llamar a (mediante API).
Elige el método HTTP (GET o POST), en función de la sección de la API que quieras utilizar.
- Ejemplo: Al utilizar el endpoint Buscar llamadas de la API de Aircall, selecciona GET.
Introduce la URL de la API, por ejemplo:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Esto busca las llamadas más recientes asociadas al número de teléfono de la persona que llama.
Utiliza variables como callerNumber, targetNumber o callUUID para insertar dinámicamente en tu solicitud datos específicos de la llamada. Consulta la documentación de la API de Aircall para ver una lista completa de los parámetros de consulta.

Configuración de la respuesta

En la sección Configuración de la respuesta, define cómo se analizará la respuesta de la API para determinar el destino de distribución.

Tipos de respuesta compatibles:

Usuario (ID o correo electrónico)
Equipo (ID)
Número de Aircall (interno)
Número externo (formato E.164)
Destino dinámico (ID)

Ejemplo de ruta JSON:

calls[0].user.id

Esta ruta hace referencia al primer elemento de la matriz “calls” y obtiene el ID del usuario.

Ejemplo de respuesta JSON del destino dinámico:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}

Ruta al tipo de destino: calls[0].target_type
Ruta al valor de destino: calls[0].target_id

Si el tipo de destino es equipo, se aplicarán las reglas de llamada correspondientes.

Probar la configuración

Utiliza el campo Respuesta de prueba para simular solicitudes de API y confirmar que las rutas configuradas devuelven los valores correctos.

Ejemplo de entrada de prueba:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Cada clave del JSON corresponde a una variable utilizada en la URL o el cuerpo de la solicitud. Al ejecutar la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

Si se produce un error, consulta la sección Errores de la documentación de la API de Aircall para obtener orientación sobre la resolución de problemas.

Ajustes de llamada

Después de configurar y probar la integración de la API, ajusta los Ajustes de llamada para definir cómo se distribuyen las llamadas. Estos ajustes funcionan de la misma manera que los del widget estándar Llamar a.

Para obtener más información, consulta nuestro artículo del Centro de ayuda Descripción general del enrutamiento de Smartflows.

Consejo: Si te interesa aprovechar esta función, pero no dispones de conocimientos técnicos, ponte en contacto con nuestro equipo de gestión de cuentas, que te pondrá en contacto con nuestro equipo técnico para ofrecerte asistencia y orientación sobre la implementación.

Este widget ofrece funciones de distribución dinámica potentes y flexibles al conectar Aircall con sistemas de terceros, como CRM o centros de ayuda.

Importante: El widget Llamar a (mediante API) solo está disponible en el plan Professional. Para actualizar tu plan, ponte en contacto con tu gestor de cuenta de Aircall.

Requisitos previos

Antes de configurar el widget, asegúrate de que se cumplen los siguientes requisitos.

Credenciales de autenticación

El método de autenticación depende de la plataforma externa cuyos datos quieras recuperar. Los métodos compatibles incluyen:

Autenticación básica
Token de portador
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integraciones > Claves API en el Panel de control de Aircall.
Genera una nueva clave API.
Guarda tanto el ID de la clave API como el token.
En la configuración del widget Llamar a (mediante API), ve a Credenciales y establece:
- Nombre de usuario = ID de la clave API
- Contraseña = token de la API

Obtén más información sobre cómo encontrar tu clave API de Aircall en nuestro artículo Dónde encontrar mi clave API de Aircall.

Conocimiento de la API de la plataforma

Debes conocer la estructura y los endpoints de la API pública de la plataforma externa.

Conocimiento de JSON

Consejo: Si necesitas ayuda para configurar el widget, nuestro equipo técnico puede ofrecerte asistencia de consultoría e implementación. Ponte en contacto con nuestro equipo de gestión de cuentas.

Consideraciones de uso

Nota: Las solicitudes realizadas por Llamar a (mediante API) agotarán el tiempo de espera después de 10 segundos. Asegúrate de que tu endpoint responda dentro de este límite de tiempo; de lo contrario, es posible que el widget no pueda recuperar el destino de distribución.

La respuesta de la API debe devolver los datos en un formato que Aircall pueda interpretar para la distribución. Los tipos de respuesta compatibles incluyen:

Tipo de respuesta	Descripción
Usuario	Dirige la llamada a un agente específico mediante su ID de usuario de Aircall o su correo electrónico.
Equipo	Dirige la llamada a un equipo específico de Aircall mediante su ID de equipo.
Número de Aircall	Dirige la llamada internamente a otro número de Aircall mediante su ID de número.
Número externo	Dirige la llamada externamente a un número de teléfono (debe estar en formato internacional E.164).
Destino dinámico (ID)	Permite que tu API externa especifique dinámicamente tanto el tipo de destino como el ID de destino.

Al utilizar Destino dinámico (ID), debes definir dos rutas JSON en el widget:

Ruta al tipo de destino (usuario, equipo, número o externo)
Ruta al valor de destino (el ID único del destino)

Nota: Para las respuestas de Destino dinámico, el widget solo acepta los siguientes valores para el tipo de destino: agent, team, internal y external.

Si el destino resuelto es un equipo, se aplican las reglas de llamada estándar. Si es un usuario o un número, estas reglas no se aplican.

Cualquier lógica avanzada (por ejemplo, distribución condicional o priorización) debe procesarse en tu sistema externo antes de devolver la respuesta de la API.

Pasos de configuración

El widget determina si debe llamar a un Usuario, Equipo, Número de Aircall, Número externo o Destino dinámico (ID) en función de la llamada a la API configurada.

Pasos:

En el editor de Smartflows, añade un widget Llamar a (mediante API).
Elige el método HTTP (GET o POST), en función de la sección de la API que quieras utilizar.
- Ejemplo: Al utilizar el endpoint Buscar llamadas de la API de Aircall, selecciona GET.
Introduce la URL de la API, por ejemplo:
```
https://api.aircall.io/v1/calls/search?order=desc&phone_number={{callerNumber}}
```
Esto busca las llamadas más recientes asociadas al número de teléfono de la persona que llama.
Utiliza variables como callerNumber, targetNumber o callUUID para insertar dinámicamente en tu solicitud datos específicos de la llamada. Consulta la documentación de la API de Aircall para ver una lista completa de los parámetros de consulta.

Configuración de la respuesta

En la sección Configuración de la respuesta, define cómo se analizará la respuesta de la API para determinar el destino de distribución.

Tipos de respuesta compatibles:

Usuario (ID o correo electrónico)
Equipo (ID)
Número de Aircall (interno)
Número externo (formato E.164)
Destino dinámico (ID)

Ejemplo de ruta JSON:

calls[0].user.id

Esta ruta hace referencia al primer elemento de la matriz “calls” y obtiene el ID del usuario.

Ejemplo de respuesta JSON del destino dinámico:

{
  "calls": [
    {
      "target_type": "team",
      "target_id": 12345
    }
  ]
}

Ruta al tipo de destino: calls[0].target_type
Ruta al valor de destino: calls[0].target_id

Si el tipo de destino es equipo, se aplicarán las reglas de llamada correspondientes.

Probar la configuración

Utiliza el campo Respuesta de prueba para simular solicitudes de API y confirmar que las rutas configuradas devuelven los valores correctos.

Ejemplo de entrada de prueba:

{
  "callerNumber": "+15551234567",
  "targetNumber": "+15557654321",
  "callUUID": "abcd-1234-efgh-5678",
  "lineId": 12345
}

Cada clave del JSON corresponde a una variable utilizada en la URL o el cuerpo de la solicitud. Al ejecutar la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

Si se produce un error, consulta la sección Errores de la documentación de la API de Aircall para obtener orientación sobre la resolución de problemas.

Ajustes de llamada

Para obtener más información, consulta nuestro artículo del Centro de ayuda Descripción general del enrutamiento de Smartflows.

Consejo: Si te interesa aprovechar esta función, pero no dispones de conocimientos técnicos, ponte en contacto con nuestro equipo de gestión de cuentas, que te pondrá en contacto con nuestro equipo técnico para ofrecerte asistencia y orientación sobre la implementación.