Cómo acceder a los análisis de sesión en Zoho Desk

Los análisis de sesión en Zoho Desk se pueden recuperar de forma programática mediante un endpoint GET dedicado que devuelve datos de interacción y participación para tus sesiones de soporte. Esto es lo que necesitas saber para llamarlo correctamente.

Por qué es importante

Si estás creando dashboards, auditando el rendimiento de los agentes o integrando datos de Zoho Desk en herramientas de informes externas, obtener los análisis de sesión a través de la API es el enfoque más fiable. Esto resulta especialmente útil cuando necesitas automatizar exportaciones periódicas de datos o mostrar métricas dentro de un portal personalizado. Como soporte experto independiente de Zoho (no soporte oficial de Zoho), Beam Help te guía por los pasos exactos a continuación.

Paso a paso

Paso 1. Asegúrate de que tu token OAuth incluya los scopes correctos de Zoho Desk antes de realizar cualquier llamada a la API. Como mínimo, necesitarás scopes como Desk.basic.READ y Desk.settings.READ autorizados para tu integración. Revisa tu configuración OAuth para confirmar que están presentes junto con cualquier scope de tickets o contactos que tu aplicación ya utilice. ^[8]

Paso 2. Construye una solicitud GET dirigida al endpoint de análisis de sesión. La ruta que necesitas es:

GET /api/v1/_doc/__session_analytics

Este endpoint está dedicado a recuperar datos de análisis de sesión de Zoho Desk. ^[1]

Paso 3. Pasa los parámetros de consulta utilizando el diccionario p (o la cadena de consulta equivalente en tu cliente HTTP). El endpoint acepta un objeto de parámetro p, que te permite filtrar o paginar los resultados de análisis devueltos. [^1, ^2]

Paso 4. En Python, la llamada sigue este patrón:

result = client.get_session_analytics(p={"your_filter_key": "value"})

También existe una segunda operación registrada (getsessionanalytics2) que apunta a la misma ruta — ambas operaciones emiten un GET a /api/v1/doc/_sessionanalytics y aceptan la misma estructura de parámetro p. ^[2]

Paso 5. Gestiona el objeto de respuesta devuelto por la solicitud. La respuesta de la API contendrá tu carga útil de análisis de sesión. Si tu integración también construye enlaces de navegación para el portal de Zoho Desk, los datos de respuesta pueden enriquecerse con URLs directas del portal pasando el resultado a través de tu lógica de construcción de enlaces junto con los identificadores deskorgid y desk_portal. [^3, ^4]

Paso 6. Si estás trabajando en un contexto de chat o asistente, el resultado de los análisis de sesión puede almacenarse junto con un sessionid para su recuperación posterior. El campo toolresult en el sobre de respuesta es donde aparecen los datos de análisis sin procesar cuando se llama como parte de un flujo de orquestación más amplio. [^4, ^6]

Errores comunes

• Scopes OAuth faltantes. La lista de scopes OAuth de Zoho Desk es extensa. Si tu token se generó sin Desk.basic.READ o Desk.settings.READ, el endpoint de análisis puede devolver un error de autorización. Verifica tu configuración de ZOHODESKSCOPES y regenera el token si es necesario. ^[8]

• Nombres de operaciones duplicados. Dos operaciones (getsessionanalytics y getsessionanalytics2) están registradas contra la misma ruta de endpoint. Si estás generando automáticamente un cliente a partir de una especificación, ten en cuenta que ambas se resuelven en GET /api/v1/doc/_sessionanalytics — llamar a cualquiera de las dos producirá el mismo resultado, pero las colisiones de nombres en el código generado pueden causar confusión. [^1, ^2]

• Parámetro p vacío. El parámetro p tiene como valor predeterminado None, lo cual es válido — el endpoint devolverá resultados sin filtrar. Sin embargo, si esperas datos paginados o acotados por fecha, omitir los filtros puede devolver una carga útil mayor de la esperada. Pasa claves de filtro explícitas dentro de p para acotar tus resultados. ^[1]

• Sesión de navegador vs. sesión de API. Zoho Desk también mantiene un concepto de sesión basado en el navegador (rastreado mediante zoho_tld y una sesión de navegador guardada). Esto es independiente de los datos de sesión de la API de análisis — no los confundas al depurar. ^[7]

Qué verificar

• Cobertura de scopes: Verifica que tu token OAuth activo incluya como mínimo Desk.basic.READ y Desk.settings.READ, y que el token no haya expirado. ^[8]
• Estructura de la respuesta del endpoint: Confirma que el cuerpo de la respuesta contiene los campos de análisis que esperas; si tool_result es null o la carga útil está vacía, comprueba si los parámetros de filtro p están correctamente formados. ^[4]
• Identificadores de organización: Asegúrate de que los valores de deskorgid y desk_portal estén correctamente configurados en tu cliente, ya que son necesarios para que las respuestas vinculadas al portal se resuelvan correctamente. ^[3]