Centro de ayuda de Aircall | Configurar la Distribución inteligente para el propietario del contacto de Zendesk mediante el widget Llamar a (mediante API) en un flujo de llamadas

Configura la distribución inteligente en un número de teléfono compartido para garantizar que las personas que llaman se conecten de forma eficiente con su persona de contacto mediante el widget Ring-to (via API) en un flujo de llamadas, autenticado con OAuth de Zendesk.

Nota: Zendesk está retirando los tokens de API como método de autenticación. Este artículo utiliza OAuth, el método que los sustituye. Si actualmente utilizas un token de API para esta configuración, consulta más abajo Por qué este artículo utiliza OAuth en lugar de un token de API.

Nota: Es posible que el videotutorial muestre la versión anterior de la sección Probar respuesta. Sigue siempre los pasos escritos de este artículo para obtener las indicaciones más recientes.

En esta guía aprenderás:

Por qué este artículo utiliza OAuth en lugar de un token de API.
Cómo mejora la eficiencia y la experiencia del cliente el uso del widget Ring-to (via API).
Cómo configurar la distribución inteligente hacia el propietario del contacto de Zendesk.
- Paso uno: Crear el campo de usuario personalizado en Zendesk
- Paso dos: Crear un cliente OAuth confidencial en Zendesk
- Paso tres: Configurar el widget Ring-to (via API) en el editor de flujos
- Paso cuatro: Probar la configuración

Nota: El widget Ring-to (via API) solo está disponible con el Plan Professional. Si no tienes el Plan Professional, ponte en contacto con tu Gestor de satisfacción del cliente para obtener ayuda.

Por qué este artículo utiliza OAuth en lugar de un token de API

Zendesk está eliminando gradualmente los tokens de API como método de autenticación para las solicitudes a la API de soporte y los está sustituyendo por OAuth. Los tokens de API existentes seguirán funcionando durante un periodo de transición, pero Zendesk acabará desactivándolos por completo.

Importante: Si esta distribución ya funciona con un token de API, no esperes a que deje de funcionar. Crea la configuración de OAuth en un segundo widget Ring-to (via API), confirma que funciona y solo entonces cambia tu widget activo. Consulta «Puesta en marcha» más abajo para conocer los pasos del cambio.

El widget Ring-to (via API) se autentica en Zendesk mediante la concesión de credenciales de cliente OAuth. Aircall solicita un token de acceso a tu cuenta de Zendesk mediante tu ID y secreto de cliente y, a continuación, envía ese token a la API de Zendesk como encabezado Authorization: Bearer. Aircall almacena el token en caché y solicita uno nuevo automáticamente cuando caduca, por lo que no hay ningún token manual que cambiar.

Nota: Para consultar el calendario exacto de retirada de Zendesk, consulta su propio anuncio sobre la eliminación de los tokens de API.

Cómo mejora la eficiencia y la experiencia del cliente el uso del widget Ring-to (via API)

La distribución inteligente en un número de teléfono compartido ofrece importantes ventajas y mejora la eficiencia, la precisión y la experiencia del cliente. Al dirigir de forma inteligente las llamadas entrantes según los datos del CRM, la distribución inteligente garantiza que cada persona que llama se conecte rápidamente con el agente más adecuado, lo que reduce los tiempos de espera y mejora las tasas de resolución en la primera llamada.

Al utilizar el widget Ring-to (via API) de Aircall en un flujo de llamadas, un caso de uso habitual consiste en dirigir a las personas VIP que llaman directamente al propietario de su contacto de Zendesk (agente de soporte al cliente dedicado). Esto evita que todo el equipo se vea interrumpido por llamadas de clientes no relacionadas y elimina la necesidad de poner a las personas que llaman en espera mientras se las transfiere a su agente asignado.

Cómo configurar la distribución inteligente hacia el propietario del contacto de Zendesk

Paso uno: Crear el campo personalizado en Zendesk

Importante: Este paso requiere familiaridad con los campos personalizados y los métodos de autenticación de Zendesk.

Comienza en Zendesk creando una propiedad personalizada para almacenar la dirección de correo electrónico del propietario del contacto.

En el Centro de administración de Zendesk, ve a Contactos → Configuración → Campos de usuario y selecciona Añadir campo.
- Tipo de campo: Texto
- Nombre para mostrar: Correo electrónico del propietario
- Clave del campo: owner_email
El campo se añadirá automáticamente a todos los perfiles de usuarios finales. Una vez creado y visible en el perfil del usuario final, rellénalo con una dirección de correo electrónico. La necesitarás más adelante para probar la validez de la ruta en el widget Ring-to (via API).

Nota: La dirección de correo electrónico que introduzcas debe coincidir con la de un usuario de Aircall existente; de lo contrario, no se podrá dirigir la llamada a esa persona.

Paso dos: Crear un cliente OAuth confidencial en Zendesk

Importante: La concesión de credenciales de cliente solo está disponible para clientes OAuth confidenciales. No se puede usar un cliente público para esta configuración. Necesitas derechos de administrador de Zendesk para crear un cliente OAuth.

En el Centro de administración de Zendesk, ve a Aplicaciones e integraciones > API > Clientes OAuth y haz clic en Añadir cliente OAuth.
Completa los campos:
- Nombre: el nombre que prefieras, por ejemplo, "Aircall - Llamar a (mediante API)"
- Identificador: se rellena automáticamente a partir del nombre. Este valor es tu ID de cliente. Puedes cambiarlo si quieres.
- Tipo de cliente: Confidencial. Es obligatorio.
- URL de redireccionamiento: la concesión de credenciales de cliente no utiliza este valor. Si el formulario no se puede guardar sin una, introduce una URL HTTPS absoluta, como https://localhost.
- Ámbitos: opcional. Si dejas este campo vacío, el cliente podrá solicitar cualquier ámbito. Si lo configuras, actuará como límite: el widget no podrá solicitar un ámbito que no figure en esta lista. Si lo configuras, incluye el ámbito que introducirás en el widget en el paso tres.
- Hacer que los tokens caduquen: puedes dejar esta opción tal como está. Para los clientes OAuth creados a partir del 30 de abril de 2026, la casilla está desactivada porque los tokens emitidos por esos clientes ya caducan de forma predeterminada.
Haz clic en Guardar. La página se actualiza y aparece un campo Secreto.
Copia el Identificador y el Secreto y guárdalos en un lugar seguro.

Importante: El Secreto solo se muestra completo una vez. Después de salir de la página, solo podrás ver sus primeros nueve caracteres. Si lo pierdes, tendrás que crear un nuevo cliente OAuth.

Importante: Las acciones realizadas con un token de credenciales de cliente se atribuyen al usuario de Zendesk que creó el cliente OAuth, normalmente un administrador. Esto afecta a tus registros de auditoría. También significa que, si posteriormente se elimina a ese usuario, se reduce su nivel de acceso o pierde de otro modo los permisos necesarios para gestionar clientes OAuth, los tokens emitidos por este cliente dejarán de funcionar y esta distribución fallará. Si alguno de estos puntos es importante para ti, crea el cliente OAuth desde una cuenta de servicio específica antes de continuar.

Paso tres: Configura el widget Llamar a (mediante API) en el editor de flujos

Importante: Este paso requiere familiaridad con la API REST de Zendesk y los flujos de llamadas.

Ve a Panel de control de Aircall > Números y abre el flujo de llamadas del número que quieras configurar.

Es importante tener en cuenta que no es necesario asignar a la configuración del flujo de llamadas a los usuarios de Aircall a los que se dirigirán llamadas mediante la API. Si están asignados y no responden a la llamada transferida, recibirán las notificaciones de llamadas perdidas correspondientes en su lista de tareas pendientes. Sin embargo, no recibirán estas notificaciones si no están asignados al número.

Ve al número de teléfono en el que quieras configurar el widget Llamar a (mediante API). Añade el widget Llamar a (mediante API) en el lugar que quieras de la configuración del flujo de llamadas para abrir el editor del widget.

Establece Autenticación en OAuth y haz clic en Configurar credenciales. Completa el formulario de credenciales de la siguiente manera:

URL de inicio de sesión	`https://MyDomainName.zendesk.com/oauth/tokens` (sustituye `MyDomainName` por tu subdominio de Zendesk; utiliza tu subdominio principal de Zendesk, no un dominio asignado a un host)
ID de cliente	El Identificador de tu cliente OAuth
Secreto de cliente	El Secreto de tu cliente OAuth
Ámbito	`users:read read` para empezar. Zendesk no publica una correspondencia entre ámbitos y endpoints, por lo que debes considerar esto un punto de partida y confirmarlo con la prueba del paso cuatro. Si la prueba devuelve un error de ámbito, Zendesk indicará los ámbitos que necesita; introdúcelos exactamente.

Algunos consejos para configurar OAuth:
- Selecciona primero el valor de Autenticación y, a continuación, introduce las credenciales. Al cambiar la selección de Autenticación, se borran las credenciales que ya estén guardadas en el widget y tendrás que volver a introducirlas.
- Si no ves un campo Ámbito en el formulario de credenciales OAuth, actualiza el Panel de control de Aircall. El campo Ámbito es obligatorio para Zendesk y, sin él, Zendesk rechaza la solicitud del token.
- Ámbito es una lista separada por espacios. Intenta utilizar el conjunto más reducido que funcione. Se ha observado que Zendesk requiere un ámbito amplio, "read", junto con el ámbito específico del recurso, motivo por el que arriba se sugiere "users:read read".

Vuelve al editor de widgets y completa la configuración de la solicitud:
- URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
  (Sustituye “MyDomainName” por el nombre real de tu dominio de Zendesk).
- Método: GET
Configura los ajustes de respuesta de la siguiente manera:
- Tipo de respuesta: Usuario (ID o correo electrónico)
- Ruta: users[0].user_fields.owner_email

Paso cuatro: Prueba la configuración

Ejecuta una prueba en el campo específico Probar respuesta:

Introduce un número de teléfono válido en formato internacional E.164.
Asegúrate de que se devuelva una carga útil JSON.
Confirma que la Ruta sea válida para encontrar el valor utilizado para distribuir la llamada entrante.
Comprueba que la dirección de correo electrónico del contacto existente coincida con la de un usuario de Aircall existente.

Consejo: Ajusta la configuración de timbre situada justo debajo del campo de prueba para adaptarla a las operaciones de tu empresa.

Ahora deberías poder empezar a probar llamadas entrantes para su distribución inteligente al propietario del contacto de Zendesk mediante el widget Ring-to (via API).

Puesta en marcha

Cuando hayas completado las pruebas y la distribución funcione según lo previsto, asegúrate de rellenar el campo Correo electrónico del propietario en Zendesk para cada perfil de usuario final cuyas llamadas quieras distribuir automáticamente.

Si antes autenticabas este widget con un token de API, cambia ahora el widget en producción a las credenciales de OAuth y elimina el antiguo token de API del Centro de administración de Zendesk cuando hayas confirmado que la configuración de OAuth funciona.

Solución de problemas

Síntoma	Causa y solución
Se produce un error al solicitar el token de acceso o se recibe un error HTTP 401 durante la búsqueda	Las credenciales se han rechazado. Confirma que el cliente de OAuth sea Confidencial y que el ID de cliente coincida exactamente con el Identificador. Si el Secreto se volvió a copiar después de salir de la página del Centro de administración, estará truncado a nueve caracteres; crea un nuevo cliente y utiliza el Secreto completo.
Una prueba o llamada aislada falla, pero la misma prueba funciona inmediatamente después	Esto puede ocurrir justo cuando caduca un token de acceso almacenado en caché y se está renovando. Repite la prueba. Si ocurre de manera constante en lugar de ocasional, trátalo como un problema real de credenciales o permisos y revisa las filas siguientes.
`{"error":"Forbidden","description":"You are missing the following required scopes: ..."}`	El token se ha emitido, pero no incluye el permiso que necesita el endpoint. Edita las credenciales de OAuth del widget y establece Alcance en los permisos indicados en el mensaje de error.
HTTP 400 con `invalid_scope`	El permiso solicitado por el widget no figura en la lista de Alcances configurada en el cliente de OAuth de Zendesk. Añade el permiso a los alcances permitidos del cliente o cambia el Alcance del widget para que se ajuste a ellos.
Parece que las credenciales se han borrado	Al cambiar la selección de Autenticación, se borran las credenciales almacenadas. Vuelve a introducirlas después de seleccionar el método.
La prueba devuelve una carga útil, pero la llamada no se distribuye	El valor de la Ruta configurada debe coincidir con un usuario de Aircall existente. Confirma que el valor de Correo electrónico del propietario en el perfil de Zendesk coincida con la dirección de correo electrónico de un usuario de Aircall.
La distribución funcionaba antes, pero dejó de hacerlo sin ningún cambio de configuración	Confirma que el usuario de Zendesk que creó el cliente de OAuth siga existiendo y aún tenga permiso para gestionar clientes de OAuth. Los tokens de credenciales de cliente actúan en nombre de ese usuario y dejan de funcionar si pierde dicho acceso.

Servicios profesionales

Si necesitas ayuda adicional para implementar esta configuración de distribución inteligente o quieres conocer automatizaciones similares para mejorar tus operaciones, consulta nuestro equipo de Éxito del cliente para reservar una sesión con nuestros consultores técnicos.

Nota: Zendesk está retirando los tokens de API como método de autenticación. Este artículo utiliza OAuth, el método que los sustituye. Si actualmente utilizas un token de API para esta configuración, consulta más abajo Por qué este artículo utiliza OAuth en lugar de un token de API.

Nota: Es posible que el videotutorial muestre la versión anterior de la sección Probar respuesta. Sigue siempre los pasos escritos de este artículo para obtener las indicaciones más recientes.

En esta guía aprenderás:

Por qué este artículo utiliza OAuth en lugar de un token de API.
Cómo mejora la eficiencia y la experiencia del cliente el uso del widget Ring-to (via API).
Cómo configurar la distribución inteligente hacia el propietario del contacto de Zendesk.
- Paso uno: Crear el campo de usuario personalizado en Zendesk
- Paso dos: Crear un cliente OAuth confidencial en Zendesk
- Paso tres: Configurar el widget Ring-to (via API) en el editor de flujos
- Paso cuatro: Probar la configuración

Nota: El widget Ring-to (via API) solo está disponible con el Plan Professional. Si no tienes el Plan Professional, ponte en contacto con tu Gestor de satisfacción del cliente para obtener ayuda.

Por qué este artículo utiliza OAuth en lugar de un token de API

Importante: Si esta distribución ya funciona con un token de API, no esperes a que deje de funcionar. Crea la configuración de OAuth en un segundo widget Ring-to (via API), confirma que funciona y solo entonces cambia tu widget activo. Consulta «Puesta en marcha» más abajo para conocer los pasos del cambio.

Nota: Para consultar el calendario exacto de retirada de Zendesk, consulta su propio anuncio sobre la eliminación de los tokens de API.

Cómo mejora la eficiencia y la experiencia del cliente el uso del widget Ring-to (via API)

Cómo configurar la distribución inteligente hacia el propietario del contacto de Zendesk

Paso uno: Crear el campo personalizado en Zendesk

Importante: Este paso requiere familiaridad con los campos personalizados y los métodos de autenticación de Zendesk.

Comienza en Zendesk creando una propiedad personalizada para almacenar la dirección de correo electrónico del propietario del contacto.

En el Centro de administración de Zendesk, ve a Contactos → Configuración → Campos de usuario y selecciona Añadir campo.
- Tipo de campo: Texto
- Nombre para mostrar: Correo electrónico del propietario
- Clave del campo: owner_email
El campo se añadirá automáticamente a todos los perfiles de usuarios finales. Una vez creado y visible en el perfil del usuario final, rellénalo con una dirección de correo electrónico. La necesitarás más adelante para probar la validez de la ruta en el widget Ring-to (via API).

Nota: La dirección de correo electrónico que introduzcas debe coincidir con la de un usuario de Aircall existente; de lo contrario, no se podrá dirigir la llamada a esa persona.

Paso dos: Crear un cliente OAuth confidencial en Zendesk

Importante: La concesión de credenciales de cliente solo está disponible para clientes OAuth confidenciales. No se puede usar un cliente público para esta configuración. Necesitas derechos de administrador de Zendesk para crear un cliente OAuth.

En el Centro de administración de Zendesk, ve a Aplicaciones e integraciones > API > Clientes OAuth y haz clic en Añadir cliente OAuth.
Completa los campos:
- Nombre: el nombre que prefieras, por ejemplo, "Aircall - Llamar a (mediante API)"
- Identificador: se rellena automáticamente a partir del nombre. Este valor es tu ID de cliente. Puedes cambiarlo si quieres.
- Tipo de cliente: Confidencial. Es obligatorio.
- URL de redireccionamiento: la concesión de credenciales de cliente no utiliza este valor. Si el formulario no se puede guardar sin una, introduce una URL HTTPS absoluta, como https://localhost.
- Ámbitos: opcional. Si dejas este campo vacío, el cliente podrá solicitar cualquier ámbito. Si lo configuras, actuará como límite: el widget no podrá solicitar un ámbito que no figure en esta lista. Si lo configuras, incluye el ámbito que introducirás en el widget en el paso tres.
- Hacer que los tokens caduquen: puedes dejar esta opción tal como está. Para los clientes OAuth creados a partir del 30 de abril de 2026, la casilla está desactivada porque los tokens emitidos por esos clientes ya caducan de forma predeterminada.
Haz clic en Guardar. La página se actualiza y aparece un campo Secreto.
Copia el Identificador y el Secreto y guárdalos en un lugar seguro.

Importante: El Secreto solo se muestra completo una vez. Después de salir de la página, solo podrás ver sus primeros nueve caracteres. Si lo pierdes, tendrás que crear un nuevo cliente OAuth.

Importante: Las acciones realizadas con un token de credenciales de cliente se atribuyen al usuario de Zendesk que creó el cliente OAuth, normalmente un administrador. Esto afecta a tus registros de auditoría. También significa que, si posteriormente se elimina a ese usuario, se reduce su nivel de acceso o pierde de otro modo los permisos necesarios para gestionar clientes OAuth, los tokens emitidos por este cliente dejarán de funcionar y esta distribución fallará. Si alguno de estos puntos es importante para ti, crea el cliente OAuth desde una cuenta de servicio específica antes de continuar.

Paso tres: Configura el widget Llamar a (mediante API) en el editor de flujos

Importante: Este paso requiere familiaridad con la API REST de Zendesk y los flujos de llamadas.

Ve a Panel de control de Aircall > Números y abre el flujo de llamadas del número que quieras configurar.

Es importante tener en cuenta que no es necesario asignar a la configuración del flujo de llamadas a los usuarios de Aircall a los que se dirigirán llamadas mediante la API. Si están asignados y no responden a la llamada transferida, recibirán las notificaciones de llamadas perdidas correspondientes en su lista de tareas pendientes. Sin embargo, no recibirán estas notificaciones si no están asignados al número.

Ve al número de teléfono en el que quieras configurar el widget Llamar a (mediante API). Añade el widget Llamar a (mediante API) en el lugar que quieras de la configuración del flujo de llamadas para abrir el editor del widget.

Establece Autenticación en OAuth y haz clic en Configurar credenciales. Completa el formulario de credenciales de la siguiente manera:

URL de inicio de sesión	`https://MyDomainName.zendesk.com/oauth/tokens` (sustituye `MyDomainName` por tu subdominio de Zendesk; utiliza tu subdominio principal de Zendesk, no un dominio asignado a un host)
ID de cliente	El Identificador de tu cliente OAuth
Secreto de cliente	El Secreto de tu cliente OAuth
Ámbito	`users:read read` para empezar. Zendesk no publica una correspondencia entre ámbitos y endpoints, por lo que debes considerar esto un punto de partida y confirmarlo con la prueba del paso cuatro. Si la prueba devuelve un error de ámbito, Zendesk indicará los ámbitos que necesita; introdúcelos exactamente.

Algunos consejos para configurar OAuth:
- Selecciona primero el valor de Autenticación y, a continuación, introduce las credenciales. Al cambiar la selección de Autenticación, se borran las credenciales que ya estén guardadas en el widget y tendrás que volver a introducirlas.
- Si no ves un campo Ámbito en el formulario de credenciales OAuth, actualiza el Panel de control de Aircall. El campo Ámbito es obligatorio para Zendesk y, sin él, Zendesk rechaza la solicitud del token.
- Ámbito es una lista separada por espacios. Intenta utilizar el conjunto más reducido que funcione. Se ha observado que Zendesk requiere un ámbito amplio, "read", junto con el ámbito específico del recurso, motivo por el que arriba se sugiere "users:read read".

Vuelve al editor de widgets y completa la configuración de la solicitud:
- URL: https://MyDomainName.zendesk.com/api/v2/users/search.json?query={{callerNumber}}
  (Sustituye “MyDomainName” por el nombre real de tu dominio de Zendesk).
- Método: GET
Configura los ajustes de respuesta de la siguiente manera:
- Tipo de respuesta: Usuario (ID o correo electrónico)
- Ruta: users[0].user_fields.owner_email

Paso cuatro: Prueba la configuración

Ejecuta una prueba en el campo específico Probar respuesta:

Introduce un número de teléfono válido en formato internacional E.164.
Asegúrate de que se devuelva una carga útil JSON.
Confirma que la Ruta sea válida para encontrar el valor utilizado para distribuir la llamada entrante.
Comprueba que la dirección de correo electrónico del contacto existente coincida con la de un usuario de Aircall existente.

Consejo: Ajusta la configuración de timbre situada justo debajo del campo de prueba para adaptarla a las operaciones de tu empresa.

Ahora deberías poder empezar a probar llamadas entrantes para su distribución inteligente al propietario del contacto de Zendesk mediante el widget Ring-to (via API).

Puesta en marcha

Solución de problemas

Síntoma	Causa y solución
Se produce un error al solicitar el token de acceso o se recibe un error HTTP 401 durante la búsqueda	Las credenciales se han rechazado. Confirma que el cliente de OAuth sea Confidencial y que el ID de cliente coincida exactamente con el Identificador. Si el Secreto se volvió a copiar después de salir de la página del Centro de administración, estará truncado a nueve caracteres; crea un nuevo cliente y utiliza el Secreto completo.
Una prueba o llamada aislada falla, pero la misma prueba funciona inmediatamente después	Esto puede ocurrir justo cuando caduca un token de acceso almacenado en caché y se está renovando. Repite la prueba. Si ocurre de manera constante en lugar de ocasional, trátalo como un problema real de credenciales o permisos y revisa las filas siguientes.
`{"error":"Forbidden","description":"You are missing the following required scopes: ..."}`	El token se ha emitido, pero no incluye el permiso que necesita el endpoint. Edita las credenciales de OAuth del widget y establece Alcance en los permisos indicados en el mensaje de error.
HTTP 400 con `invalid_scope`	El permiso solicitado por el widget no figura en la lista de Alcances configurada en el cliente de OAuth de Zendesk. Añade el permiso a los alcances permitidos del cliente o cambia el Alcance del widget para que se ajuste a ellos.
Parece que las credenciales se han borrado	Al cambiar la selección de Autenticación, se borran las credenciales almacenadas. Vuelve a introducirlas después de seleccionar el método.
La prueba devuelve una carga útil, pero la llamada no se distribuye	El valor de la Ruta configurada debe coincidir con un usuario de Aircall existente. Confirma que el valor de Correo electrónico del propietario en el perfil de Zendesk coincida con la dirección de correo electrónico de un usuario de Aircall.
La distribución funcionaba antes, pero dejó de hacerlo sin ningún cambio de configuración	Confirma que el usuario de Zendesk que creó el cliente de OAuth siga existiendo y aún tenga permiso para gestionar clientes de OAuth. Los tokens de credenciales de cliente actúan en nombre de ese usuario y dejan de funcionar si pierde dicho acceso.