Centro de ayuda de Aircall | Widgets de Smartflows: Documentación técnica de Ring to (via API)

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

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

Importante: El widget Ring to (via API) está disponible solo en el plan Professional. Para actualizar, 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 de portador
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integrations & API > Claves API 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 Ring to (via API), ve a Credenciales y establece:
- Nombre de usuario = ID de la Clave API
- Contraseña = token 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 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 proporcionar consultoría y soporte de implementación. Ponte en contacto con nuestro equipo de gestión de cuentas.

Consideraciones de uso

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

Nota: Las solicitudes realizadas por Ring to (via 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 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 usando su ID de Usuario de Aircall o correo electrónico.
Equipo	Dirige a un equipo específico de Aircall usando su ID de Team.
Número de Aircall	Dirige internamente a otro número de Aircall usando 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 (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 acepta solo 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 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 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) según la llamada de API configurada.

Pasos:

En el editor de Smartflows, agrega un widget Ring to (via 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.
Utiliza 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 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 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 del destino: calls[0].target_id

Si el tipo de destino es team, las reglas de timbrado se aplicarán en consecuencia.

Prueba de 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 la 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 sobre la resolución de problemas.

Configuración del timbrado

Después de configurar y probar tu integración de API, ajusta la Configuración del timbrado para definir cómo se distribuyen las llamadas. Estos ajustes funcionan de la misma manera que los del widget estándar Ring to.

Para obtener más detalles, 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 tienes experiencia técnica, contacta con nuestro equipo de gestión de cuentas, que te pondrá en contacto con nuestro equipo técnico para recibir soporte y orientación sobre la implementación.

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

Importante: El widget Ring to (via API) está disponible solo en el plan Professional. Para actualizar, 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 de portador
Clave API
OAuth

Ejemplo (API de Aircall):

Ve a Integrations & API > Claves API 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 Ring to (via API), ve a Credenciales y establece:
- Nombre de usuario = ID de la Clave API
- Contraseña = token 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

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

Consideraciones de uso

Nota: Las solicitudes realizadas por Ring to (via 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 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 usando su ID de Usuario de Aircall o correo electrónico.
Equipo	Dirige a un equipo específico de Aircall usando su ID de Team.
Número de Aircall	Dirige internamente a otro número de Aircall usando 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 (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 acepta solo 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 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 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) según la llamada de API configurada.

Pasos:

En el editor de Smartflows, agrega un widget Ring to (via 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.
Utiliza 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 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 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 del destino: calls[0].target_id

Si el tipo de destino es team, las reglas de timbrado se aplicarán en consecuencia.

Prueba de 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 la 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 sobre la resolución de problemas.

Configuración del timbrado

Para obtener más detalles, 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 tienes experiencia técnica, contacta con nuestro equipo de gestión de cuentas, que te pondrá en contacto con nuestro equipo técnico para recibir soporte y orientación sobre la implementación.