Para usar la API de Chat en las cuentas de Support y Chat, y en las cuentas de la fase 4 de Chat, necesita generar un token de acceso para autenticar las solicitudes de API. No se admite la autenticación básica. No obstante, generar un token por primera vez puede ser un poco confuso, pero este tutorial proporciona ejemplos paso por paso de cómo generar manualmente un token. Al terminar, tendrá un token que puede usar en las solicitudes de la API de Chat para leer y escribir datos.

Si está diseñando una aplicación, debe crear la funcionalidad para generar tokens en su aplicación con el fin de automatizar el proceso.

Hay dos maneras de crear un token de acceso para la API de Chat; una manera más rápida y práctica de probar entornos (usando el flujo de concesión "implícita"), y una manera menos breve y más formal para los entornos de producción (usando el flujo de concesión de "código de autorización"). Ambas formas se incluyen en este tutorial.

Condiciones

Este tutorial se destina a las cuentas de Chat integrado a las que se aplicaron todos los cambios indicados en el artículo anterior. Estos se están introduciendo gradualmente, por lo que algunas cuentas pueden necesitarlos antes que otras. Si no está seguro de que su cuenta ya recibió todos los cambios, no dude en contactar con el equipo de soporte para confirmarlo.

Nota: una consecuencia de los cambios de cuentas es que será necesario volver a crear los tokens de OAuth. Si termina este tutorial antes de que los cambios se hayan hecho en su cuenta, necesitará volver a seguir los pasos después.

Procedimiento

El flujo de concesión "implícito" de OAuth tiene estos pasos:

  1. Crear el cliente API de OAuth.
  2. Finalizar el flujo de concesión implícito de OAuth para obtener el token usando la información del paso 1.

Crear el cliente API de OAuth

Primero, necesitamos un cliente API. Vaya a Zendesk Chat > Cuenta > API y SDK, y haga clic en el botón Agregar cliente API. Ingrese un nombre para el cliente y la compañía que desee y, para el URL de redireccionamiento, ingrese http://localhost:8080. Debe tener un aspecto similar a este:

Haga clic en Crear cliente API para finalizar la configuración. Verá una ventana emergente con el secreto y la ID del cliente. Muy importante: el secreto del cliente se muestra una sola vez, así que anótelo para cuando lo necesite más adelante. Se verá así:

Ahora que ya estableció el cliente API, anote el secreto y la ID del cliente antes de hacer clic en Entendido, y estará preparado para terminar el flujo de concesión de OAuth.

Finalizar el flujo de concesión implícito de OAuth para obtener el token

Este método usa el flujo de concesión "implícito" de OAuth. Otro método es usar el flujo de concesión de "código de autorización" de OAuth (que se muestra en la siguiente sección). Si se hace manualmente, este método tiene menos pasos y es más conveniente que el flujo de concesión de código de autorización que se muestra más adelante.

1. Siga el paso "Crear CLIENTE API de OAuth" anterior.

2. Obtenga esta información del cliente OAuth:

  • ID del cliente: CLIENT_ID
  • Su subdominio de Zendesk

3. Aplique su CLIENT_ID y SUBDOMAIN al siguiente URL, péguelo en una nueva pestaña del navegador y presione Intro.

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=token&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

NOTAS:

  • Si el cliente OAuth solo tiene un valor de URL de redireccionamiento, el paso de un valor redirect_uri es opcional. El sistema usará de manera predeterminada el único valor del URL de redireccionamiento del cliente OAuth.
  • Si el cliente OAuth tiene más de un valor de URL de redireccionamiento, el paso de un valor redirect_uri es obligatorio. Si se hace el paso de un valor redirect_uri, es necesario que sea un URL con codificación. En el ejemplo anterior, el parámetro de redirección opcional sería: redirect_uri=http%3A%2F%2Flocalhost%3A8080

4. Se hará la llamada, y posiblemente le pedirán que inicie sesión y seleccione "Permitir" para generar el token.

Si funciona la llamada, el campo de dirección de su navegador tendrá un nuevo token de OAuth (devuelto como el valor access_token).

A pesar del mensaje de error aparente que se muestra en la ventana principal del navegador, si el valor access_token se ve en el campo del URL del navegador, entonces si funcionó.

Esta es una demostración del flujo de trabajo:

 

Otra manera más larga de generar el token

Estos pasos crean un token de la misma manera que en la sección anterior, pero demuestran el flujo de concesión de "código de autorización" de OAuth. Anote los detalles de su cliente OAuth que se usarán a continuación.

Se usarán marcadores de posición en lugar de datos reales, pero recuerde que el secreto de su cliente OAuth se debe tratar con la máxima seguridad porque, básicamente, es la contraseña para entrar a su cuenta de Chat.

  • ID de cliente: CLIENT_ID
  • Secreto de cliente: CLIENT_SECRET
  • URI de redireccionamiento: http://localhost:8080
  • Subdominio: su subdominio de Zendesk; por ejemplo, si su cuenta está en niall.zendesk.com, este valor es niall
  • Código de autorización: todavía no lo tenemos

1. Preparar el primer URL

Aquí se crea un URL para solicitar un código de autorización. Tendrá que ir a https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new y agregar algunos parámetros de consulta para pasar parte de la información anterior. Por ahora, necesitamos:

  • response_type: esto siempre será code
  • redirect_uri: a donde será redirigido después de la concesión de acceso; http://localhost:8080 para este tutorial
  • client_id: es específico para usted, como se anotó antes
  • scope: el acceso que tendrá este token (seleccionaremos read y write)
    • Incluya también el alcance del chat si usa el token para la API de conversaciones de Chat.
  • subdomain: su subdominio de Zendesk

Con todos estos datos, la codificación de URL le dará el URL final que tiene un aspecto similar a este:

https://{subdomain}.zendesk.com/oauth2/chat/authorizations/new?response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080&client_id=CLIENT_ID&scope=read%20write&subdomain=SUBDOMAIN

en el que CLIENT_ID y SUBDOMAIN son los únicos valores diferentes en su URL.

2. Preparar la llamada con cURL

Antes de visitar ese URL, hay que generar la llamada con cURL que se ejecutará después. Esta vez, necesitaremos lo siguiente:

  • grant_type: esto siempre será authorization_code
  • code: se obtendrá después de permitir el acceso desde el URL
  • client_id: su ID de cliente
  • client_secret: su secreto de cliente
  • redirect_uri: igual que el del último paso, http://localhost:8080
  • scope: igual que en el último paso, read y write

Cuando se compila toda esta información, se obtiene un comando similar a este:

curl https://{subdomain}.zendesk.com/oauth2/chat/ \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

Recuerde: ahora ya debería tener CLIENT_ID y CLIENT_SECRET, pero aún no tenemos AUTH_CODE.

3. Obtener el código de autorización

Vaya ahora al URL que se generó en el paso 1. Verá una página como esta:

Haga clic en Permitir para conceder el acceso, y se le redirigirá al URL de redireccionamiento. Se verá como una página de error, pero lo importante es fijarse en el URL para ver cuál es el código de autorización, es decir, todo lo que está después de ?code=.

Copie ese código y prepárese para el último paso. El código de autorización solo es válido por poco tiempo. Si espera más de unos minutos, es posible que tenga que volver a ejecutar el paso anterior para obtener un valor nuevo de código.

4. Hacer la llamada con cURL para obtener el token

En la llamada con cURL que se generó en el paso 2 y que se ve como esta

curl https://{subdomain}.zendesk.com/oauth2/chat/token \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=http%3A%2F%2Flocalhost%3A8080&scope=read%20write' \
 -X POST

reemplace AUTH_CODE por el código del paso 3 y ejecute el comando desde una aplicación terminal. Recibirá una respuesta en forma de un objeto JSON, como este:

{
 "access_token": "TOKEN",
 "token_type": "Bearer",
 "refresh_token": "REFRESH_TOKEN",
 "scope": "read write"
}

5. Probar el token nuevo

Siempre es buena idea probar las cosas para confirmar que funcionen según lo previsto, y eso es lo que haremos. La llamada más fácil de hacer es un sencillo GET a /api/v2/chats para ver la información de su cuenta:

curl https://{subdomain}.zendesk.com/api/v2/chat/chats -H "Authorization: Bearer TOKEN"

y reemplazar TOKEN con el que se obtuvo en el paso 4. 

Información adicional

Valor client_type confidencial

En las secciones anteriores, se demostró el tipo de concesión "implícito" y el tipo de concesión de "código de autorización". La API de Chat también admite el tipo de concesión confidencial usando las credenciales del cliente. Esto se describe con más detalle en la documentación de referencia en la sección Tipos de concesión confidenciales.

Para las llamadas de API que usan los administradores y los agentes para asuntos como los informes de métricas, puede ser preferible obtener un token de OAuth con el tipo de concesión confidencial. Será necesario establecer el client_type como "confidencial". De manera predeterminada, este valor se establece como "público". El cambio se hace por medio de la API, y se logra de la siguiente manera:

1. Obtener la ID del cliente

Primero, necesita la ID de su cliente nuevo. Esta se obtiene usando el token nuevo, con la llamada siguiente:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients -H "Authorization: Bearer TOKEN"

que le mostrará todos sus clientes. Puede ser que solo tenga uno, pero, si tiene muchos, debe escoger el que desea actualizar y anotar su ID.

2. Actualizar el valor client_type

Ahora que ya tiene la ID del cliente, puede ejecutar la siguiente llamada con cURL para actualizar la propiedad client_type:

curl https://{subdomain}.zendesk.com/api/v2/chat/oauth/clients/{client_ID} -d '{"client_type": "confidential"}' \
 -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer TOKEN"

Una vez que termine, puede usar el token para los extremos restringidos.

Tecnología de Zendesk