Integracja n8n z Zendesk: nody, poświadczenia i przykładowe workflowy

Node Zendesk odczytuje lub zmienia dane w Zendesk jako krok workflow. Dokumentacja n8n grupuje jego operacje według zasobów.

Jedno zachowanie często zaskakuje. Gdy używasz Update Ticket i wypełniasz pole Tag Names or IDs, według dokumentacji n8n cała lista tagów zgłoszenia zostaje zastąpiona, więc każdy tag, którego nie uwzględnisz, zostanie usunięty. Wynika to z domyślnego sposobu, w jaki Zendesk API obsługuje aktualizacje tagów. Dokumentacja podaje trzy obejścia: pobierz bieżące tagi i scal je z nowymi przed aktualizacją, użyj node'a HTTP Request z właściwością additional_tags w Zendesk albo wywołaj endpoint tagów zgłoszenia. Dwa ostatnie dodają tagi bez usuwania istniejących.

Jeśli node nie obsługuje potrzebnej Ci operacji, użyj node'a HTTP Request, ustaw Authentication na Predefined Credential Type i wybierz swoje poświadczenia Zendesk. Żądanie korzysta wtedy z tego samego połączenia co node Zendesk.

Nody Zendesk i Zendesk Trigger korzystają z tych samych poświadczeń, a n8n obsługuje dwa sposoby uwierzytelniania. Oba wymagają Twojej subdomeny, czyli części adresu URL Zendesk między https:// a .zendesk.com.

• Token API: w Zendesk Admin Center otwórz Apps and integrations, a następnie APIs, i włącz dostęp przez token dla Zendesk API. Dodaj token z opisem i skopiuj go. W n8n wpisz subdomenę, adres e-mail, którym logujesz się do Zendesk, i token.
• OAuth2: w Zendesk Admin Center utwórz klienta OAuth w Apps and integrations, a następnie APIs. Wklej adres OAuth callback URL z n8n w pole redirect URL klienta. Skopiuj unikalny identyfikator klienta do pola Client ID w n8n, a jego sekret do Client Secret, dodaj subdomenę, zapisz i połącz swoje konto Zendesk.

Workflow n8n można uruchomić z Zendesk na dwa sposoby. Node Zendesk Trigger uruchamia workflow, gdy zdarzenia w Zendesk pasują do warunków ustawionych w nodzie. W przykładzie z dokumentacji n8n filtruje zgłoszenia o statusie Open, a workflow działa po jego włączeniu.

Alternatywą jest samodzielne zbudowanie połączenia. W Zendesk Admin Center przejdź do Apps and integrations, a następnie Webhooks, utwórz webhook, wybierz Trigger or Automation jako metodę połączenia i skieruj go na Production URL node'a Webhook w n8n. Następnie dodaj akcję 'Notify webhook' do triggera lub automatyzacji Zendesk i napisz payload, który nie może przekraczać 16 000 znaków. Dzięki temu warunki pozostają w regułach biznesowych Zendesk, a Ty dokładnie wybierasz, które pola wysłać.

Jeśli używasz webhooka, sprawdzaj, czy żądania naprawdę pochodzą z Zendesk. Zendesk wysyła dwa nagłówki: X-Zendesk-Webhook-Signature i X-Zendesk-Webhook-Signature-Timestamp. Podpis to base64(HMACSHA256(timestamp + body)) utworzony z użyciem sekretu podpisującego webhooka, który możesz odsłonić na stronie szczegółów webhooka lub pobrać przez API. Przelicz go w swoim workflow i odrzucaj żądania, które się nie zgadzają. Zendesk zaznacza też, że ta sama akcja może wywołać webhook więcej niż raz, więc zadbaj, aby workflow można było bezpiecznie uruchomić dwa razy dla tego samego zgłoszenia.

Node Webhook może odpowiedzieć od razu, po zakończeniu ostatniego node'a albo przez osobny node Respond to Webhook. Przy dłuższych workflowach natychmiastowa odpowiedź szybko potwierdza odbiór po stronie Zendesk, podczas gdy reszta pracy trwa dalej.

Oto popularny wzorzec opisany krok po kroku. Pokazuje, jak nody do siebie pasują. To nie jest case study TascaLab.

1. Trigger: node Zendesk Trigger albo node Webhook zasilany przez trigger Zendesk, który uruchamia się po utworzeniu zgłoszenia. Wyślij co najmniej ID zgłoszenia.
2. Pobranie: node Zendesk z zasobem Ticket pobiera pełne zgłoszenie, w tym temat, opis i bieżące tagi.
3. Klasyfikacja: node Text Classifier przypisuje tekst do zdefiniowanych przez Ciebie kategorii, np. rozliczenia, problem techniczny lub zwrot. Każda kategoria ma nazwę i opis, który pomaga modelowi. Domyślnie elementy niepasujące do żadnej kategorii są odrzucane, więc włącz gałąź Other, aby je wychwycić.
4. Aktualizacja: node Zendesk ustawia grupę i tagi. Najpierw scal istniejące tagi albo dodaj tagi przez node HTTP Request z additional_tags, aby nie wymazać tagów ustawionych przez agentów.
5. Powiadomienie: node Slack publikuje kategorię i link do zgłoszenia na kanale zespołu.
6. Obsługa błędów: wysyłaj nieudane uruchomienia do alertu, a gdy Zendesk zwróci odpowiedź 429, odczekaj i ponów próbę.

Ten sam wzorzec możesz rozbudować. Wysyłaj pilne zgłoszenia na osobny kanał Slack albo przed wyborem grupy wyszukaj organizację klienta za pomocą zasobu Organization.

Zendesk ogranicza liczbę żądań API na minutę w zależności od planu. Dokumentacja dla deweloperów podaje następujące domyślne limity dla Support API i Help Center API:

• Suite Team: 200 żądań na minutę.
• Suite Growth i Suite Professional: 400 żądań na minutę.
• Suite Enterprise: 700 żądań na minutę.
• Suite Enterprise Plus: 2 500 żądań na minutę.

Dodatek High Volume API podnosi limit kwalifikującego się planu do 2 500 żądań na minutę. Zastępuje on limit planu, a nie się do niego dodaje, i wymaga planu Suite Growth lub wyższego (albo Support Professional lub wyższego) z co najmniej 10 licencjami agentów. Po przekroczeniu limitu Zendesk zwraca HTTP 429 z nagłówkiem Retry-After, który podaje, ile sekund trzeba odczekać. Niektóre endpointy mają własne, surowsze limity. Policz wywołania API wykonywane przy każdym uruchomieniu i pomnóż przez szczytowy wolumen zgłoszeń. Zadania zbiorcze, np. uzupełnianie tagów w starych zgłoszeniach, częściej trafiają na limit, więc dziel je na partie i dodawaj odczekiwanie.

n8n działa jako n8n Cloud – zarządzana instancja, którą n8n uruchamia za Ciebie – albo jako instalacja self-hosted na Twoim własnym komputerze lub infrastrukturze. W większości instalacji self-hosted dokumentacja zaleca Dockera, a n8n Cloud – jeśli nie masz doświadczenia w zarządzaniu serwerami. Przy obu metodach uruchamiania Zendesk musi mieć dostęp do Twojej instancji n8n. Jeśli instancja self-hosted stoi za reverse proxy, ustaw N8N_WEBHOOK_URL na jej publiczny bazowy URL, aby n8n pokazywało prawidłowe adresy URL webhooków, a usługi zewnętrzne poprawnie je rejestrowały. N8N_WEBHOOK_URL zastępuje WEBHOOK_URL, które nadal działa, ale od n8n 2.35.0 jest przestarzałe (deprecated).

TascaLab buduje takie automatyzacje Zendesk z użyciem n8n, Make, API i webhooków, na narzędziach, których już używasz. Projekty Ticket Routing & Categorization kosztują 3000 zł, a projekty Custom Automation od 4650 zł. Większość wdrożeń trwa od 1 do 3 tygodni, a każdy projekt obejmuje podstawową dokumentację i 30 dni wsparcia po uruchomieniu. Możesz zacząć od bezpłatnej 30-minutowej rozmowy Health Check.