Cómo ver las métricas de rendimiento de agentes en Zoho Desk

Las métricas de rendimiento de agentes en Zoho Desk son accesibles a través de endpoints de API dedicados que exponen datos de productividad, monitoreo de estado en tiempo real y asignaciones de habilidades para cada agente de tu organización de soporte.

Por qué esto es importante

Los responsables de soporte necesitan una visión clara y en tiempo real del rendimiento de su equipo — desde las tasas de resolución de tickets hasta la disponibilidad actual. Ya sea que estés construyendo un panel personalizado, realizando una revisión periódica o integrando datos de Zoho Desk en una herramienta de BI más amplia, saber qué endpoints llamar y qué permisos configurar es esencial. Esta guía (de Beam Help — soporte experto independiente para Zoho, no soporte oficial de Zoho) te lleva por todo el proceso.

---

Paso a paso

Paso 1. Confirma que tus scopes de OAuth están configurados.

Antes de que cualquier llamada de métricas tenga éxito, tu aplicación conectada debe estar autorizada con los scopes de OAuth correctos de Zoho Desk. Como mínimo necesitas Desk.basic.READ (cubre agentes, departamentos y organizaciones) junto con cualquier scope de tickets o configuración relevante para tu caso de uso. ^[5] Asegúrate de que estos scopes estén presentes en tu configuración de OAuth y de que el token se haya actualizado tras cualquier cambio de scope. ^[5]

Paso 2. Recupera las métricas de rendimiento de agentes.

Envía una solicitud GET al endpoint /api/v1/doc/agentperformancemetrics, pasando cualquier parámetro de filtro o paginación como un diccionario de parámetros de consulta. ^[1] Esta operación — identificada internamente como getagentperformancemetrics — devuelve datos orientados a la productividad de tus agentes. ^[1] Una llamada mínima en Python tiene este aspecto:

result = client.get_agent_performance_metrics(p={"department": "Support"})

Reemplaza el diccionario de parámetros con los filtros que requiera tu ventana de informes. ^[1]

Paso 3. Obtén los datos de estado en tiempo real de los agentes.

Para información de disponibilidad y carga de trabajo en tiempo real, llama a GET /api/v1/doc/agentstatusmonitoring usando la operación getagentstatusmonitoring. ^[2] Este endpoint está diseñado específicamente para la observación continua del estado — útil para paneles de control o vistas de supervisores en vivo. ^[2] Pasa el mismo diccionario de parámetros opcional p para acotar los resultados por departamento o equipo si es necesario. ^[2]

Paso 4. Recupera las asignaciones de habilidades de los agentes (opcional pero recomendado).

Si tu configuración de Desk utiliza enrutamiento basado en habilidades, también querrás consultar GET /api/v1/doc/agentskillmapping a través de la operación getagentskillmapping. ^[4] Esto te permite cruzar los datos de rendimiento con el conjunto de habilidades asignado a cada agente, dando contexto a los tiempos de resolución y los volúmenes de tickets. ^[4]

Paso 5. Formatea y presenta los datos devueltos.

Una vez que recibas los resultados, muestra los campos de datos clave en un formato legible para los interesados. Un patrón recomendado es mostrar cada campo en su propia línea (Nombre, Estado, Propietario/Agente, etc.), omitiendo los valores vacíos y los IDs internos. ^[3] Evita volcar JSON sin procesar directamente en los informes — analiza y etiqueta cada campo de forma explícita. ^[3]

Paso 6. Automatiza con un trabajo programado (opcional).

Para revisiones de rendimiento recurrentes, envuelve las llamadas de los Pasos 2–4 en un script programado. Almacena las respuestas en tu almacén de datos o capa de BI, indexadas por marca de tiempo e ID de agente, para poder rastrear tendencias a lo largo del tiempo. Dado que los endpoints aceptan un diccionario de parámetros, puedes variar el rango de fechas o el filtro de departamento en cada ejecución sin cambiar la lógica principal. ^[1][2]

---

Errores comunes

• Scope Desk.basic.READ ausente. Esta es la causa más frecuente de errores 401/403 al consultar endpoints de agentes. Aunque tu token tenga amplios permisos de tickets, los datos de agentes y departamentos se encuentran bajo la familia de scopes basic. Verifica tu lista de scopes antes de depurar el endpoint en sí. ^[5]
• Tokens de acceso caducados. Los tokens OAuth de Zoho expiran (normalmente después de 3600 segundos). Si tu integración no actualiza el token automáticamente, las llamadas a los tres endpoints fallarán silenciosamente o devolverán errores de autenticación. Implementa un flujo de actualización que compruebe tokenexpiresat antes de cada solicitud. ^[8]
• Diccionario de parámetros vacío vs. None. Los tres endpoints aceptan p como un diccionario opcional. Pasar None es válido y devuelve resultados sin filtrar, pero si pretendes filtrar por departamento o rango de fechas, asegúrate de que el diccionario esté correctamente formado — un diccionario mal formado será ignorado en lugar de generar un error evidente. ^[1][2][4]
• Los cambios de scope requieren la reemisión del token. Añadir Desk.basic.READ a tu configuración después de la autorización inicial no actualiza automáticamente los tokens existentes. Los usuarios o cuentas de servicio deben volver a autenticarse para recibir un token que incluya el nuevo scope. ^[5]

---

Qué verificar

• Los scopes están activos en el token actual — verifica que Desk.basic.READ (y cualquier otro scope requerido) aparezca en la lista de scopes concedidos del token antes de realizar tu primera llamada de métricas. ^[5]
• Los tres endpoints devuelven datos — confirma que getagentperformancemetrics, getagentstatusmonitoring y getagentskill_mapping respondan cada uno con un payload no vacío, ya que una respuesta ausente de cualquiera de ellos suele indicar un problema de permisos o parámetros. ^[1][2][4]
• La lógica de actualización del token funciona correctamente — comprueba que tu integración lea correctamente tokenexpiresat y vuelva a obtener las credenciales antes de que caduquen, para que las extracciones de métricas programadas no fallen durante la noche. ^[8]