Integrazione n8n Zendesk: nodi, credenziali e workflow di esempio

Il nodo Zendesk legge o modifica dati in Zendesk come passaggio di un workflow. La documentazione di n8n raggruppa le sue operazioni per risorsa.

C'è un comportamento che coglie molti di sorpresa. Quando usi Update Ticket e compili il campo Tag Names or IDs, la documentazione di n8n dice che l'intero elenco di tag del ticket viene sostituito, quindi ogni tag che non includi viene rimosso. Questo rispecchia il modo in cui l'API di Zendesk gestisce per impostazione predefinita gli aggiornamenti dei tag. La documentazione indica tre soluzioni: recuperare i tag attuali e unirli a quelli nuovi prima dell'aggiornamento, usare il nodo HTTP Request con la proprietà additional_tags di Zendesk, oppure chiamare l'endpoint dei tag del ticket. Le ultime due aggiungono tag senza rimuovere quelli esistenti.

Se il nodo non supporta un'operazione che ti serve, usa il nodo HTTP Request, imposta Authentication su Predefined Credential Type e scegli la tua credenziale Zendesk. La richiesta riutilizza così la stessa connessione del nodo Zendesk.

I nodi Zendesk e Zendesk Trigger usano la stessa credenziale e n8n supporta due modalità di autenticazione. Entrambe richiedono il tuo sottodominio, cioè la parte dell'URL di Zendesk tra https:// e .zendesk.com.

• API token: nell'Admin Center di Zendesk apri Apps and integrations, poi APIs, e abilita l'accesso tramite token per la Zendesk API. Aggiungi un token con una descrizione e copialo. In n8n inserisci il sottodominio, l'indirizzo email che usi per accedere a Zendesk e il token.
• OAuth2: nell'Admin Center di Zendesk crea un client OAuth in Apps and integrations, poi APIs. Incolla l'URL di callback OAuth di n8n nel campo dell'URL di reindirizzamento del client. Copia l'identificativo univoco del client in Client ID in n8n e il suo secret in Client Secret, aggiungi il sottodominio, salva e collega il tuo account Zendesk.

Ci sono due modi per avviare un workflow n8n da Zendesk. Il nodo Zendesk Trigger avvia un workflow quando gli eventi di Zendesk corrispondono alle condizioni che imposti nel nodo. Nell'esempio della documentazione di n8n, filtra i ticket con stato Open e il workflow gira non appena lo attivi.

L'alternativa è costruire tu stesso la connessione. Nell'Admin Center di Zendesk vai in Apps and integrations, poi Webhooks, crea un webhook, scegli Trigger o Automation come metodo di connessione e indirizzalo verso il Production URL di un nodo Webhook di n8n. Poi aggiungi l'azione Notify webhook a un trigger o a un'automazione di Zendesk e scrivi il payload, che non può superare i 16.000 caratteri. Così le condizioni restano nelle regole aziendali di Zendesk e puoi scegliere esattamente quali campi inviare.

Se usi un webhook, verifica che le richieste arrivino davvero da Zendesk. Zendesk invia due header, X-Zendesk-Webhook-Signature e X-Zendesk-Webhook-Signature-Timestamp. La firma è base64(HMACSHA256(timestamp + body)) calcolata con il signing secret del webhook, che puoi visualizzare nella pagina dei dettagli del webhook o ottenere tramite l'API. Ricalcolala nel tuo workflow e rifiuta le richieste che non corrispondono. Zendesk avverte inoltre che la stessa azione può chiamare un webhook più di una volta, quindi fai in modo che il workflow possa girare due volte per lo stesso ticket senza problemi.

Il nodo Webhook può rispondere subito, quando termina l'ultimo nodo, oppure tramite un nodo Respond to Webhook separato. Per i workflow più lunghi, rispondere subito dà a Zendesk una risposta rapida mentre il resto del lavoro prosegue.

Ecco uno schema comune, descritto per passaggi. Mostra come i nodi si incastrano tra loro. Non è un caso di studio di TascaLab.

1. Trigger: un nodo Zendesk Trigger, oppure un nodo Webhook alimentato da un trigger di Zendesk che si attiva alla creazione di un ticket. Invia almeno l'ID del ticket.
2. Recupero: un nodo Zendesk con la risorsa Ticket ottiene il ticket completo, compresi oggetto, descrizione e tag attuali.
3. Classificazione: un nodo Text Classifier ordina il testo nelle categorie che definisci, come fatturazione, problema tecnico o rimborso. Ogni categoria ha un nome e una descrizione che aiuta il modello. Per impostazione predefinita, gli elementi che non corrispondono a nessuna categoria vengono scartati, quindi attiva il ramo Other per intercettarli.
4. Aggiornamento: un nodo Zendesk imposta il gruppo e i tag. Unisci prima i tag esistenti, oppure aggiungi i tag tramite il nodo HTTP Request con additional_tags, così non cancelli i tag impostati dagli agenti.
5. Notifica: un nodo Slack pubblica la categoria e un link al ticket nel canale del team.
6. Gestione degli errori: invia le esecuzioni non riuscite a un avviso, e attendi e riprova quando Zendesk restituisce una risposta 429.

Puoi estendere lo stesso schema. Invia i ticket urgenti a un canale Slack separato, oppure cerca l'organizzazione del cliente con la risorsa Organization prima di scegliere un gruppo.

Zendesk limita le richieste API al minuto in base al piano. La sua documentazione per sviluppatori indica questi limiti predefiniti per le API di Support e Help Center:

• Suite Team: 200 richieste al minuto.
• Suite Growth e Suite Professional: 400 richieste al minuto.
• Suite Enterprise: 700 richieste al minuto.
• Suite Enterprise Plus: 2.500 richieste al minuto.

L'add-on High Volume API porta un piano idoneo a 2.500 richieste al minuto. Sostituisce il limite del piano anziché aggiungersi a esso e richiede Suite Growth o superiore (oppure Support Professional o superiore) con almeno 10 postazioni agente. Oltre il limite, Zendesk restituisce HTTP 429 con un header Retry-After che indica quanti secondi aspettare. Alcuni endpoint hanno limiti propri, più restrittivi. Conta le chiamate API che fa ogni esecuzione e moltiplica per il tuo volume di ticket nei momenti di picco. I job massivi, come l'aggiunta retroattiva di tag ai ticket vecchi, hanno più probabilità di raggiungere il limite, quindi suddividili in blocchi e aggiungi delle attese.

n8n gira come n8n Cloud, un'istanza gestita che n8n fa girare per te, oppure in self-hosting sulla tua macchina o infrastruttura. Per la maggior parte delle installazioni self-hosted la documentazione consiglia Docker, e consiglia n8n Cloud se non hai esperienza nella gestione dei server. Con entrambi i metodi di attivazione, Zendesk deve poter raggiungere la tua istanza n8n. Se un'istanza self-hosted si trova dietro un reverse proxy, imposta N8N_WEBHOOK_URL sul suo URL di base pubblico, così n8n mostra gli URL dei webhook corretti e i servizi esterni li registrano correttamente. N8N_WEBHOOK_URL sostituisce WEBHOOK_URL, che funziona ancora ma è deprecata da n8n 2.35.0.

TascaLab realizza automazioni Zendesk come questa con n8n, Make, API e webhook, sugli strumenti che usi già. I progetti Ticket Routing & Categorization costano 690 € e i progetti Custom Automation da 1070 €. La maggior parte delle configurazioni richiede da 1 a 3 settimane e ogni progetto include documentazione di base e 30 giorni di supporto dopo il lancio. Puoi iniziare con una call di Health Check gratuita di 30 minuti.