Ticket erstellen - Chatarmin CX Docs

Lege Tickets programmatisch an — aus CRM, Bestellsystem, eigenem Backend oder Automatisierung (Zapier, Make, Webhooks). Braucht den Scope tickets:write. Rate Limit: 30 Requests / Minute (siehe Rate Limits).

Für neue Integrationen nicht Legacy POST https://api.armin.cx/public/tickets nutzen. v1 bevorzugen; Abschaltdatum siehe Migration von Legacy (2026-10-31).

Voraussetzungen

API-Schlüssel mit tickets:read und tickets:write — unter Einstellungen → API anlegen oder erweitern.
Verbundener Kanal — der Wert channel muss zu einem in eurem Workspace verbundenen Kanaltyp passen (z. B. email oder widget). Bei mehreren Kanälen desselben Typs: channel_identifier für eine konkrete Posteingangs-Adresse setzen.
HTTP-Client — curl, Postman oder ein Server mit JSON-POST.

Request


Methode	`POST`
URL	`https://api.armin.cx/public/v1/tickets`
Header	`cx-api-key: DEIN_API_SCHLÜSSEL`, `Content-Type: application/json`

Nur die unten aufgeführten Felder senden. Zusätzliche Felder im JSON-Body führen zu einem Fehler.

Request-Body

Pflichtfeld

Feld	Typ	Beschreibung
`channel`	string	Primärer Posteingangskanal. Einer von: `email`, `widget`, `whatsapp`, `voice`, `instagram`, `facebook`, `tiktok`, `youtube`, `contact_form`. Der Kanaltyp muss im Workspace verbunden sein.

Optional — Ticket

Feld	Typ	Default	Beschreibung
`subject`	string	—	Betreff (max. 500 Zeichen).
`note`	string	—	Interne Notiz (max. 10.000 Zeichen). Wird genutzt, wenn `messages` fehlt oder leer ist.
`tags`	string[]	—	Tag-Namen (max. 20 Tags, je 100 Zeichen). Tags werden angelegt, falls nötig, und am Ticket gesetzt.
`metadata`	object	—	Schlüssel/Wert für externe Referenzen (max. 50 Keys; String-Werte max. 2.000 Zeichen). z. B. Bestell-ID, Fallnummer — standardmäßig nicht kundensichtbar.
`channel_identifier`	string	—	Eindeutige Posteingangs-ID bei mehreren Kanälen desselben `channel`-Typs.
`priority`	string	`medium`	`none`, `urgent`, `high`, `medium`, `low`.
`status`	string	`open`	`open`, `need_more_info`, `resolved`, `closed`.
`language`	string	—	Ticket-Sprache (unterstützte Werte wie in der Posteingang-Sprachliste).
`is_spam`	boolean	`false`	Ticket als Spam markieren.
`ticket_type`	string	—	`regular` oder `side`.
`parent_ticket_id`	UUID	—	Side-Ticket an Eltern-Ticket koppeln.
`assignee_email`	string	—	Ticket per Agenten-E-Mail zuweisen.

Optional — Kontakt

Feld	Typ	Beschreibung
`contact.email`	string	Kunden-E-Mail. Bestehenden Kontakt matchen oder neu anlegen.
`contact.first_name`	string	Vorname.
`contact.last_name`	string	Nachname.
`contact.phone`	string	Telefonnummer.

Optional — Nachrichten

Statt (oder zusätzlich zu) note bis zu 10 Nachrichten in messages[]:

Feld	Typ	Beschreibung
`messages[].channel`	string	Kanal für diese Nachricht (gleiche Enum wie Ticket-`channel`).
`messages[].from_agent`	boolean	`false`, wenn nicht angegeben. Auf `true` setzen, damit die Nachricht als von deinem Unternehmen gesendet gilt statt vom Kunden. Bei Agent-Nachrichten ist `from` optional.
`messages[].body`	string	Klartext (max. 100.000 Zeichen).
`messages[].html_body`	string	HTML (max. 100.000 Zeichen).
`messages[].prefilled_input`	boolean	`false`, wenn nicht angegeben. Auf `true` setzen, damit `body` als KI-Antwortentwurf für den Agenten hinterlegt wird, statt als Nachricht im Verlauf. Nur eine Nachricht pro Anfrage darf dies setzen.
`messages[].from.email`	string	Absender-E-Mail. Optional, wenn `contact.email` gesetzt ist.
`messages[].from.first_name`	string	Absender-Vorname.
`messages[].from.last_name`	string	Absender-Nachname.
`messages[].from.phone`	string	Absender-Telefon.
`messages[].skip_email`	boolean	`false`, wenn nicht angegeben. Auf `true` setzen, damit die Nachricht gespeichert wird, ohne eine ausgehende Benachrichtigung (z. B. E-Mail) zu senden — etwa beim Nachtragen oder Importieren von Nachrichten, die bereits anderswo zugestellt wurden.
`messages[].metadata`	object	Metadaten pro Nachricht (gleiche Limits wie Ticket-`metadata`).
`messages[].attachment_ids`	UUID[]	IDs von Anhängen, bestätigt über den Anhänge-Ablauf unten (max. 10 pro Nachricht). Bei `prefilled_input`-Nachrichten nicht unterstützt.

Für typische Integrationen reichen note + contact + metadata. messages nutzen, wenn beim Anlegen eine sichtbare Kundennachricht im Thread stehen soll.

Anhänge

Eine Datei in drei Aufrufen an eine Nachricht anhängen: Upload-URL anfordern, Datei hochladen, dann bestätigen — erst danach beim Ticket referenzierbar.

POST /public/v1/attachments/upload-url mit Dateiname, MIME-Type und Größe. Liefert id und eine signierte upload_url (30 Minuten gültig).
Die rohen Dateibytes per PUT an upload_url senden — direkt an den Speicher, nicht über diese API.
POST /public/v1/attachments/{id}/confirm. Prüft die Datei gegen das Größenlimit und den tatsächlichen Inhalt — nicht nur den in Schritt 1 angegebenen MIME-Type.
Die bestätigte id beim Ticket-Anlegen in messages[].attachment_ids übergeben.

Limit	Wert
Max. Dateigröße	20 MB
Max. Anhänge pro Nachricht	10
Erlaubte Typen	Bilder, PDF, Klartext, CSV, Word (`.docx`), Excel (`.xlsx`), MP4, MP3

# 1. Upload-URL anfordern
curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/attachments/upload-url" \
  -d '{
    "file_name": "rechnung.pdf",
    "mime_type": "application/pdf",
    "size": 20480
  }'
# -> { "data": { "id": "...", "upload_url": "...", "public_url": "...", "expires_at": "..." } }

# 2. Datei direkt an die zurückgegebene upload_url hochladen
curl -sS -X PUT "UPLOAD_URL_AUS_SCHRITT_1" \
  -H "Content-Type: application/pdf" \
  --data-binary @rechnung.pdf

# 3. Upload bestätigen
curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  "https://api.armin.cx/public/v1/attachments/ANHANG_ID/confirm"

# 4. Ticket anlegen und den bestätigten Anhang referenzieren
curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets" \
  -d '{
    "channel": "email",
    "messages": [
      {
        "channel": "email",
        "from_agent": true,
        "body": "Hier ist deine Rechnung.",
        "attachment_ids": ["ANHANG_ID"]
      }
    ]
  }'

Minimales Beispiel

Nur interne Notiz — kein Kontakt nötig:

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets" \
  -d '{
    "channel": "email",
    "subject": "Nachverfolgung erforderlich",
    "note": "Aus Bestellüberwachung — Kunde ohne Telefonnummer."
  }'

Vollständiges Beispiel

Kontakt, Tags und externe Referenz in metadata:

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets" \
  -d '{
    "channel": "email",
    "subject": "Telefonnummer fehlt — Bestellung #1042",
    "contact": {
      "email": "kunde@beispiel.de",
      "first_name": "Alex",
      "last_name": "Beispiel"
    },
    "note": "Bestellung #1042: Versandart erfordert Telefonnummer, keine angegeben.\nKunde: Alex Beispiel\nBitte Rückrufnummer vor Versand einholen.",
    "tags": ["telefon-fehlt", "express-versand"],
    "metadata": {
      "external_order_id": "5678901234",
      "external_order_name": "#1042",
      "source": "order-automation"
    }
  }'

metadata-Keys an euer System anpassen — die API speichert sie als Integrationsfelder.

Automatisierung und Webhooks

Viele Teams rufen den Endpoint aus HTTP-Request-Aktionen auf (eigene Skripte, Zapier, Make, n8n, E-Commerce-Workflows):

Trigger, wenn eure Geschäftsregel greift (Tag gesetzt, Feld fehlt, Statuswechsel).
POST auf https://api.armin.cx/public/v1/tickets mit Variablen eurer Plattform in subject, note, contact, metadata.
Externe Bestell- oder Fall-ID in metadata mappen, damit Agenten die Quelle sehen.

Trigger so bauen, dass sie nur bei der Bedingung feuern, nicht bei jedem Update.

Jeder erfolgreiche Request erstellt ein neues Ticket. Automatisierung nur auslösen, wenn wirklich ein Ticket entstehen soll (z. B. wenn ein Tag gesetzt wird), nicht bei jedem Update desselben Datensatzes.

Antwort

201 Created — v1-Erfolgs-Envelope:

{
  "success": true,
  "data": {
    "id": "019b0000-0000-7000-8000-000000000001",
    "ticket_number": 1042,
    "subject": "Telefonnummer fehlt — Bestellung #1042",
    "status": "open",
    "priority": "medium",
    "channel": "email",
    "created_at": "2026-08-25T10:00:00.000Z",
    "updated_at": "2026-08-25T10:00:00.000Z",
    "tags": ["telefon-fehlt", "express-versand"]
  }
}

data.id (UUID) oder data.ticket_number (Posteingangsnummer) für spätere GET-Requests speichern.

Fehler

Situation	HTTP	Code
Fehlender/ungültiger API-Schlüssel	401	`API_KEY_REQUIRED`, `INVALID_API_KEY`
Scope `tickets:write` fehlt	403	`FORBIDDEN_SCOPE`
Ungültiger Body, unbekanntes Feld, `channel` fehlt	400	`VALIDATION_ERROR`
Kein verbundener Kanal für `channel` / `channel_identifier`	400	`VALIDATION_ERROR`
Anhang nicht gefunden, nicht bestätigt oder schon einer anderen Nachricht zugeordnet	404 oder 400	`ATTACHMENT_NOT_FOUND`, `VALIDATION_ERROR`
Rate Limit überschritten	429	`RATE_LIMIT_EXCEEDED`

Vollständige Liste: Fehler.

Zuerst testen

Unter Einstellungen → API einen Schlüssel mit tickets:write anlegen.
Einen Test-Request mit den Beispielen oben senden. Test-subject oder Tag setzen (z. B. api-test), damit euer Team das Ticket im Posteingang erkennt.
Prüfen, ob das Ticket mit dem erwarteten Kanal, Kontakt, Tags und metadata ankommt.

Test-Schlüssel danach widerrufen.

Weiterführend

OpenAPI-Referenz

Interaktives Schema und Try it für POST /tickets.

Authentifizierung

Scopes, Rotation, Least Privilege.

Rate Limits

Write-Stufe (30/min) und Backoff bei 429.

Migration von Legacy

Legacy POST /public/tickets auf v1 mappen.

​Voraussetzungen

​Request

​Request-Body

​Pflichtfeld

​Optional — Ticket

​Optional — Kontakt

​Optional — Nachrichten

​Anhänge

​Minimales Beispiel

​Vollständiges Beispiel

​Automatisierung und Webhooks

​Antwort

​Fehler

​Zuerst testen

​Weiterführend

OpenAPI-Referenz

Authentifizierung

Rate Limits

Migration von Legacy

Voraussetzungen

Request

Request-Body

Pflichtfeld

Optional — Ticket

Optional — Kontakt

Optional — Nachrichten

Anhänge

Minimales Beispiel

Vollständiges Beispiel

Automatisierung und Webhooks

Antwort

Fehler

Zuerst testen

Weiterführend