Centro de ayuda de Aircall | Widgets de flujo de llamadas: documentación técnica de «Llamar a» (mediante API)

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

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

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

Requisitos previos

Antes de configurar el widget, asegúrate de que se cumplan 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 de API
OAuth

Ejemplo (API de Aircall):

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

Obtén más información sobre cómo encontrar tu clave de API de Aircall en nuestro artículo Dónde encontrar mi clave de 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 de API de Aircall utiliza la API de Aircall como ejemplo, también puedes utilizar 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 conocer 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 servicios de consultoría y asistencia con la 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 la distribución.

La respuesta de la API debe devolver 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 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 como el ID del 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 del 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, esas reglas no se aplican.

Cualquier lógica avanzada (p. ej., 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 de API configurada.

Pasos:

En el editor de flujos, añade un widget Llamar a (mediante API).
Elige el método HTTP (GET o POST), según 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 la 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 la 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 recupera el ID de usuario.

Ejemplo de respuesta JSON de 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 team, se aplicarán las reglas de timbre correspondientes.

Probar la configuración

Utiliza el campo Probar respuesta para simular solicitudes de API y confirmar que las rutas configuradas devuelvan 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 en 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 ayuda para solucionar el problema.

Configuración de timbre

Después de configurar y probar la integración de la API, ajusta la Configuración de timbre para definir cómo se distribuyen las llamadas. Esta configuración funciona igual que la 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 del flujo de llamadas

Consejo: Si te interesa aprovechar esta función, pero no dispones de los conocimientos técnicos necesarios, 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 potentes y flexibles de distribución dinámica al conectar Aircall con sistemas de terceros, como CRM o centros de ayuda.

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

Requisitos previos

Antes de configurar el widget, asegúrate de que se cumplan 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 de API
OAuth

Ejemplo (API de Aircall):

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

Obtén más información sobre cómo encontrar tu clave de API de Aircall en nuestro artículo Dónde encontrar mi clave de 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

El widget utiliza JSON (notación de objetos de JavaScript) para intercambiar datos con las API. Debes conocer 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 servicios de consultoría y asistencia con la 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 la distribución.

La respuesta de la API debe devolver 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 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 como el ID del 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 del 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, esas reglas no se aplican.

Cualquier lógica avanzada (p. ej., 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 de API configurada.

Pasos:

En el editor de flujos, añade un widget Llamar a (mediante API).
Elige el método HTTP (GET o POST), según 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 la 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 la 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 recupera el ID de usuario.

Ejemplo de respuesta JSON de 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 team, se aplicarán las reglas de timbre correspondientes.

Probar la configuración

Utiliza el campo Probar respuesta para simular solicitudes de API y confirmar que las rutas configuradas devuelvan 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 en 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 ayuda para solucionar el problema.

Configuración de timbre

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

Consejo: Si te interesa aprovechar esta función, pero no dispones de los conocimientos técnicos necesarios, 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.