Cómo recuperar enlaces personalizados en Zoho

Los enlaces personalizados en Zoho CRM se pueden recuperar a través de un endpoint de configuración dedicado que acepta un parámetro de módulo y devuelve los enlaces configurados para ese módulo.

Por qué es importante

Al crear integraciones o flujos de trabajo asistidos por IA sobre Zoho CRM, a menudo necesitas mostrar enlaces de navegación directa a registros o módulos específicos. Saber cómo consultar el endpoint de configuración de enlaces personalizados —y cómo se ensamblan y devuelven esos enlaces al usuario final— te permite incorporar deep-links contextuales en paneles de control, interfaces de chat o herramientas de automatización sin codificar las URLs de forma fija.

Paso a paso

Paso 1. Envía una solicitud GET al endpoint /settings/custom_links en Zoho CRM, pasando el nombre del módulo de destino como parámetro m (mapeado internamente a module). Esta es la operación dedicada para recuperar configuraciones de enlaces personalizados dentro de la categoría de Configuración Adicional. ^[7]

GET /settings/custom_links?module=<ModuleName>

Paso 2. La firma del método subyacente es la siguiente: tu capa de integración llama a getcustomlinks(m), donde m es la cadena del módulo (por ejemplo, "Leads" o "Contacts"). El cliente emite la solicitud con {"module": m} como parámetro de consulta. ^[7]

def get_custom_links(self, m: str):
    return self.c.request("GET", "/settings/custom_links", {"module": m})

Paso 3. Una vez que tengas el resultado bruto de la API, pásalo a través de la capa de construcción de enlaces. La función buildzoholinks acepta el resultado de la herramienta, el nombre de la herramienta, el diccionario de parámetros (que debe contener una clave "module"), el tipo de aplicación y el identificador del centro de datos (dc). Para los registros de CRM, el patrón de URL sigue https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. ^[1]

Paso 4. El valor de dc (centro de datos) controla qué dominio regional se utiliza. Cuando dc es "com", la URL base se resuelve como https://crm.zoho.com; para cualquier otra región se convierte en https://crm.zoho.{dc}. Si tu organización tiene configurado un ID de organización de CRM, la ruta se prefija adicionalmente con /org{crmorgid}. ^[1]

Paso 5. Después de que buildzoholinks se ejecute, cada entrada en la lista devuelta es un diccionario con tres claves: name, url y type. En una interfaz de chat o asistente, estos se renderizan como deep-links etiquetados con el formato 🔗 {name}: {url} y se añaden al mensaje del asistente bajo un encabezado «Abrir en Zoho:». ^{[2] [3]}

Paso 6. Los enlaces ensamblados también se inyectan en el payload de respuesta de la API bajo la clave "links", junto con sessionid, response y toolresult. Los consumidores posteriores pueden leer response_data["links"] para mostrar o procesar las URLs de forma independiente al texto formateado. ^[5]

Paso 7. En contextos de streaming (por ejemplo, el endpoint /api/chat/stream), se realiza la misma llamada a buildzoholinks después de que se ejecute cada acción de solo lectura. El objeto de conexión proporciona los valores dc, crmorgid, deskorgid y desk_portal, con valor predeterminado "com" si el diccionario de conexión está ausente. ^{[6] [8]}

Errores comunes

• Parámetro de módulo ausente. La llamada a getcustomlinks requiere una cadena m no vacía. Pasar un nombre de módulo vacío o incorrecto devolverá sin resultados o generará un error de API. Valida siempre el nombre del módulo contra la lista de módulos activos de tu CRM antes de llamar al endpoint. ^[7]

• Valor de centro de datos incorrecto. Si dc se deja como "com" pero tu organización está en un centro de datos de la UE o IN, cada enlace generado apuntará al dominio incorrecto. Asegúrate de que el valor de dc se obtenga de la configuración de conexión almacenada en lugar de estar codificado de forma fija. ^{[1] [6]}

• Confusión entre enlaces de Desk y CRM. La función buildzoholinks se ramifica según apptype. Si apptype está configurado como "desk" cuando pretendes obtener enlaces de CRM, las URLs de salida seguirán el patrón de Desk (https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}) en lugar del patrón de pestaña de CRM. ^[1]

• Enlaces de reserva en lugar de enlaces de registro. Cuando no se puede extraer ningún ID de registro específico del resultado de la herramienta, la función recurre a URLs genéricas de vista de lista como /tickets, /contacts o /accounts. Si estás viendo enlaces de vista de lista en lugar de deep-links a nivel de registro, comprueba que el resultado de la herramienta contiene los campos de ID de registro esperados. ^[4]

Qué verificar

• Confirma que el parámetro module pasado a /settings/custom_links coincida exactamente con el nombre de API del módulo en tu organización de Zoho CRM (distingue entre mayúsculas y minúsculas). ^[7]
• Verifica que el valor de dc en tu configuración de conexión coincida con la región del centro de datos real de tu organización para que todas las URLs generadas se resuelvan correctamente. ^[1]
• Después de recuperar los enlaces, inspecciona el array "links" en el payload de respuesta para asegurarte de que cada entrada contenga un name, url y type válidos antes de renderizarlos en tu interfaz. ^[5]

---

*Beam Help proporciona orientación experta independiente para los productos de Zoho y no es el soporte oficial de Zoho.*