Cómo acceder a los iconos disponibles en Zoho Desk

Zoho Desk expone un endpoint de API dedicado que devuelve el catálogo completo de iconos disponibles dentro de la plataforma — útil al crear widgets personalizados, extensiones o componentes de interfaz con temática propia.

Por qué esto es importante

Cuando desarrollas una extensión de Zoho Desk o personalizas la interfaz del portal, necesitas saber qué identificadores de iconos son válidos antes de referenciarlos en tu código. Consultar el endpoint de iconos disponibles de forma programática te evita adivinar nombres de iconos y previene errores de renderizado en producción. Esto es especialmente relevante para equipos que crean widgets o automatizaciones en Desk que muestran elementos visuales a los agentes.

Paso a paso

Paso 1. Asegúrate de que tu integración tenga una conexión activa y autenticada con Zoho Desk. La conexión requiere un token de acceso OAuth válido obtenido mediante los scopes adecuados de Desk — como mínimo se necesita Desk.basic.READ para consultas de metadatos generales, y tu token debe mantenerse vigente mediante un flujo de refresh token. ^[2][3]

Paso 2. Confirma que tu org_id (el identificador de organización de Zoho Desk) esté disponible en el contexto de tu conexión. Si aún no se ha almacenado, el cliente de API puede descubrirlo automáticamente llamando al endpoint de organizaciones y persistiendo el primer valor id devuelto para solicitudes posteriores. ^[3][5]

Paso 3. Envía una solicitud GET a la siguiente ruta de la API de Zoho Desk:

GET /api/v1/_doc/__available_icons

Este endpoint está documentado internamente como la operación "Available Icons" (getavailableicons) y acepta un diccionario de parámetros de consulta opcionales (p) para cualquier opción de filtrado o paginación que desees pasar. ^[7]

Paso 4. En Python, usando el wrapper de cliente ZohoDeskApi, la llamada tiene este aspecto:

def get_available_icons(self, p: dict = None):
    return self.c.request("GET", "/api/v1/_doc/__available_icons", p, None)

Pasa p={} (un diccionario vacío) si no tienes parámetros de consulta adicionales, o complétalo con las claves de filtro compatibles que necesites. ^[7]

Paso 5. Analiza el payload de la respuesta. Los datos devueltos contendrán los identificadores de iconos que puedes referenciar al construir componentes de interfaz dentro de Zoho Desk. Almacena o guarda en caché esta lista localmente si tu extensión necesita validar nombres de iconos en tiempo de compilación en lugar de en tiempo de ejecución.

---

Errores comunes

• Token de acceso ausente o caducado. Si el token ha expirado, la solicitud será rechazada. Asegúrate de que la lógica de renovación del token de tu integración se ejecute antes de llamar al endpoint — el flujo de refresh debe actualizar los campos accesstoken y tokenexpires_at almacenados en tu registro de conexión. ^[3]
• orgid ausente. Las llamadas a la API de Zoho Desk requieren que el ID de organización esté presente en los encabezados de la solicitud o en la configuración del cliente. Si orgid está vacío, el cliente puede fallar silenciosamente o devolver un error de permisos. Verifica siempre que el valor esté completado antes de realizar cualquier llamada a la API de Desk. ^[3][5]
• Pasar None en lugar de un diccionario vacío para p. La firma del método acepta p: dict = None, por lo que si lo llamas sin argumentos el parámetro toma el valor predeterminado None. Dependiendo de cómo el cliente HTTP subyacente gestione None, esto puede omitir los parámetros de consulta por completo — lo cual está bien para este endpoint, pero sé deliberado al respecto. ^[7]

---

Qué verificar

• Validez del token: Confirma que tu token de acceso OAuth esté vigente y que el mecanismo de refresh token esté correctamente configurado antes de realizar la llamada. ^[3]
• Presencia del Org ID: Verifica que deskorgid esté completado en tu registro de conexión; si está vacío, activa primero el flujo de autodescubrimiento. ^[5]
• Cobertura de scopes: Comprueba que Desk.basic.READ (como mínimo) esté incluido en tus scopes OAuth autorizados, ya que los endpoints de metadatos generalmente lo requieren. ^[2]

---

*Beam Help es un recurso de soporte experto independiente para productos Zoho y no es el soporte oficial de Zoho. Consulta siempre la documentación más reciente de la API de Zoho Desk para tu región de centro de datos.*