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

El widget Smart Routing: Ring to (vía API) utiliza una respuesta de API para determinar a qué usuario de Aircall, equipo, número interno o número externo se debe enrutar una llamada, basándose en datos almacenados fuera de Aircall.

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

Importante: E:
El widget Ring to (vía API) está disponible solo en el plan Professional. Para actualizar, por favor contacte con su gestor de cuenta de Aircall.

Requisitos previos

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

Credenciales de autenticación

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

Autenticación básica
Bearer Token
Clave API
OAuth

Ejemplo (API de Aircall):

Navegue a Integraciones & API > Claves API en el panel de Aircall.
Genere una nueva clave API.
Guarde tanto el ID de clave API como el token.
En la configuración del widget Ring to (vía API), vaya a Credenciales y configure:
- Nombre de usuario = ID de clave API
- Contraseña = token API

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

Conocimiento de la API de la plataforma

Debe comprender la estructura y los endpoints de la API pública de la plataforma externa.

Aunque Dónde encontrar mi clave API de Aircall usa la API de Aircall como ejemplo, también puede 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. Debe estar familiarizado con las estructuras básicas de JSON para configurar correctamente las rutas de datos.

CONSEJO:
Si necesita ayuda para configurar el widget, el equipo de Servicios Profesionales de Aircall puede ofrecer consultoría y soporte de implementación.

Consideraciones para su uso

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

NOTA:
Las solicitudes realizadas por Ring to (vía API) se agotarán después de 10 segundos. Asegúrese de que su endpoint responda dentro de este límite de tiempo o el widget podría no ser capaz de obtener el destino del enrutamiento.

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

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

Al usar Destino dinámico (ID), debe 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 respuestas de Destino dinámico, el widget acepta solo los siguientes valores para el tipo de destino: agent, team, internal y external.

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

Cualquier lógica avanzada (por ejemplo, enrutamiento condicional, priorización) debe procesarse en su 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) según la llamada API configurada.

Pasos:

En el editor Smartflows, agregue un widget Ring to (vía API).
Elija el método HTTP (GET o POST), dependiendo de la sección de la API que quiera usar.
- Ejemplo: Al usar el endpoint Search Calls de la API de Aircall, seleccione GET.
Introduzca 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 con el número de teléfono del llamante.
Use variables como callerNumber, targetNumber o callUUID para insertar dinámicamente datos específicos de la llamada en su solicitud. Consulte la documentación de la API de Aircall para obtener una lista completa de parámetros de consulta.

Configuración de la respuesta

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

Tipos de respuesta soportados:

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 referencia el primer elemento en el array “calls” y obtiene 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 equipo, se aplicarán las reglas de timbrado correspondientes.

Prueba de la configuración

Utilice el campo de prueba de respuesta para simular solicitudes 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 en el JSON corresponde a una variable usada en su URL o cuerpo de la solicitud. Cuando ejecute la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

Si ocurre un error, consulte la sección Errores en la documentación de la API de Aircall para obtener orientación sobre resolución de problemas.

Configuración de timbrado

Después de configurar y probar su integración API, ajuste la Configuración de timbrado para definir cómo se distribuyen las llamadas. Estas configuraciones funcionan igual que en el widget estándar Ring to.

Para más detalles, consulte nuestro artículo del Centro de Ayuda Resumen del enrutamiento en Smartflows.

CONSEJO:
Si necesita ayuda para configurar o probar su integración API, el equipo de Servicios Profesionales de Aircall puede asistirle con implementación práctica y resolución de problemas.

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

Importante: E:
El widget Ring to (vía API) está disponible solo en el plan Professional. Para actualizar, por favor contacte con su gestor de cuenta de Aircall.

Requisitos previos

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

Credenciales de autenticación

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

Autenticación básica
Bearer Token
Clave API
OAuth

Ejemplo (API de Aircall):

Navegue a Integraciones & API > Claves API en el panel de Aircall.
Genere una nueva clave API.
Guarde tanto el ID de clave API como el token.
En la configuración del widget Ring to (vía API), vaya a Credenciales y configure:
- Nombre de usuario = ID de clave API
- Contraseña = token API

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

Conocimiento de la API de la plataforma

Debe 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. Debe estar familiarizado con las estructuras básicas de JSON para configurar correctamente las rutas de datos.

CONSEJO:
Si necesita ayuda para configurar el widget, el equipo de Servicios Profesionales de Aircall puede ofrecer consultoría y soporte de implementación.

Consideraciones para su uso

NOTA:
Las solicitudes realizadas por Ring to (vía API) se agotarán después de 10 segundos. Asegúrese de que su endpoint responda dentro de este límite de tiempo o el widget podría no ser capaz de obtener el destino del enrutamiento.

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

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

Al usar Destino dinámico (ID), debe 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 respuestas de Destino dinámico, el widget acepta solo los siguientes valores para el tipo de destino: agent, team, internal y external.

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

Cualquier lógica avanzada (por ejemplo, enrutamiento condicional, priorización) debe procesarse en su 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) según la llamada API configurada.

Pasos:

En el editor Smartflows, agregue un widget Ring to (vía API).
Elija el método HTTP (GET o POST), dependiendo de la sección de la API que quiera usar.
- Ejemplo: Al usar el endpoint Search Calls de la API de Aircall, seleccione GET.
Introduzca 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 con el número de teléfono del llamante.
Use variables como callerNumber, targetNumber o callUUID para insertar dinámicamente datos específicos de la llamada en su solicitud. Consulte la documentación de la API de Aircall para obtener una lista completa de parámetros de consulta.

Configuración de la respuesta

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

Tipos de respuesta soportados:

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 referencia el primer elemento en el array “calls” y obtiene 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 equipo, se aplicarán las reglas de timbrado correspondientes.

Prueba de la configuración

Utilice el campo de prueba de respuesta para simular solicitudes 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 en el JSON corresponde a una variable usada en su URL o cuerpo de la solicitud. Cuando ejecute la prueba, el widget sustituirá estas variables y mostrará los resultados analizados.

Si ocurre un error, consulte la sección Errores en la documentación de la API de Aircall para obtener orientación sobre resolución de problemas.

Configuración de timbrado

Para más detalles, consulte nuestro artículo del Centro de Ayuda Resumen del enrutamiento en Smartflows.

CONSEJO:
Si necesita ayuda para configurar o probar su integración API, el equipo de Servicios Profesionales de Aircall puede asistirle con implementación práctica y resolución de problemas.