Cómo ver las analíticas de elementos anclados en Zoho Desk

Las analíticas de elementos anclados en Zoho Desk se pueden recuperar de forma programática a través de un endpoint de API dedicado que devuelve datos de interacción para los ítems anclados. Esta guía te explica cómo llamar a ese endpoint utilizando el cliente de la API de Zoho Desk.

Por qué esto es importante

Si gestionas una base de conocimiento o un portal de soporte en Zoho Desk, entender el rendimiento del contenido anclado te ayuda a priorizar qué elementos permanecen visibles para los clientes. Los equipos que hacen seguimiento de la interacción con artículos o de la productividad de los agentes suelen necesitar las analíticas de anclaje como parte de flujos de trabajo de informes más amplios. Esto resulta especialmente útil al crear dashboards o automatizar informes fuera de la interfaz nativa de Zoho Desk.

Paso a paso

Paso 1. Asegúrate de que tu conexión OAuth de Zoho Desk esté activa y de que tu token de acceso sea válido. El cliente de la API gestiona la renovación del token automáticamente, pero tu conexión inicial debe estar establecida y almacenada. Si utilizas el motor Zpilot, el helper getzohoapi recuperará y renovará las credenciales en tu nombre. ^[7]

Paso 2. Confirma que tus scopes de OAuth incluyen los permisos necesarios de Zoho Desk. Como mínimo, tu entorno debe tener configurados Desk.tickets.READ, Desk.basic.READ y Desk.search.READ — estos forman parte del bloque estándar ZOHODESKSCOPES. Sin los scopes correctos, la API rechazará tu solicitud. ^[2]

Paso 3. Instancia el cliente ZohoDeskApi con un ZohoDeskClient válido. Necesitarás tu dominio de API, un token de acceso vigente y el ID de tu organización (orgid). Si tu orgid aún no está almacenado, el cliente puede descubrirlo automáticamente llamando a getallorganizations y leyendo el primer resultado de la lista devuelta. ^[7]

Paso 4. Llama al endpoint de analíticas de anclaje utilizando el siguiente método en tu instancia de ZohoDeskApi:

result = api.get_pin_analytics(p={})

Esto envía una solicitud GET a /api/v1/doc/pinanalytics. El parámetro p acepta un diccionario opcional de parámetros de consulta — pasa un dict vacío si no tienes filtros que aplicar. ^[1]

Paso 5. Procesa la respuesta. El método devuelve la respuesta bruta de la API como un objeto Python. Itera sobre los datos devueltos para extraer las métricas relevantes para tus necesidades de informes. Si utilizas la interfaz de chat de Zpilot, el asistente formateará automáticamente los campos clave en texto plano. ^[5]

Paso 6. Si ejecutas esto dentro del conjunto de pruebas del motor Zpilot, puedes ejercitar el endpoint a través de la clase DeskTestRunner. Inicializa el runner con tu org_id y un nivel de riesgo "SAFE", llama a setup() para establecer la conexión y luego invoca el método de analíticas directamente. ^[8]

Errores comunes

• Org ID ausente: Si org_id está en blanco o no se ha persistido en tu registro de conexión, el cliente de Desk puede fallar silenciosamente o devolver un error de autorización. Verifica siempre que el org ID esté completado antes de realizar llamadas. ^[7]
• Tokens expirados: El renovador de tokens consulta la base de datos para obtener el refreshtoken más reciente y actualiza el accesstoken almacenado si tiene éxito. Si la renovación falla — por ejemplo, debido a un client secret revocado — el renovador devuelve None y las llamadas posteriores a la API fallarán. ^[7]
• Scopes faltantes: La configuración ZOHODESKSCOPES no incluye un scope de analíticas dedicado por nombre. Si Zoho añade la aplicación de scopes para las analíticas de anclaje en una versión futura de la API, es posible que debas agregarlo a tu configuración .env. ^[2]
• Conflictos de puerto: Si ejecutas el servidor Zpilot localmente, debe correr en el puerto 8080. Usar cualquier otro puerto rompe el URI de redirección de OAuth e impide completamente la adquisición del token. ^[6]

Qué verificar

• Verifica que tu orgid esté almacenado en el registro de base de datos zohoconnections antes de llamar al endpoint — un org ID ausente es la causa más común de fallos silenciosos. ^[7]
• Confirma los scopes de OAuth en tu archivo .env e incluye como mínimo Desk.basic.READ y Desk.search.READ para garantizar que la API de Desk acepte tus solicitudes. ^[2]
• Inspecciona la respuesta bruta de getpinanalytics para verificar la presencia de una clave data o una estructura de lista esperada antes de construir cualquier lógica de informes posterior sobre ella. ^[1]

---

*Beam Help es soporte experto independiente para Zoho — no somos el soporte oficial de Zoho, y esta guía se basa en el comportamiento de la API observado en la documentación de la API REST de Zoho Desk y en implementaciones de clientes.*