Die Migration von Ticketdaten in Zendesk ist eine häufige Herausforderung für Teams, die Plattformen wechseln, Instanzen konsolidieren oder historische Datensätze importieren. Während Zendesk verschiedene Importmethoden anbietet, ist die Ticket Import API die einzige Option, die historische Zeitstempel beibehält und große Datensätze korrekt verarbeitet.
Diese Anleitung führt Sie durch den kompletten Prozess des Massenimports von Tickets mithilfe der Zendesk API. Sie erfahren, wie Sie Ihre Daten strukturieren, Sonderfälle behandeln und die Fallstricke vermeiden, die ein Wochenendprojekt in ein mehrwöchiges Kopfzerbrechen verwandeln können.
Was Sie benötigen
Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes eingerichtet haben:
- Zendesk-Administratorzugriff – nur Administratoren können die Import-API verwenden
- API-Token – die Kennwortauthentifizierung allein funktioniert nicht; Sie benötigen ein gültiges API-Token aus Ihren Zendesk-Administratoreinstellungen
- Vorhandene Benutzer – Anfragende müssen bereits in Zendesk vorhanden sein, bevor Sie ihre Tickets importieren
- JSON-Kenntnisse – Sie arbeiten mit REST-API-Anfragen und JSON-Nutzdaten
- Skriptumgebung – Python oder Node.js erleichtern die Batch-Verarbeitung erheblich
Wenn Sie nach einer einfacheren Möglichkeit suchen, Support-Workflows ohne komplexe Migrationen zu verwalten, können moderne KI-Lösungen wie eesel AI direkt in Ihre bestehende Einrichtung integriert werden.
Die Zendesk API-Endpunkt für den Massenimport von Tickets verstehen
Die Ticket Import API unterscheidet sich in einigen wichtigen Punkten von der Standard-Tickets-API. Hier ist, was Sie wissen müssen.
Wichtige Endpunktunterschiede
Der Import-Endpunkt ist POST /api/v2/imports/tickets (oder /api/v2/imports/tickets/create_many für Batches mit bis zu 100 Tickets). Im Gegensatz zur Standard-API zur Ticketerstellung bietet der Import-Endpunkt:
- Beibehaltung historischer Zeitstempel, einschließlich
created_at,updated_atundsolved_at - Unterstützung des Parameters
archive_immediatelyfür geschlossene Tickets - Keine Auslösung von Geschäftsregeln oder Automatisierungen beim Import
- Keine Benachrichtigungen an CC-Benutzer
- Möglichkeit, benutzerdefinierte Kommentarzeitstempel festzulegen
Quelle: Zendesk Ticket Import API-Dokumentation
Ratenbegrenzungen und Batch-Größen
Zendesk erlaubt bis zu 100 Tickets pro Massenimportanfrage. Für größere Datensätze müssen Sie eine Batching-Logik in Ihrem Skript implementieren. Es gelten die Standard-API-Ratenbegrenzungen (700 Anfragen pro Minute für die meisten Pläne), planen Sie Ihre Migration entsprechend.
Authentifizierungsanforderungen
Alle Importanfragen erfordern eine Basic Authentication mit Ihrer E-Mail-Adresse in Kombination mit einem API-Token (nicht Ihrem Passwort). Das Format ist {email_address}/token:{api_token}, codiert in Base64.
Schritt 1: Bereiten Sie Ihre Daten vor
Die Datenvorbereitung ist der Punkt, an dem die meisten Migrationen gelingen oder scheitern. Nehmen Sie sich Zeit, um dies richtig zu machen.
Erforderliche und optionale Felder
Jedes Ticket benötigt mindestens eine requester_id und einen subject. Hier ist ein vollständiges Beispiel:
{
"ticket": {
"requester_id": 827,
"subject": "Hilfe beim Kontozugriff",
"description": "Erste Ticketbeschreibung",
"assignee_id": 19,
"tags": ["migration", "account-issue"],
"created_at": "2023-06-25T10:15:18Z",
"comments": [
{
"author_id": 827,
"created_at": "2023-06-25T10:15:18Z",
"value": "Ich kann mich nicht in mein Konto einloggen"
}
]
}
}
Benutzer-Voraussetzungen
Der Anfragende und alle Kommentatoren müssen bereits als aktive Benutzer in Zendesk vorhanden sein. Die API lehnt Tickets mit gesperrten oder nicht existierenden Anfragenden ab. Importieren Sie Ihre Benutzer zuerst entweder mit dem Massen-CSV-Import (bis zu 2.000 Zeilen) oder der Users API.
Anhänge verarbeiten
Anhänge erfordern einen zweistufigen Prozess:
- Laden Sie Dateien mit dem Anhänge-Endpunkt in Zendesk hoch, um Upload-Token zu erhalten
- Fügen Sie diese Token in Ihre Ticket-Import-Nutzlast ein
Beachten Sie bei Inline-Bildern (Screenshots in Kommentaren), dass die API-Dokumentation diese nicht vollständig abdeckt. Migrationen in der Praxis zeigen, dass Inline-Anhänge anders behandelt werden als Standard-Anhänge.
Schritt 2: Strukturieren Sie Ihre API-Anfrage
Nachdem Ihre Daten vorbereitet sind, können Sie mit dem Aufbau der eigentlichen API-Anfragen beginnen.
Grundlegende Anfragestruktur
Hier ist ein Python-Beispiel, das zeigt, wie eine grundlegende Importanfrage strukturiert wird:
import requests
import base64
email = 'your-email@example.com'
api_token = 'your_api_token_here'
auth_string = base64.b64encode(f"{email}/token:{api_token}".encode()).decode()
headers = {
'Content-Type': 'application/json',
'Authorization': f'Basic {auth_string}'
}
ticket_data = {
"ticket": {
"requester_id": 827,
"subject": "Hilfe",
"description": "Eine Beschreibung",
"created_at": "2023-06-25T10:15:18Z",
"comments": [
{
"author_id": 827,
"created_at": "2023-06-25T10:15:18Z",
"value": "Dies ist ein Kommentar"
}
]
}
}
response = requests.post(
'https://your-subdomain.zendesk.com/api/v2/imports/tickets',
headers=headers,
json=ticket_data
)
Historische Kommentare einbeziehen
Das Kommentare-Array unterstützt mehrere Einträge mit individuellen Zeitstempeln. Dies ist entscheidend, um den vollständigen Konversationsverlauf aus Ihrem Quellsystem beizubehalten.
Benutzerdefinierte Felder und Tags
Ordnen Sie die benutzerdefinierten Felder Ihres Quellsystems den benutzerdefinierten Feldern von Zendesk mithilfe des Arrays custom_fields mit id- und value-Paaren zu. Tags können als einfaches Zeichenfolgen-Array übergeben werden.
Schritt 3: Behandeln Sie Sonderfälle
Migrationen in der Praxis beinhalten immer Sonderfälle. Hier erfahren Sie, wie Sie mit den häufigsten Fällen umgehen.
Geschlossene Tickets importieren
Verwenden Sie für Tickets mit dem Status "geschlossen" den Abfrageparameter archive_immediately:
POST /api/v2/imports/tickets?archive_immediately=true
Dies umgeht den normalen Ticket-Lebenszyklus und erstellt Tickets direkt in Ihrem Archiv. Zendesk empfiehlt diesen Ansatz, wenn Sie 750.000 oder mehr historische Tickets importieren, um die Leistung Ihrer aktiven Ticketwarteschlange nicht zu beeinträchtigen.
Große Datensätze verwalten
Implementieren Sie für große Migrationen diese Praktiken:
- Verarbeiten Sie Tickets in Batches von 100 (dem API-Maximum)
- Protokollieren Sie die Ergebnisse jedes Batches zur Fehlerverfolgung
- Erstellen Sie eine Wiederholungslogik für fehlgeschlagene Anfragen
- Erwägen Sie, Importe außerhalb der Stoßzeiten durchzuführen
Mit gesperrten Benutzern umgehen
Die API erfordert, dass Anfragende aktive Benutzer sind. Wenn Ihre Quelldaten Tickets von gesperrten oder gelöschten Benutzern enthalten, haben Sie zwei Möglichkeiten:
- Reaktivieren Sie die Benutzer vor dem Import
- Ordnen Sie gelöschte Benutzer einem Platzhalterkonto "ehemaliger Mitarbeiter" zu
Ein Migrationsteam hat dies auf die harte Tour herausgefunden: "Die API streikt, wenn Anfragende und Absender gesperrt sind. Wir mussten ehemalige Mitarbeiter während des Importvorgangs vorübergehend reaktivieren."
Quelle: Zendesk Community Migration Experience
Leere Kommentarfelder
Die API lehnt Kommentare mit leeren Feldern ab, obwohl die Zendesk-Benutzeroberfläche dies zulässt (z. B. wenn jemand einen Anhang ohne Text per E-Mail sendet). Sie müssen für diese Fälle einen Platzhaltertext wie "(Kein Kommentartext)" hinzufügen.
Schritt 4: Ausführen und validieren
Nachdem Ihre Daten vorbereitet und Sonderfälle behandelt wurden, ist es an der Zeit, den Import auszuführen.
Anfragen in Batches senden
Durchlaufen Sie Ihre Ticketdaten in Blöcken von 100 und senden Sie jeden Batch an den Massenimport-Endpunkt. Protokollieren Sie die Antwort von jedem Batch, einschließlich aller Ticket-IDs, die erfolgreich erstellt wurden.
Fehlerbehandlung
Häufige HTTP-Statuscodes, auf die Sie stoßen werden:
- 200 OK – Ticket erfolgreich erstellt
- 422 Unprocessable Entity – Validierungsfehler (überprüfen Sie Ihre JSON-Struktur)
- 429 Too Many Requests – Ratenbegrenzung erreicht; implementieren Sie exponentielles Backoff
- 401 Unauthorized – Authentifizierungsproblem; überprüfen Sie Ihr API-Token
Verifizierungsstrategien
Überprüfen Sie nach dem Import den Erfolg durch:
- Überprüfen, ob die Ticketanzahl mit Ihren Quelldaten übereinstimmt
- Stichprobenartige Überprüfung von Tickets, um zu überprüfen, ob Zeitstempel und Kommentare korrekt importiert wurden
- Bestätigen, dass Anhänge zugänglich sind
- Testen, ob Tags und benutzerdefinierte Felder korrekt angezeigt werden
Häufige Fallstricke und wie man sie vermeidet
Aus den Fehlern anderer zu lernen, kann Ihnen viel Zeit sparen. Hier sind die größten Probleme, auf die Migrationsteams stoßen.
Anfragende müssen aktiv sein
Wie bereits erwähnt, verursachen gesperrte Benutzer Importfehler. Reaktivieren Sie sie zuerst oder verwenden Sie Platzhalterkonten.
Die Importreihenfolge ist wichtig
Sie müssen in dieser Reihenfolge importieren:
- Organisationen (falls verwendet)
- Benutzer
- Tickets
Tickets referenzieren Benutzer und Organisationen anhand der ID, daher müssen diese Datensätze zuerst vorhanden sein.
Metriken und SLAs werden nicht berechnet
Zendesk-Metriken und SLAs werden für importierte Tickets nicht berechnet. Wenn Sie Berichte über historische Daten benötigen, sollten Sie ein Tag wie "importiert" hinzufügen, um diese Tickets von den aktuellen Metriken auszuschließen.
Keine Ticket-ID-Reservierung
Sie können Ticket-ID-Beziehungen aus Ihrem Quellsystem nicht beibehalten. Zusammengeführte Tickets und Querverweise müssen manuell oder über externe Zuordnungstabellen behandelt werden.
Nebenkonversationen werden nicht unterstützt
Wenn Ihr Quellsystem Nebenkonversationen oder kollaborative Threads enthält, können diese nicht über die API importiert werden. Konvertieren Sie sie in interne Kommentare oder akzeptieren Sie, dass diese Daten nicht übertragen werden.
JSON-Parsing-Eigenheiten
Ein Migrationsteam, das PowerShell verwendete, stieß auf unerwartete JSON-Parsing-Probleme: "Zendesk hat sich beschwert, dass es das JSON nicht parsen kann. Das von mir generierte JSON war syntaktisch korrekt, aber ich habe das PowerShell-Objekt direkt übergeben. Das Speichern des JSON zuerst in einer Datei und das anschließende Übertragen an Zendesk funktionierte problemlos."
Quelle: Zendesk Community Migration Experience
Alternative Ansätze: eesel AI und andere Optionen
Manchmal ist die API nicht die richtige Wahl. Erwägen Sie diese Alternativen.
Wann stattdessen ein CSV-Import verwendet werden sollte
Der Zendesk-Massen-CSV-Import funktioniert für Benutzer und Organisationen (nicht für Tickets) und verarbeitet bis zu 2.000 Zeilen pro Datei. Er ist einfacher als die API, hat aber erhebliche Einschränkungen: kein Zeitzonenimport, keine Fotos, keine Spracheinstellungen und keine Ticketunterstützung.
Migrationsdienste von Drittanbietern
Für komplexe Migrationen können professionelle Dienste wie zendesk-import.com oder die Zenplates Import App die technische Komplexität bewältigen. Diese Dienste berechnen in der Regel auf der Grundlage des Datenvolumens, sparen aber erhebliche Entwicklungszeit.
Moderne KI-gestützte Alternativen
Wenn Sie migrieren, weil Ihr aktueller Helpdesk Ihre Anforderungen nicht erfüllt, sollten Sie überlegen, ob eine moderne KI-Lösung besser geeignet ist als eine herkömmliche Plattformmigration. eesel AI lässt sich in Zendesk integrieren, um KI-gestützte Ticketbearbeitung, automatisierte Antworten und intelligentes Routing hinzuzufügen, ohne dass ein vollständiger Plattformwechsel erforderlich ist.
Beginnen Sie mit dem Aufbau besserer Support-Workflows
Der Massenimport von Tickets über die Zendesk API gibt Ihnen die präzise Kontrolle über die Migration historischer Daten, erfordert aber sorgfältige Planung und Aufmerksamkeit für Sonderfälle. Die wichtigsten Schritte sind einfach: Bereiten Sie Ihre Daten gründlich vor, behandeln Sie gesperrte Benutzer, verarbeiten Sie sie in Batches und überprüfen Sie anschließend alles.
Wenn Sie eine Migration in Erwägung ziehen, weil Ihre aktuellen Support-Tools nicht mit Ihren Anforderungen Schritt halten, erfahren Sie, wie die Zendesk-Integration von eesel AI Ihre bestehende Einrichtung mit KI-gestützten Funktionen verbessern kann. Oder wenn Sie völlig neue Ansätze für den Kundensupport evaluieren, lesen Sie die Preisgestaltung von eesel AI, um zu sehen, wie moderne KI-Lösungen im Vergleich zu herkömmlichen Plattformmigrationen abschneiden.
Häufig gestellte Fragen
Diesen Beitrag teilen
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
