Cómo listar conversaciones en tickets de Zoho Desk

Listar todas las conversaciones de un ticket de Zoho Desk es sencillo una vez que conoces el endpoint correcto de la API y los scopes de OAuth necesarios. Este artículo te guía a través de la llamada exacta y lo que debes verificar después.

Por qué esto es importante

Los flujos de trabajo de soporte suelen requerir acceso programático al hilo completo de respuestas, notas y reenvíos asociados a un ticket — para informes, automatización o integración con otras herramientas. Saber cómo recuperar esa lista de conversaciones a través de la API de Zoho Desk te permite construir pipelines fiables sin necesidad de exportar datos manualmente desde la interfaz. Como soporte experto independiente (no soporte oficial de Zoho), Beam Help documenta este patrón para que tu equipo pueda implementarlo con confianza.

Paso a paso

Paso 1. Confirma que tu token de OAuth incluye los scopes correctos de Desk antes de realizar cualquier llamada a la API. Como mínimo necesitas Desk.tickets.READ en tu lista de scopes; las integraciones más amplias suelen incluir también Desk.tickets.ALL para cubrir las operaciones de lectura, escritura, creación, actualización y eliminación en un único permiso. ^[2]

Paso 2. Identifica el ticket_id del ticket cuyas conversaciones deseas recuperar. Este es el identificador numérico interno de Zoho Desk para el registro del ticket — no el número de ticket visible que se muestra a los clientes. Puedes obtenerlo a partir de una búsqueda previa de tickets o desde la URL de detalle del ticket en el portal de agentes de Desk. ^[7]

Paso 3. Envía una solicitud GET al endpoint de conversaciones, sustituyendo el ID de tu ticket en la ruta:

GET /api/v1/tickets/{ticket_id}/conversations

Incluye tu token bearer de OAuth en el encabezado Authorization como de costumbre. El parámetro opcional p puede pasarse como un diccionario de cadena de consulta para controlar la paginación o el filtrado de la lista de conversaciones devuelta. ^[8]

Paso 4. Analiza la respuesta. El endpoint devuelve la lista de entradas de conversación asociadas a ese ticket — las respuestas, comentarios públicos, notas privadas y mensajes reenviados se exponen todos a través de esta única llamada. Itera sobre el array devuelto para acceder a los cuerpos de los mensajes individuales, marcas de tiempo, detalles del autor e información del canal. ^[8]

Paso 5. Si estás construyendo una interfaz de usuario o un asistente sobre estos datos, mapea cada entrada de conversación de vuelta a la URL del portal de agentes del ticket para que los agentes puedan acceder directamente al registro. El patrón de enlace directo de Desk sigue el formato https://desk.zoho.{dc}/agent/{portal}/tickets/details/{ticket_id}, donde dc es el sufijo de tu centro de datos (p. ej., com, eu, in) y portal es el nombre de tu portal de Desk. ^[7]

Errores comunes

• Scopes ausentes o insuficientes. Si a tu cliente OAuth solo se le otorgó Desk.search.READ u otros scopes a nivel de contacto, el endpoint de conversaciones devolverá un error de autorización. Verifica que Desk.tickets.READ (o Desk.tickets.ALL) esté presente en la cadena de scopes del token. ^[2]

• Formato incorrecto del ID de ticket. Pasar el número de ticket visible para el cliente en lugar del ticket_id interno resultará en una respuesta 404 o vacía. Resuelve siempre el ID interno primero mediante una búsqueda o llamada de consulta de tickets antes de llamar al endpoint de conversaciones. ^[8]

• Discrepancia de centro de datos. Zoho Desk está alojado en múltiples centros de datos regionales. Asegúrate de que la URL base que utilizas (desk.zoho.com, desk.zoho.eu, etc.) coincida con la región donde está aprovisionada la cuenta de Desk de tu organización; las solicitudes enrutadas a la región incorrecta fallarán en la autenticación. ^[7]

• Paginación no gestionada. Para tickets con historiales de conversación extensos, la API devuelve los resultados en páginas. Usa el parámetro p para avanzar por las páginas y evitar truncar silenciosamente la lista de conversaciones. ^[8]

Qué verificar

• Cobertura de scopes: Verifica que tu token de OAuth activo contenga Desk.tickets.READ o Desk.tickets.ALL inspeccionando los scopes otorgados en tu consola de API de Zoho. ^[2]
• Ruta del endpoint correcta: Confirma que la URL de la solicitud resuelve a /api/v1/tickets/{ticketid}/conversations con un ticketid numérico y válido sustituido. ^[8]
• Paginación completa: Si la respuesta incluye un indicador nextPage o un recuento total superior al tamaño de página predeterminado, asegúrate de que tu integración recorra todas las páginas antes de procesar los resultados. ^[8]