Ticket-Exporte - Chatarmin CX Docs

Mit der Public API von Chatarmin CX lädst du viele Tickets samt Nachrichten auf einmal. Du startest einen Export mit einer Anfrage, fragst den Status ab, bis er fertig ist, und lädst das Ergebnis über einen zeitlich begrenzten Link herunter. Du musst Nachrichten nicht mehr Ticket für Ticket lesen.

So funktioniert es

POST /public/v1/ticket-exports legt den Export an und gibt ihn sofort mit Status queued zurück.
Der Export läuft im Hintergrund und umfasst so viele Tickets, wie du wählst, bis zu 50.000.
GET /public/v1/ticket-exports/{exportId} liefert den Status. Bei completed enthält die Antwort auch eine download_url.
Du lädst die Datei über download_url herunter.

Beide Endpoints brauchen den Scope tickets:export. Erstelle einen Schlüssel unter Einstellungen → API. Ein mit einem Agenten verknüpfter Schlüssel exportiert nur gespeicherte Ansichten, die dieser Agent im Posteingang sieht, wie bei GET /views. Ein Schlüssel ohne verknüpften Agenten kann jede Ansicht der Organisation exportieren.

Nächtlicher Sync

Exportiere einmal pro Nacht die Tickets einer gespeicherten Ansicht samt Nachrichten.

Ansicht finden

Rufe GET /public/v1/views auf und merke dir die id der Ansicht mit den Tickets, die du synchronisierst. Siehe Filtern und gespeicherte Ansichten.

Export anlegen

curl -X POST 'https://api.armin.cx/public/v1/ticket-exports' \
  -H "cx-api-key: $CX_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "view_id": "00000000-0000-4000-8000-0000000000a1", "include_messages": true }'

Die Antwort hat Status 202 und enthält den Export mit Status queued.

Warten, bis er fertig ist

curl "https://api.armin.cx/public/v1/ticket-exports/$EXPORT_ID" \
  -H "cx-api-key: $CX_API_KEY"

Es gibt keine Webhooks. Frage alle paar Sekunden ab, bis status completed oder failed ist.

Datei herunterladen

Lade data.download_url herunter und entpacke die Datei. Jede Statusabfrage eines abgeschlossenen Exports liefert einen neuen Link. Frage den Status also erneut ab, wenn ein Link abgelaufen ist.

Backfill

Exportiere alle Tickets, die in einem Zeitraum erstellt wurden. Datumsangaben haben das Format YYYY-MM-DD in UTC, beide Tage sind eingeschlossen, und es wird nach dem Erstellungsdatum des Tickets gefiltert.

curl -X POST 'https://api.armin.cx/public/v1/ticket-exports' \
  -H "cx-api-key: $CX_API_KEY" \
  -H 'content-type: application/json' \
  -d '{ "date_from": "2026-08-01", "date_to": "2026-08-14", "include_messages": true }'

Ein Export enthält höchstens 50.000 Tickets. Trifft ein Zeitraum auf mehr, schlägt die Anfrage mit EXPORT_TOO_LARGE fehl. Teile den Zeitraum in kleinere Zeiträume und lege pro Zeitraum einen Export an.

Request-Felder

Wähle genau einen der drei Auswahlmodi. Unbekannte Felder werden mit 400 VALIDATION_ERROR abgelehnt.

Feld	Verhalten
`view_id`	UUID einer gespeicherten Ansicht. Exportiert alle Tickets der Ansicht.
`ticket_ids`	1 bis 500 Ticket-UUIDs. Existiert eine ID in deiner Organisation nicht, schlägt die Anfrage mit `400 VALIDATION_ERROR` fehl und listet sie in `details.invalid_ticket_ids`.
`date_from`, `date_to`	Nur zusammen, `YYYY-MM-DD`, UTC, einschließlich, `date_from` am oder vor `date_to`.
`include_messages`	Boolean, standardmäßig `false`. Fügt `messages.csv` hinzu.
`columns`	Optionale Liste von Ticket-Spalten für `tickets.csv`. Standardmäßig die Standardspalten.

Standardspalten: ticket_number, subject, contact_first_name, contact_last_name, contact_email, contact_phone, status, assigned_agent_name, created_at, updated_at. Optionale Spalten: priority, channel, channel_name, tags, last_message_at, message_count, ticket_url, csat_score, csat_comment, csat_survey_sent, csat_submitted_at, created_date, created_time, language, social_thread_type, social_post_type, team_name, first_resolved_at, resolved_at.

Export lesen

{
  "success": true,
  "data": {
    "id": "01a1adf2-20b3-72db-a67c-b1fc3cb46be2",
    "status": "completed",
    "created_at": "2026-11-05T23:01:28.884Z",
    "completed_at": "2026-11-05T23:01:38.519Z",
    "expires_at": "2026-11-12T23:01:38.515Z",
    "ticket_count": 144,
    "download_url": "https://…",
    "error": null
  }
}

Feld	Bedeutung
`id`	Export-ID. Nutze sie in `GET /ticket-exports/{exportId}`.
`status`	`queued`, `processing`, `completed`, `failed` oder `expired`.
`created_at`, `completed_at`	ISO-8601-Zeitstempel. `completed_at` ist `null`, bis der Export fertig ist.
`expires_at`	Zeitpunkt, an dem die Datei gelöscht wird. `null`, bis der Export abgeschlossen ist.
`ticket_count`	Anzahl der Tickets in der Datei. `null`, bis der Export abgeschlossen ist.
`download_url`	Nur gesetzt, wenn `status` `completed` ist. 1 Stunde gültig.
`error`	Nur gesetzt, wenn `status` `failed` ist: `Export failed. Please create a new export.`

Status	Bedeutung
`queued`	Der Export wartet auf einen freien Worker.
`processing`	Die Datei wird erstellt.
`completed`	Die Datei ist fertig. Lade sie über `download_url` herunter.
`failed`	Der Export konnte nicht erstellt werden. Lege einen neuen Export an.
`expired`	Die Datei hat die Aufbewahrung von 7 Tagen überschritten und ist nicht mehr verfügbar. Lege einen neuen Export an.

Die Datei

Ist include_messages true, ist der Download ein ZIP mit tickets.csv und messages.csv. Sonst ist der Download eine einzelne tickets.csv. Die Dateien sind UTF-8 ohne Byte-Order-Mark. Trifft die Auswahl keine Tickets, wird der Export trotzdem abgeschlossen, mit Dateien, die nur die Kopfzeile enthalten. Tickets sind nach Erstellungsdatum sortiert, älteste zuerst. Nachrichten sind nach Ticket und dann nach Erstellungsdatum sortiert, älteste zuerst. Interne Notizen und gelöschte Nachrichten sind nicht enthalten. messages.csv hat diese Spalten:

Spalte	Wert
`ticket_id`, `ticket_number`	Das Ticket, zu dem die Nachricht gehört.
`created_at`	ISO-8601-Zeitstempel in UTC.
`direction`	`inbound` für Kundennachrichten, `outbound` für alle anderen.
`author_type`	`customer`, `agent` oder `ai`.
`author_name`	Name des Absenders.
`ai_agent_name`	Name des KI-Agenten bei `ai`-Nachrichten, sonst leer.
`body_text`	Die Nachricht als reiner Text, identisch zu `text` in `GET /tickets/:ticketNumber/messages`, ohne Längenlimit.
`message_id`	Nachrichten-ID.

Alle Zeitstempel in beiden Dateien sind ISO-8601 in UTC. Es gibt keine Zeitzonen-Option.

Limits

Limit	Wert
Tickets pro Export	50.000. Darüber schlägt die Anfrage mit `EXPORT_TOO_LARGE` fehl.
`ticket_ids` pro Anfrage	500
Aktive Exporte pro Organisation	2 (`queued` oder `processing`). Eine dritte Anfrage schlägt mit `EXPORT_LIMIT_REACHED` fehl.
Aufbewahrung der Datei	7 Tage. Danach ist der Status `expired`.
Download-Link	Bei jeder Statusabfrage ein neuer Link, 1 Stunde gültig.
Export anlegen	30 Requests/Minute
Status abfragen	120 Requests/Minute

Siehe Rate Limits.

Unterschiede zum Legacy-Export

POST /public/tickets/export bleibt verfügbar. Wenn du auf den v1-Export umsteigst, ändert sich Folgendes.

	Legacy-Export	v1-Export
Auslieferung	Die Datei ist die Antwort der Anfrage	Hintergrund-Job: anlegen, abfragen, herunterladen
Größter Export	500 Tickets	50.000 Tickets
Gelöschte Nachrichten	Enthalten	Nicht enthalten
`direction`	`in` / `out`	`inbound` / `outbound`
`author_type`	`customer` / `business` / `ai`	`customer` / `agent` / `ai`
Zeitstempel	`yyyy-MM-dd hh:mm:ss a zzz` in einer angegebenen Zeitzone	ISO-8601 UTC, keine Option `timezone`
`body_text`	Bereinigter Text	Derselbe reine Text wie `text` der v1-Nachricht, ohne Längenlimit
Keine Tickets gefunden	`404`	Wird mit Dateien abgeschlossen, die nur die Kopfzeile enthalten
Auswahl	`ticketIds` oder `date_from` und `date_to`	`ticket_ids`, `date_from` und `date_to` oder `view_id`
Formate	`csv`, `excel`, `eml`	Nur CSV

In v1 nicht unterstützt: excel, eml, order, timezone und include_ticket_fields. Die Spaltennamen in tickets.csv und messages.csv sind dieselben wie im Legacy-Export.

Fehler

Antwort	Wann
`400 VALIDATION_ERROR`	Nicht genau ein Auswahlmodus, unbekannte Felder oder Spalten, `date_from` nach `date_to` oder `ticket_ids`, die nicht existieren (`details.invalid_ticket_ids`).
`400 EXPORT_TOO_LARGE`	Die Auswahl trifft mehr als 50.000 Tickets (`details.max_tickets`). Teile den Zeitraum.
`403 FORBIDDEN_SCOPE`	Der Schlüssel hat `tickets:export` nicht.
`404 VIEW_NOT_FOUND`	Die Ansicht existiert nicht oder ist für den Agenten des Schlüssels nicht sichtbar.
`404 EXPORT_NOT_FOUND`	Der Export existiert in deiner Organisation nicht.
`429 EXPORT_LIMIT_REACHED`	Es laufen bereits zwei Exporte, oder ein weiterer Export wird gerade angelegt. Warte kurz und versuche es erneut.
`429 RATE_LIMIT_EXCEEDED`	Du hast zu viele Requests gesendet. Warte auf `Retry-After`.

Das Fehlerformat steht unter Fehler. Werte code aus, nicht message.

​So funktioniert es

​Nächtlicher Sync

​Backfill

​Request-Felder

​Export lesen

​Die Datei

​Limits

​Unterschiede zum Legacy-Export

​Fehler