Come mappare le competenze degli agenti in Zoho Desk

La mappatura delle competenze degli agenti in Zoho Desk ti consente di associare specifiche abilità ai singoli agenti, in modo che i ticket possano essere instradati alla persona più qualificata. Questo articolo illustra come recuperare e utilizzare i dati di mappatura delle competenze degli agenti tramite l'API di Zoho Desk.

Perché è importante

Quando la tua operazione di supporto cresce oltre un numero ristretto di agenti, instradare i ticket in base alle competenze diventa essenziale per la risoluzione al primo contatto. Capire come sono strutturate le mappature delle competenze — e come interrogarle — ti permette di costruire automazioni, verificare le assegnazioni e mantenere accurate le regole di instradamento. Questo è particolarmente rilevante se stai integrando Zoho Desk con strumenti esterni di gestione della forza lavoro o di reportistica. Come sempre, Beam Help è un supporto esperto indipendente per Zoho e non è il supporto ufficiale Zoho.

Procedura passo dopo passo

Passaggio 1. Verifica che il tuo token OAuth includa gli scope corretti di Zoho Desk prima di effettuare qualsiasi chiamata API. Come minimo avrai bisogno di Desk.basic.READ e Desk.settings.READ nel tuo elenco di scope autorizzati, poiché i dati degli agenti e dell'organizzazione rientrano in quelle categorie di autorizzazione. ^[5]

Passaggio 2. Per recuperare il documento di mappatura delle competenze degli agenti, invia una richiesta GET all'endpoint /api/v1/doc/agentskill_mapping. Questo endpoint restituisce la struttura completa della mappatura delle competenze per la tua organizzazione Desk. Passa eventuali parametri di query opzionali come dizionario nell'argomento p se hai bisogno di filtrare o paginare i risultati. ^[1]

Passaggio 3. Se il tuo livello di integrazione è basato su Python, la chiamata si presenta così in pratica:

result = client.get_agent_skill_mapping(p={"param_key": "param_value"})

Il metodo invia una GET a /api/v1/doc/agentskillmapping e restituisce la risposta analizzata. Usa lo stesso endpoint sia che tu lo chiami come getagentskillmapping o con l'alias operativo alternativo getagentskillmapping2 — entrambi risolvono allo stesso percorso identico. ^[1][2]

Passaggio 4. Una volta ottenuti i dati di mappatura delle competenze, incrocia i singoli agenti interrogando gli agenti filtrati per profilo assegnato. Invia una richiesta GET a /api/v1/profiles/{profile_id}/agents, sostituendo l'identificatore di profilo pertinente, per elencare ogni agente associato a quel profilo. ^[6]

Passaggio 5. Allo stesso modo, se i tuoi raggruppamenti di competenze si allineano con le definizioni dei ruoli, puoi recuperare gli agenti per ruolo usando GET /api/v1/roles/{role_id}/agents. Fornisci l'identificatore del ruolo nel percorso per ottenere l'elenco degli agenti corrispondenti. ^[7]

Passaggio 6. Quando costruisci qualsiasi livello di interfaccia utente o reportistica sopra questi risultati, crea i link ai record di Zoho Desk usando il pattern https://desk.zoho.{dc}/agent/{portal}/tickets/details/{TicketId}, dove dc è il suffisso del tuo data center (ad es. com, eu) e portal è il nome del tuo portale Desk. Questo ti consente di mostrare link profondi cliccabili insieme ai dati di mappatura delle competenze. ^[4]

Errori comuni

• Gli scope mancanti causano errori silenziosi. Se Desk.basic.READ o Desk.settings.READ è assente dalla tua concessione OAuth, l'endpoint di mappatura delle competenze restituirà un errore di autorizzazione anziché i dati. Controlla attentamente la stringa degli scope nella configurazione dell'ambiente prima di eseguire il debug della chiamata API stessa. ^[5]
• Nomi di operazioni duplicati. L'endpoint di mappatura delle competenze è registrato sotto due identificatori di operazione (getagentskillmapping e getagentskillmapping_2). Entrambi puntano allo stesso percorso, quindi chiamare l'uno o l'altro è funzionalmente equivalente — ma se stai generando automaticamente il codice client da una specifica OpenAPI, tieni presente che potresti vedere entrambi e dovresti deduplicarli. ^[1][2]
• Confusione tra Profile ID e Role ID. Gli agenti possono essere interrogati per profilo (/api/v1/profiles/{profileid}/agents) o per ruolo (/api/v1/roles/{roleid}/agents). Questi sono identificatori distinti e non sono intercambiabili — usare un ID ruolo nell'endpoint dei profili restituirà un errore o un risultato vuoto. ^[6][7]

Cosa verificare

• Verifica che il tuo token OAuth attivo contenga sia Desk.basic.READ che Desk.settings.READ prima di eseguire qualsiasi query di mappatura delle competenze. ^[5]
• Conferma che la risposta da /api/v1/doc/agentskill_mapping contenga i campi agente e competenza previsti, e che il conteggio dei record corrisponda a quanto visualizzato nel pannello di amministrazione di Zoho Desk. ^[1]
• Dopo l'incrocio con gli endpoint di profilo o ruolo, assicurati che ogni ID agente restituito appaia in modo coerente in tutte e tre le risposte per escludere mappature obsolete o configurate in modo errato. ^[6][7]