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

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

Este widget ofrece capacidades potentes y flexibles de enrutamiento dinámico al conectar Aircall con sistemas de terceros, como CRM o centros de ayuda.

Importante: El widget Enviar a (mediante API) está disponible solo en el plan Professional. Para actualizarlo, ponte en contacto con tu account manager 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 planeas recuperar. Los métodos compatibles incluyen:

Autenticación básica
Token Bearer
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integrations & API > API keys en el Dashboard de Aircall.
Genera una nueva Clave API.
Guarda tanto el ID de la Clave API como el token.
En la configuración del widget Enviar a (mediante API), ve a Credentials y establece:
- Username = ID de la Clave API
- Password = token de 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 comprender 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 (JavaScript Object Notation) para intercambiar datos con APIs. 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, el equipo de Servicios profesionales de Aircall puede ofrecer consultoría y asistencia para la implementación.

Consideraciones de uso

El widget Enviar a (mediante API) permite un enrutamiento de llamadas dinámico (“inteligente”) basado en datos externos. Puede consultar cualquier sistema que admita APIs REST y métodos de autenticación estándar.

Nota: Las solicitudes realizadas por Enviar 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, o es posible que el widget no pueda recuperar el destino de enrutamiento.

La respuesta de la API debe devolver datos en un formato que Aircall pueda interpretar para el enrutamiento. Los tipos de respuesta compatibles incluyen:

Tipo de respuesta	Descripción
Usuario	Dirige a un agente específico utilizando su ID de Usuario o correo electrónico de Aircall.
Equipo	Dirige a un equipo específico de Aircall utilizando su ID de equipo.
Número de Aircall	Dirige internamente a otro número de Aircall utilizando su ID de número.
Número externo	Dirige 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 tanto el tipo de destino como el ID del destino de forma dinámica.

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

Ruta al tipo de destino (user, team, number o external)
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, and external.

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

Cualquier lógica avanzada (p. ej., enrutamiento condicional, 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 dirigir 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 Smartflows, añade un widget Enviar a (mediante API).
Elige el método HTTP (GET o POST), según la sección de la API que quieras usar.
- Ejemplo: al usar el endpoint Search Calls 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.
Usa variables como callerNumber, targetNumber o callUUID para insertar dinámicamente datos específicos de la llamada en tu solicitud. 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 enrutamiento.

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 del array “calls” y recupera el ID del 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, las reglas de timbrado se aplicarán en consecuencia.

Probar la configuración

Utiliza el campo Test response 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 tu URL o cuerpo de solicitud. Cuando ejecutes la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

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

Configuración de timbrado

Después de configurar y probar tu integración de API, ajusta la configuración de timbrado para definir cómo se distribuyen las llamadas. Esta configuración funciona de la misma manera que la del widget estándar Enviar a.

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

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

Este widget ofrece capacidades potentes y flexibles de enrutamiento dinámico al conectar Aircall con sistemas de terceros, como CRM o centros de ayuda.

Importante: El widget Enviar a (mediante API) está disponible solo en el plan Professional. Para actualizarlo, ponte en contacto con tu account manager 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 planeas recuperar. Los métodos compatibles incluyen:

Autenticación básica
Token Bearer
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integrations & API > API keys en el Dashboard de Aircall.
Genera una nueva Clave API.
Guarda tanto el ID de la Clave API como el token.
En la configuración del widget Enviar a (mediante API), ve a Credentials y establece:
- Username = ID de la Clave API
- Password = token de 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 comprender la estructura y los endpoints de la API pública de la plataforma externa.

Conocimiento de JSON

El widget utiliza JSON (JavaScript Object Notation) para intercambiar datos con APIs. 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, el equipo de Servicios profesionales de Aircall puede ofrecer consultoría y asistencia para la implementación.

Consideraciones de uso

Nota: Las solicitudes realizadas por Enviar 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, o es posible que el widget no pueda recuperar el destino de enrutamiento.

La respuesta de la API debe devolver datos en un formato que Aircall pueda interpretar para el enrutamiento. Los tipos de respuesta compatibles incluyen:

Tipo de respuesta	Descripción
Usuario	Dirige a un agente específico utilizando su ID de Usuario o correo electrónico de Aircall.
Equipo	Dirige a un equipo específico de Aircall utilizando su ID de equipo.
Número de Aircall	Dirige internamente a otro número de Aircall utilizando su ID de número.
Número externo	Dirige 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 tanto el tipo de destino como el ID del destino de forma dinámica.

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

Ruta al tipo de destino (user, team, number o external)
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, and external.

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

Cualquier lógica avanzada (p. ej., enrutamiento condicional, 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 dirigir 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 Smartflows, añade un widget Enviar a (mediante API).
Elige el método HTTP (GET o POST), según la sección de la API que quieras usar.
- Ejemplo: al usar el endpoint Search Calls 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.
Usa variables como callerNumber, targetNumber o callUUID para insertar dinámicamente datos específicos de la llamada en tu solicitud. 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 enrutamiento.

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 del array “calls” y recupera el ID del 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, las reglas de timbrado se aplicarán en consecuencia.

Probar la configuración

Utiliza el campo Test response 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 tu URL o cuerpo de solicitud. Cuando ejecutes la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

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

Configuración de timbrado

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

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