KI-Agent an Zendesk anbinden: Tickets, Makros, Help Center
Zendesk ist für viele Service-Teams das System, in dem jede Kundenanfrage landet: als Ticket mit Verlauf, Feldern, Tags und Zuständigkeit. Wer einen eigenen KI-Agenten einführt, will genau dort ansetzen, statt ein zweites Werkzeug daneben zu stellen. Dieser Überblick zeigt, welche Schnittstellen Zendesk dafür bietet, wie die Bausteine zusammenspielen und wo die Grenzen liegen. Alle Angaben zur API beziehen sich auf die Zendesk-Entwicklerdokumentation, Stand November 2026.
Was bedeutet es, einen KI-Agenten an Zendesk anzubinden?
Ein angebundener KI-Agent ist ein eigener Dienst außerhalb von Zendesk, der bei neuen oder geänderten Tickets automatisch angestoßen wird, Ticket und Wissen liest und sein Ergebnis ins Ticket zurückschreibt. Zendesk bleibt das maßgebliche System; der Agent arbeitet zu, entscheidet aber nicht selbst über das Ticket, solange Sie das nicht ausdrücklich freigeben.
Typische Aufgaben eines solchen Agenten:
- Antwortentwurf: einen Vorschlag für die Antwort an den Kunden formulieren, gestützt auf Help-Center-Artikel und frühere Tickets.
- Einordnung: Kategorie, Priorität, Sprache oder betroffenes Produkt erkennen und als Tag oder Feld setzen.
- Zusammenfassung: lange Verläufe mit vielen Rückfragen auf wenige Zeilen verdichten, bevor ein Ticket die Gruppe wechselt.
- Datenabgleich: Seriennummer, Auftrags- oder Vertragsnummer aus dem Ticket lesen und in angebundenen Systemen nachschlagen.
Zendesk bietet mit AI Agents auch eine eigene KI-Lösung an, die nach Herstellerangaben in den Suite- und Support-Plänen enthalten ist. Ein eigener Agent ist dann sinnvoll, wenn Sie Modell, Datenhaltung und Logik selbst bestimmen wollen, etwa weil Wissen aus ERP, PLM oder Fileservern einfließen soll, das nicht in Zendesk liegt, oder weil das Modell im eigenen Rechenzentrum laufen soll. Welche Aufgaben ein Service-Agent fachlich übernehmen kann, beschreibt der Überblick zum Kundenservice-Agenten; dieser Artikel konzentriert sich auf die technische Anbindung an Zendesk.
Wie funktioniert die Anbindung? Die vier Bausteine
Die Anbindung besteht aus vier Teilen: einem Trigger, der entscheidet, wann der Agent gerufen wird; einem Webhook, der das Ticket meldet; der Ticket-API, über die der Agent liest und schreibt; und dem Help Center als Wissensquelle. Jeder Baustein ist in Zendesk dokumentiert und ohne Zusatzprodukt nutzbar.
Trigger: wann der Agent arbeitet
Trigger laufen bei jedem Anlegen oder Aktualisieren eines Tickets. Jeder Trigger hat Bedingungen (gruppiert in all und any) und Aktionen. Zendesk prüft alle Trigger der Reihe nach, die Position bestimmt die Reihenfolge, und die Aktionen eines Triggers können die Bedingungen eines späteren beeinflussen. Für den Agenten heißt das: Legen Sie genau fest, bei welchen Tickets er laufen soll, zum Beispiel „Ticket ist neu“, „Kanal ist E-Mail“ und „Gruppe ist Erstlösung“.
Webhook: wie Zendesk den Agenten benachrichtigt
Ein Webhook schickt eine HTTP-Anfrage an Ihren Dienst. Für Trigger wählen Sie den Verbindungstyp „Trigger oder Automatisierung“; in der API entspricht das subscriptions: ["conditional_ticket_events"]. Im Trigger kommt dann die Aktion „Notify webhook“ hinzu, in der API notification_webhook mit einem Array aus Webhook-ID und Nachrichtentext. Laut Zendesk-Hilfe können Sie im JSON-Payload Platzhalter für Ticketdaten verwenden; Payload und URL-Parameter dürfen 16.000 Zeichen nicht überschreiten.
Ein schlanker Payload ist meist die bessere Wahl: nur Ticket-ID und Anlass. Den Rest holt der Agent selbst über die API, dann arbeitet er immer mit dem aktuellen Stand.
{
"ticket_id": "{{ticket.id}}",
"event": "ticket_created"
}
Die zweite Verbindungsart, „Zendesk events“, sendet feste JSON-Payloads zu Ereignissen wie Ticket-, Benutzer- oder Help-Center-Aktivität. Methode und Inhalt sind dort nicht änderbar, und ein Webhook kann nachträglich nicht zwischen den Arten wechseln.
Ticket-API: lesen und zurückschreiben
Über GET /api/v2/tickets/{id} und GET /api/v2/tickets/{id}/comments liest der Agent Ticket und Verlauf; die Kommentarliste liefert höchstens 100 Einträge pro Seite. Zurückgeschrieben wird nicht über einen eigenen Kommentar-Endpunkt, sondern per Ticket-Update mit einem comment-Objekt, wie die Dokumentation zu Ticket-Kommentaren beschreibt.
Help Center: das Wissen des Agenten
Die Help-Center-API listet Artikel insgesamt, je Kategorie, je Sektion oder je Sprache. Der Artikeltext steht als HTML im Feld body; user_segment_id regelt, wer einen Artikel sehen darf. Wie ein solcher Wissensindex grundsätzlich aufgebaut wird, beschreibt der Artikel zu RAG im Unternehmen. Für die Aktualisierung ist der inkrementelle Endpunkt GET /api/v2/help_center/incremental/articles?start_time=<Unix-Zeit> praktisch, weil er nur seit einem Zeitpunkt geänderte Artikel liefert.
Interne Notiz oder öffentliche Antwort: der wichtigste Schalter
Jeder Kommentar hat das Feld public: true ist eine öffentliche Antwort, die der Kunde sieht, false eine interne Notiz nur für Agenten. Für einen KI-Agenten ist die interne Notiz der richtige Start, weil ein Mensch jeden Vorschlag sieht, bevor er beim Kunden ankommt (Human in the Loop).
Die Dokumentation nennt eine Eigenheit, die man kennen sollte: Der beim Anlegen gesetzte Wert von public gilt auch für spätere Kommentare, solange man ihn nicht ändert. Setzen Sie das Feld deshalb bei jedem Schreibvorgang ausdrücklich. Ein Update mit interner Notiz sieht so aus:
# Vorschlag des Agenten als interne Notiz zurückschreiben
curl -s -X PUT "https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${TICKET_ID}.json" \
-H "Authorization: Bearer ${ZENDESK_OAUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"ticket": {
"comment": {
"body": "Antwortvorschlag (KI-Agent): ...",
"public": false
}
}
}'
# Kennzeichnendes Tag ergänzen, ohne vorhandene Tags zu ersetzen
curl -s -X PUT "https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${TICKET_ID}/tags.json" \
-H "Authorization: Bearer ${ZENDESK_OAUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"tags": ["ki_vorschlag"]}'
Das Tag setzt der zweite Aufruf über den Endpunkt Add Tags (PUT), der vorhandene Tags behält; das Feld tags im Ticket-Update würde sie dagegen überschreiben.
Weitere Details aus der Dokumentation, die im Betrieb zählen:
bodyentfernt HTML und unterstützt Markdown nur, wenn der Autor ein Agent ist;html_bodynimmt HTML an und wird für den Agent Workspace empfohlen.- Kommentartexte sind auf 64 kB begrenzt; längere Texte werden ohne Fehlermeldung abgeschnitten. Prüfen Sie die Länge vorher.
- Ein Ticket nimmt höchstens 5.000 Kommentare auf.
- Mit
author_idkann ein anderer Benutzer als Autor erscheinen, als Bearbeiter des Tickets zählt aber weiter der API-Benutzer. Das beeinflusst Trigger und Ansichten.
Ein eigener technischer Benutzer für den Agenten macht dessen Beiträge in Berichten und Bedingungen eindeutig erkennbar, und ein festes Tag pro Aktion hilft, Trigger-Schleifen zu verhindern (siehe unten).
Makros: Standardantworten wiederverwenden
Makros sind gespeicherte Aktionen, mit denen Agenten Felder setzen und Standardtexte einfügen. Ein KI-Agent kann sie nutzen, statt eigene Formulierungen zu erfinden: Er wählt das passende Makro, übernimmt dessen Änderungen und ergänzt nur, was fallbezogen fehlt.
Die Makro-API bietet dafür GET /api/v2/macros/active (aktive Makros, die der Benutzer sehen darf), eine Suche über den Titel und zwei Vorschau-Endpunkte. Wichtig: Laut Dokumentation verändern die Apply-Endpunkte das Ticket nicht. GET /api/v2/tickets/{ticket_id}/macros/{macro_id}/apply liefert nur, wie das Ticket danach aussähe; schreiben muss der Agent selbst per Ticket-Update. Das ist kein Nachteil, sondern eine natürliche Prüfstelle: Der Agent kann die Vorschau mit dem Ticket abgleichen und bei Unsicherheit nur eine Notiz hinterlassen.
In der Praxis bewährt sich, Makros mit klaren Titeln und Kategorien zu pflegen. Der Agent bekommt die Liste der erlaubten Makros als Werkzeug, nicht als freien Zugriff auf alle.
Einsatzfelder und Varianten
Die Bausteine lassen sich je nach Ziel unterschiedlich kombinieren. Drei Varianten decken die meisten Vorhaben ab; sie unterscheiden sich vor allem darin, wie viel der Agent selbst schreiben darf und welche Wissensquellen er braucht.
Antwortentwurf als Notiz. Der Agent liest neue Tickets, sucht passende Help-Center-Artikel und frühere gelöste Tickets und schreibt einen Entwurf als interne Notiz mit Quellenangabe. Der Mensch übernimmt, ändert oder verwirft. Diese Variante ist der übliche Start, weil sie das Risiko klein hält und schnell zeigt, wie gut das Wissen trägt.
Einordnung und Weiterleitung. Der Agent setzt Tags, Priorität oder Gruppe. Hier schreibt er Felder statt Text, was leichter zu prüfen ist, aber direkt auf Ihre Trigger wirkt: Eine neue Gruppe kann weitere Trigger auslösen. Testen Sie diese Variante in einer Sandbox oder mit einer eng gefassten Bedingung.
Technischer Service mit Systemabgleich. Bei Störmeldungen zu Maschinen oder Anlagen liest der Agent Seriennummer und Fehlercode, schlägt in Handbüchern, Servicehistorie und Ersatzteillisten nach und legt eine strukturierte Notiz an. Wie solche Agenten fachlich aufgebaut sind, zeigt die Seite zum Agenten für technischen Service; welche Rolle ein gepflegter Wissensbestand spielt, beschreibt der Wissensmanagement-Agent.
Eine Schritt-für-Schritt-Anleitung mit Code für die erste Variante folgt in einem eigenen Tutorial. Für Freshdesk gelten dieselben Grundideen, die Begriffe und Endpunkte unterscheiden sich aber; dazu entsteht ein eigener Artikel.
Voraussetzungen: Zugänge, Daten, Organisation
Sie brauchen einen Admin-Zugang zu Zendesk, einen Dienst, der von Zendesk per HTTPS erreichbar ist, ein Sprachmodell und ein Help Center, das den aktuellen Stand Ihrer Produkte abbildet. Organisatorisch braucht es eine Person, die Vorschläge bewertet und Wissenslücken schließt.
Zugang zur API. Zendesk empfiehlt laut Sicherheitsdokumentation OAuth-Zugriffstoken als Bearer-Token. API-Tokens führt die Dokumentation unter „deprecated“ und warnt, dass sich mit ihnen jeder Benutzer des Kontos, auch Admins, darstellen lässt. Für einen neuen Agenten ist OAuth daher der saubere Weg.
Rate Limits. Die Grenzen hängen vom Plan ab: 200 Anfragen pro Minute bei Team, 400 bei Professional, 700 bei Enterprise. Für Ticket-Updates gelten zusätzlich 30 Updates pro 10 Minuten je Benutzer und Ticket sowie 100 Anfragen pro Minute für das ganze Konto. Bei Überschreitung antwortet die API mit 429 und einem Retry-After-Header, den Ihr Dienst auswerten muss.
Wissensbasis. Ein Agent ist nur so gut wie die Artikel, die er findet. Veraltete oder widersprüchliche Help-Center-Artikel landen sonst als Vorschlag im Ticket. Planen Sie vor dem Start eine Durchsicht ein.
Datenschutz. Tickets enthalten personenbezogene Daten. Klären Sie, wo das Modell läuft, welche Felder es sieht und wie lange Daten gespeichert werden. Mit einem Modell im eigenen Betrieb oder bei einem europäischen Anbieter ist ein solcher Agent datenschutzkonform betreibbar; die Optionen beschreibt die Seite zu souveräner KI. Das ist eine Orientierung, keine Rechtsberatung.
Vorgehen in Schritten
Ein belastbarer Weg führt in sechs Schritten von der Idee zum Betrieb. Er beginnt bewusst mit lesenden Zugriffen und internen Notizen und erweitert die Rechte erst, wenn Messwerte aus dem eigenen Ticketbestand das rechtfertigen.
- Ziel und Ticketart wählen. Eine klar umrissene Gruppe, zum Beispiel Anfragen zu Lieferstatus oder Dokumentation, statt aller Tickets.
- Wissen indizieren. Help-Center-Artikel über die API laden, in Abschnitte teilen und durchsuchbar ablegen; Updates über den inkrementellen Endpunkt nachziehen.
- Webhook und Trigger anlegen. Webhook mit Verbindungstyp Trigger, Trigger mit enger Bedingung und Ausschluss über ein Tag, Payload nur mit Ticket-ID.
- Signatur prüfen. Jede eingehende Anfrage verifizieren, bevor der Agent arbeitet (Code unten).
- Notizen schreiben und auswerten. Wochenweise auswerten, wie oft Vorschläge übernommen, geändert oder verworfen wurden.
- Rechte schrittweise erweitern. Erst Tags und Felder, öffentliche Antworten nur für eng begrenzte Fälle und nur, wenn die Auswertung das trägt.
Die Signaturprüfung folgt der Zendesk-Anleitung: HMAC-SHA256 über Zeitstempel plus unveränderten Request-Body, Base64-kodiert, verglichen mit dem Header X-Zendesk-Webhook-Signature. Der Zeitstempel kommt aus X-Zendesk-Webhook-Signature-Timestamp. Das Beispiel nutzt nur die Standardbibliothek von Python 3.12:
import base64
import hashlib
import hmac
import os
SECRET = os.environ["ZENDESK_WEBHOOK_SECRET"].encode()
def signatur_gueltig(raw_body: bytes, timestamp: str, signature: str) -> bool:
# Zendesk signiert Zeitstempel + unveränderten Body
nachricht = timestamp.encode() + raw_body
digest = hmac.new(SECRET, nachricht, hashlib.sha256).digest()
erwartet = base64.b64encode(digest).decode()
# Vergleich in konstanter Zeit
return hmac.compare_digest(erwartet, signature)
Wichtig ist der unveränderte Body: Wer das JSON vor der Prüfung parst und neu serialisiert, bekommt eine andere Byte-Folge und damit eine falsche Signatur. Solange der Webhook noch nicht angelegt ist, nennt die Dokumentation ein statisches Test-Secret; danach gilt das eigene Secret aus dem Admin Center.
Grenzen und Risiken
Die größten Risiken liegen nicht im Modell, sondern im Zusammenspiel mit Zendesk-Regeln: Schleifen zwischen Trigger und Agent, verlorene Webhook-Aufrufe, still abgeschnittene Texte und zu weit gefasste Rechte. Alle vier lassen sich mit einfachen Mitteln abfangen.
- Trigger-Schleifen. Schreibt der Agent ins Ticket, ist das wieder ein Ticket-Update, und Trigger laufen erneut. Ohne Ausschlussbedingung ruft der Trigger den Agenten immer wieder. Abhilfe: Der Agent setzt ein Tag wie
ki_vorschlag, und der Trigger enthält die Bedingung „Tags enthalten nicht ki_vorschlag“. - Keine Zustellgarantie. Zendesk wiederholt fehlgeschlagene Aufrufe laut Hilfe-Artikel bis zu dreimal bei bestimmten Fehlercodes; die Reihenfolge ist nicht garantiert, Verzögerungen sind möglich. Ein regelmäßiger Abgleich über die API fängt verpasste Tickets ab, und der Dienst muss doppelte Aufrufe für dasselbe Ticket vertragen.
- Abgeschnittene Kommentare. Über 64 kB schneidet Zendesk ohne Fehler ab. Lange Zusammenfassungen gehören gekürzt oder als Link auf ein internes System.
- Zu viel Vertrauen. Ein flüssig formulierter Entwurf wirkt richtig, auch wenn er auf einem veralteten Artikel beruht. Quellenangaben in jeder Notiz machen das prüfbar.
- Rechte. Ein API-Zugang mit Admin-Rechten kann alles ändern. Geben Sie dem technischen Benutzer nur die Rechte, die die gewählte Variante braucht.
Nicht passend ist ein eigener Agent, wenn Ihr Wissen vollständig im Help Center liegt, Sie kein eigenes Modell betreiben wollen und niemand den Dienst dauerhaft betreut. Dann ist die Zendesk-eigene Lösung meist der kürzere Weg.
Wie fange ich an?
Beginnen Sie mit einer Ticketart, einem lesenden Zugang und internen Notizen. Nach einigen Wochen zeigt die Übernahmequote aus Ihrem eigenen Ticketbestand, ob sich der Ausbau lohnt und welche Wissenslücken zuerst zu schließen sind.
Ein sinnvoller erster Schritt ist eine Bestandsaufnahme: Welche Ticketarten kommen am häufigsten, wie viele davon lassen sich mit vorhandenen Help-Center-Artikeln beantworten, und welche Systeme außerhalb von Zendesk müsste der Agent kennen? Daraus ergibt sich der Zuschnitt des ersten Agenten. Wie wir solche Agenten aufbauen und in bestehende Systeme einbetten, beschreibt die Übersicht zu KI-Agenten; die fachliche Seite des Kundenservice behandelt der Artikel zum Kundenservice-Agenten.
Häufige Fragen
Braucht man für einen eigenen Agenten eine Zendesk-App aus dem Marketplace?
Nein. Für den Einstieg genügen ein Webhook, ein Trigger und ein OAuth-Zugang zur API. Eine App in der Agentenoberfläche lohnt sich erst, wenn Agenten Vorschläge direkt in der Seitenleiste annehmen oder verwerfen sollen.
Kann der KI-Agent Makros selbst ausführen?
Die Makro-Endpunkte der API liefern nur eine Vorschau der Änderungen. Der Agent muss das Ergebnis anschließend selbst per Ticket-Update schreiben, was gleichzeitig eine gute Stelle für eine Prüfung ist.
Woran erkennt man im Ticket, dass eine Notiz vom Agenten stammt?
Am saubersten über einen eigenen technischen Benutzer als Autor und ein festes Tag pro Aktion. Damit lassen sich Ansichten, Berichte und Trigger gezielt filtern.
Was passiert, wenn der Agent-Dienst ausfällt?
Zendesk wiederholt fehlgeschlagene Webhook-Aufrufe nur begrenzt. Tickets laufen dann ohne Vorschlag ganz normal weiter; ein nächtlicher Abgleich über die API kann verpasste Tickets nachholen.
Quellen
- Zendesk Developer Docs: Ticket Comments developer.zendesk.com
- Zendesk Developer Docs: Webhooks API developer.zendesk.com
- Zendesk Developer Docs: Verifying webhook authenticity developer.zendesk.com
- Zendesk Help: Creating webhooks to interact with third-party systems support.zendesk.com
- Zendesk Developer Docs: Triggers developer.zendesk.com
- Zendesk Developer Docs: Actions reference developer.zendesk.com
- Zendesk Developer Docs: Tags developer.zendesk.com
- Zendesk Developer Docs: Macros developer.zendesk.com
- Zendesk Developer Docs: Help Center Articles developer.zendesk.com
- Zendesk Developer Docs: Rate limits developer.zendesk.com
- Zendesk Developer Docs: Security and authentication developer.zendesk.com
- Zendesk: AI Agents zendesk.de