Cómo usar la API de Chat en Zendesk: Una guía paso a paso

Así que quieres crear una integración personalizada, extraer datos de chat para un informe o automatizar algunos flujos de trabajo en Zendesk. Es un gran objetivo. Usar la API te da el poder de adaptar realmente la plataforma a tu voluntad.

Pero seamos sinceros un momento. Averiguar por dónde empezar con las API de Zendesk puede parecer una pesadilla. Tienes el clásico Live Chat, la plataforma más nueva de Messaging y toda una variedad de API diferentes para elegir: REST, Real-Time, Conversations… Es suficiente para que te den ganas de cerrar la pestaña del navegador antes de haber escrito una sola línea de código.

Si esto te suena familiar, estás en el lugar correcto. Esta guía está aquí para acabar con la confusión. Te guiaremos a través de un proceso sencillo y paso a paso para usar la API de Chat clásica que Zendesk proporciona. Aclararemos las dudas y te guiaremos para que pases de rascarte la cabeza a realizar tu primera llamada a la API con éxito.

Lo que necesitarás para empezar con la API de Chat de Zendesk

Antes de arremangarnos y meternos de lleno en el código, hagamos una comprobación rápida para asegurarnos de que tienes todo lo que necesitas. Dejar esto listo ahora te ahorrará un montón de problemas más adelante.

Aquí tienes una lista de verificación rápida:

• Una cuenta de Zendesk con acceso a la API. Esto suele estar disponible en los planes Zendesk Suite Team en adelante. Si no estás seguro de qué plan tienes, vale la pena echar un vistazo a los detalles de tu suscripción para confirmarlo.

• Permisos de administrador. Necesitarás ser administrador en tu cuenta de Zendesk para generar las claves de la API. Si no eres administrador, tendrás que encontrar a la persona que lo es y pedirle amablemente que te ayude.

• Un cliente de API. Necesitarás una forma de enviar peticiones a la API. Una herramienta como Postman es fantástica para esto porque te permite probar llamadas a la API con una interfaz fácil de usar en lugar de escribir código de inmediato. Alternativamente, puedes usar cURL directamente en el terminal de tu ordenador o saltar directamente a tu lenguaje de programación favorito.

• Conocimientos básicos de las API REST. No necesitas ser un experto, pero tener una familiaridad básica con conceptos como endpoints, peticiones GET y cabeceras de autorización hará que este proceso sea mucho más fluido.

Guía paso a paso para usar la API de Chat de Zendesk

Muy bien, ahora que tienes todas tus herramientas listas, vamos al grano. Empezaremos por entender el panorama de Zendesk y luego nos ensuciaremos las manos con una llamada real a la API.

Paso 1: Entender el panorama de la API de Chat de Zendesk (Chat vs. Messaging)

Sinceramente, el mayor punto de confusión para cualquiera que empiece con las API de Zendesk es la diferencia entre sus dos productos de chat: Live Chat y Messaging. Suenan parecidos, pero bajo el capó, son dos bestias completamente diferentes que utilizan conjuntos de API totalmente distintos. Tener esto claro desde el principio es fundamental.

Zendesk Live Chat (El clásico)

Este es el producto de chat original, basado en sesiones, con el que muchos de nosotros estamos familiarizados (antes se llamaba Zopim). Piénsalo como una llamada telefónica: un cliente inicia un chat, es una conversación en vivo y en tiempo real que termina cuando cierran la ventana. Este producto utiliza un conjunto específico de API, incluida la API REST de Chat, en la que nos centraremos en esta guía. Estas API están diseñadas para gestionar esas conversaciones en tiempo real, manejar agentes y extraer registros de chats históricos de este sistema clásico.

Zendesk Messaging

Este es el enfoque omnicanal más nuevo de Zendesk. Está diseñado para conversaciones asíncronas, que se parecen más a los mensajes de texto o WhatsApp. Un cliente puede enviar un mensaje desde tu sitio web, aplicación móvil o incluso Facebook Messenger, y luego volver más tarde para ver la respuesta. Aquí está la parte clave: Messaging no utiliza las API de Chat clásicas en absoluto. En su lugar, se basa en un conjunto de herramientas para desarrolladores diferente, que incluye cosas como Sunshine Conversations y webhooks para datos en tiempo real.

Esta división es un verdadero dolor de cabeza para los equipos que intentan crear automatizaciones unificadas. Lidiar con dos modelos de API completamente diferentes es complicado y puede consumir mucho tiempo y recursos. Es una razón común por la que muchos de estos proyectos se quedan atascados en el desarrollo. Es también exactamente la razón por la que existen plataformas como eesel AI. Proporciona una única integración con Zendesk en un solo clic que se conecta a todos los datos de tu servicio de asistencia, ya provengan del Chat clásico o del Messaging moderno. Esto te permite crear agentes de IA inteligentes sin tener que preocuparte por qué API se supone que debes usar.

Paso 2: Elegir la API adecuada para tu objetivo

Incluso dentro del mundo del Live Chat tradicional, Zendesk te ofrece varias API diferentes, cada una diseñada para una tarea específica. Elegir la correcta desde el principio te evitará dar vueltas en círculos.

Aquí tienes un resumen rápido de tus opciones:

• API REST de Chat: Este es el caballo de batalla que usarás para la mayoría de las cosas. La usarías para obtener programáticamente datos históricos de chats, recuperar transcripciones, gestionar tus agentes y actualizar la información del chat después de que una conversación haya terminado. Usaremos esta API en nuestro ejemplo más abajo.

• API de Chat en tiempo real: Se trata de una API de streaming creada para monitorear lo que está sucediendo ahora mismo. Si necesitas crear un panel que muestre cuántos chats están activos o qué agentes están en línea en este mismo segundo, esta es la API que quieres.

• API de Conversaciones (GraphQL): Esta API fue diseñada originalmente para crear aplicaciones que pudieran actuar como agentes, como chatbots personalizados. Sin embargo, Zendesk ha puesto esta API en modo de mantenimiento y ya no está disponible para nuevas integraciones. Para cualquier proyecto nuevo, deberías mantenerte alejado de esta.

• SDK web: No es una API típica, sino una biblioteca de JavaScript que se ejecuta en el lado del cliente. Te da el poder de crear un widget de chat completamente personalizado para tu sitio web, dándote un control total sobre la apariencia, la sensación y la experiencia del usuario.

Para que quede aún más claro, aquí tienes una tabla sencilla para ayudarte a decidir:

Paso 3: Generar tus credenciales de la API

Para hablar con la API de forma segura, tu código necesita demostrar que tiene permiso. La forma estándar de hacerlo es creando un cliente OAuth en tu panel de control de Zendesk Chat, lo que te dará las credenciales que necesitas para generar un token de acceso.

Aquí te explicamos cómo hacerlo:

1. Dirígete a tu panel de control de Zendesk Chat. Normalmente puedes encontrarlo en la bandeja de productos (el icono de cuatro cuadrados) en tu cuenta principal de Zendesk Support.

2. En el menú de la izquierda, navega a Configuración > Cuenta y luego haz clic en la pestaña API y SDK.

3. Haz clic en el gran botón Añadir cliente de API.

4. Verás un formulario. Dale a tu cliente un Nombre de Cliente fácil de recordar (algo como "Integración de Datos de Chat" funciona bien) y completa el nombre de tu Empresa. Para las URL de redirección, por ahora puedes simplemente introducir "https://localhost". Este es un marcador de posición que es necesario para el flujo de autenticación, y está perfectamente bien para lo que estamos haciendo hoy.

5. Después de crear el cliente, Zendesk te mostrará un ID de cliente y un Secreto de cliente. Ve y copia el Secreto de cliente y guárdalo en un lugar seguro, como un gestor de contraseñas. Esta es la única oportunidad que tendrás de verlo.

6. Estas credenciales se utilizan en un proceso llamado flujo de autorización OAuth para obtener un token de portador (bearer token) temporal. Para mantener esta guía sencilla, vamos a avanzar rápidamente y suponer que ya has generado un token de acceso para usarlo directamente en tus peticiones.

Paso 4: Realizar tu primera llamada a la API

Y ahora, el momento de la verdad. Usemos las credenciales que acabas de generar para extraer algunos datos reales de tu cuenta. Nuestro objetivo es sencillo: recuperar una lista de tus chats más recientes.

El Endpoint

El endpoint de la API es simplemente la URL a la que envías tu petición. Para obtener una lista de todos los chats, el endpoint es "GET /api/v2/chats".

Autenticación

Cada petición que envíes debe estar autenticada para demostrar que eres tú. Esto se hace incluyendo tu token de acceso en una cabecera "Authorization". El formato es simple: "Authorization: Bearer TU_TOKEN_DE_ACCESO".

Juntándolo todo (Ejemplo con cURL)

Usar cURL desde tu terminal es una de las formas más rápidas de probar una API sin complicaciones. Abre tu terminal, reemplaza TU_TOKEN_DE_ACCESO con el token real que tienes y ejecuta este comando:

"`bash

curl https://www.zopim.com/api/v2/chats \

-H "Authorization: Bearer TU_TOKEN_DE_ACCESO"

"`

Si todo se configuró correctamente, el servidor de Zendesk debería responder con un montón de texto con formato JSON que contiene una lista de tus chats.

Respuesta de ejemplo

La respuesta será un array JSON de objetos de chat. Aquí tienes un fragmento simplificado de cómo podría ser:

"`json

{

"chats": [

{  

  "id": "1A2B3C4D5E",  

  "visitor": {  

    "name": "Jane Doe",  

    "email": "jane.doe@example.com"  

  },  

  "history": [  

    {  

      "type": "chat.msg",  

      "display_name": "Jane Doe",  

      "msg": "Hola, tengo una pregunta sobre mi pedido reciente.",  

      "timestamp": 1678886400000  

    },  

    {  

      "type": "chat.msg",  

      "display_name": "Agente de soporte",  

      "msg": "Hola Jane, ¡estaré encantado de ayudarte con eso!",  

      "timestamp": 1678886460000  

    }  

  ],  

  "timestamp": "2023-03-15T12:00:00Z"  

}  

],

"count": 1

}

"`

¡Y así de fácil, lo has conseguido! Has utilizado con éxito la API de Chat que Zendesk proporciona para obtener datos reales. Aquí puedes ver todo tipo de información útil, como el ID del chat, los detalles del visitante y el historial completo de la conversación con marcas de tiempo.

Errores comunes que evitar al trabajar con la API de Chat de Zendesk

Lograr que tu primera llamada a la API funcione es un gran primer paso, pero a medida que empieces a crear integraciones más avanzadas, hay algunas trampas comunes en las que es fácil caer. Aquí tienes algunos consejos para ayudarte a esquivarlas.

• 1. Usar la API incorrecta para la tarea: Lo hemos mencionado varias veces, pero vale la pena repetirlo porque es el error número uno que comete la gente. Antes de escribir una línea de código, verifica dos veces si tu objetivo involucra el Live Chat clásico o el Messaging moderno. Intentar obtener datos de Messaging con la API de Chat simplemente no funcionará y te dejará preguntándote por qué no aparece nada.

• 2. Ignorar los límites de peticiones: Para mantener su servicio estable para todos, la API de Chat de Zendesk tiene un límite de peticiones (rate limit), que suele ser de unas 200 peticiones por minuto. Si superas este límite, recibirás un error "429 Too Many Requests". Una buena práctica es comprobar siempre la cabecera "X-Rate-Limit-Remaining" en la respuesta de la API para ver cuántas llamadas te quedan, y construir una lógica simple en tu aplicación para pausar si te estás acercando al límite.

• 3. Crear un nuevo proyecto sobre una API obsoleta: Como señalamos anteriormente, la API de Conversaciones está en modo de mantenimiento. Puede parecer potente, pero empezar un nuevo proyecto en una API que Zendesk ya no desarrolla activamente es prepararse para tener problemas en el futuro. Cíñete a las API con soporte activo para cualquier trabajo nuevo.

Este tipo de desafíos resaltan los costes ocultos de crear y mantener integraciones personalizadas. No es solo el tiempo inicial que se necesita para escribir el código; es el trabajo continuo de manejar errores, adaptarse a los cambios de la API y gestionar todo el mantenimiento técnico. Aquí es donde podrías preguntarte si vale la pena construir desde cero. Por una pequeña fracción del esfuerzo de ingeniería, una herramienta como eesel AI ofrece un potente motor de simulación que te permite probar el rendimiento de tu IA en miles de tickets históricos antes de que interactúe con un cliente real. Puedes desplegar una automatización sofisticada con confianza y sin el riesgo de desarrollo.

Sáltate el código de la API de Chat de Zendesk y automatiza con IA

¡Enhorabuena! Has logrado navegar por el a veces confuso mundo de la API de Chat que ofrece Zendesk, desde la generación de tus credenciales hasta la extracción de datos reales. Esa es una base sólida para construir cualquier herramienta personalizada que tengas en mente.

Sin embargo, si tu objetivo final es automatizar resoluciones, hacer que tus agentes sean más eficientes y dar a los clientes respuestas instantáneas, construir todo por tu cuenta es un camino largo que requiere mucho tiempo de desarrollo. Hay una forma mucho más rápida de llegar allí.

eesel AI se conecta directamente a tu instancia de Zendesk en solo unos minutos, dándote un conjunto completo de herramientas de IA listas para usar. Desde un agente autónomo que puede resolver tickets por sí mismo hasta un Copiloto de IA que da superpoderes a tus agentes humanos, puedes estar en funcionamiento en minutos, no en meses. Obtienes todos los beneficios de una potente automatización sin los dolores de cabeza de la ingeniería.

Un Copiloto de IA redactando una respuesta en Zendesk, una alternativa a programar con la API de Chat de Zendesk.

Comienza tu prueba gratuita hoy mismo.