Come recuperare i link personalizzati in Zoho

I link personalizzati in Zoho CRM possono essere recuperati tramite un endpoint dedicato alle impostazioni, che accetta un parametro modulo e restituisce i link configurati per quel modulo.

Perché è importante

Quando si creano integrazioni o flussi di lavoro assistiti dall'IA su Zoho CRM, spesso è necessario esporre link di navigazione diretti a record o moduli specifici. Sapere come interrogare l'endpoint delle impostazioni dei link personalizzati — e come tali link vengono assemblati e restituiti all'utente finale — consente di incorporare deep-link contestuali in dashboard, interfacce di chat o strumenti di automazione senza dover codificare gli URL in modo statico.

Procedura passo dopo passo

Passaggio 1. Invia una richiesta GET all'endpoint /settings/custom_links in Zoho CRM, passando il nome del modulo di destinazione come parametro m (mappato internamente su module). Questa è l'operazione dedicata al recupero delle configurazioni dei link personalizzati nella categoria Impostazioni aggiuntive. ^[7]

GET /settings/custom_links?module=<ModuleName>

Passaggio 2. La firma del metodo sottostante è la seguente — il livello di integrazione chiama getcustomlinks(m), dove m è la stringa del modulo (ad esempio, "Leads" o "Contacts"). Il client invia la richiesta con {"module": m} come parametro di query. ^[7]

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

Passaggio 3. Una volta ottenuto il risultato grezzo dell'API, passalo attraverso il livello di costruzione dei link. La funzione buildzoholinks accetta il risultato dello strumento, il nome dello strumento, il dizionario dei parametri (che deve contenere una chiave "module"), il tipo di app e l'identificatore del data center (dc). Per i record CRM, il pattern dell'URL segue https://crm.zoho.{dc}/crm/tab/{Module}/{RecordId}. ^[1]

Passaggio 4. Il valore dc (data center) determina quale dominio regionale viene utilizzato. Quando dc è "com", l'URL base si risolve in https://crm.zoho.com; per qualsiasi altra regione diventa https://crm.zoho.{dc}. Se la tua organizzazione ha configurato un ID org CRM, il percorso viene ulteriormente preceduto da /org{crmorgid}. ^[1]

Passaggio 5. Dopo l'esecuzione di buildzoholinks, ogni voce nell'elenco restituito è un dizionario con tre chiavi: name, url e type. In un'interfaccia di chat o assistente, questi vengono visualizzati come deep-link etichettati nel formato 🔗 {name}: {url} e aggiunti al messaggio dell'assistente sotto un'intestazione "Apri in Zoho:". ^{[2] [3]}

Passaggio 6. I link assemblati vengono anche inseriti nel payload della risposta API sotto la chiave "links", insieme a sessionid, response e toolresult. I consumer a valle possono leggere response_data["links"] per visualizzare o elaborare gli URL indipendentemente dal testo formattato. ^[5]

Passaggio 7. Nei contesti di streaming (ad esempio, l'endpoint /api/chat/stream), la stessa chiamata buildzoholinks viene effettuata dopo l'esecuzione di ogni azione di sola lettura. L'oggetto di connessione fornisce i valori dc, crmorgid, deskorgid e desk_portal, con valore predefinito "com" se il dizionario di connessione è assente. ^{[6] [8]}

Errori comuni

• Parametro modulo mancante. La chiamata getcustomlinks richiede una stringa m non vuota. Passare un nome di modulo vuoto o errato restituirà nessun risultato o un errore API. Verifica sempre il nome del modulo rispetto all'elenco dei moduli attivi del tuo CRM prima di chiamare l'endpoint. ^[7]

• Valore del data center errato. Se dc è lasciato come "com" ma la tua organizzazione si trova su un data center EU o IN, ogni link generato punterà al dominio sbagliato. Assicurati che il valore dc venga recuperato dalla configurazione di connessione memorizzata anziché essere codificato in modo statico. ^{[1] [6]}

• Confusione tra link Desk e CRM. La funzione buildzoholinks si dirama in base a apptype. Se apptype è impostato su "desk" quando si intendono link CRM, gli URL di output seguiranno il pattern Desk (https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}) invece del pattern tab CRM. ^[1]

• Link di fallback invece di link ai record. Quando non è possibile estrarre un ID record specifico dal risultato dello strumento, la funzione ricade su URL generici della vista elenco come /tickets, /contacts o /accounts. Se visualizzi link alla vista elenco invece di deep-link a livello di record, verifica che il risultato dello strumento contenga i campi ID record previsti. ^[4]

Cosa verificare

• Conferma che il parametro module passato a /settings/custom_links corrisponda esattamente al nome API del modulo nella tua organizzazione Zoho CRM (distinzione tra maiuscole e minuscole). ^[7]
• Verifica che il valore dc nella configurazione di connessione corrisponda all'effettiva regione del data center della tua organizzazione, in modo che tutti gli URL generati si risolvano correttamente. ^[1]
• Dopo aver recuperato i link, esamina l'array "links" nel payload della risposta per assicurarti che ogni voce contenga un name, un url e un type validi prima di visualizzarli nell'interfaccia utente. ^[5]

---

*Beam Help fornisce una guida esperta indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho.*