Nachricht senden - Chatarmin CX Docs

Fügt einem bestehenden Ticket eine Nachricht hinzu — eine kundensichtbare Antwort oder eine interne Notiz. Braucht den Scope tickets:write. Rate Limit: 30 Requests / Minute (siehe Rate Limits).

Voraussetzungen

API-Schlüssel mit tickets:write — unter Einstellungen → API anlegen oder erweitern.
Ein bestehendes Ticket — ticket_number aus Ticket erstellen oder GET /public/v1/tickets.
HTTP-Client — curl, Postman oder ein Server mit JSON-POST.

Request


Methode	`POST`
URL	`https://api.armin.cx/public/v1/tickets/{ticket_number}/messages`
Header	`cx-api-key: DEIN_API_SCHLÜSSEL`, `Content-Type: application/json`, `Idempotency-Key: DEIN_EINDEUTIGER_KEY` (optional)

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

Request-Body

Feld	Typ	Default	Beschreibung
`type`	string	`reply`	`reply` sendet die Nachricht an den Kunden. `note` speichert eine interne Notiz, die nur Mitarbeitende sehen — wird nie versendet.
`body`	string	—	Klartext (max. 100.000 Zeichen). `body` oder `html_body` ist erforderlich.
`html_body`	string	—	HTML (max. 100.000 Zeichen).
`channel`	string	—	Auf einem bestimmten Kanaltyp senden statt auf dem Ticket-eigenen Kanal. Einer von: `email`, `widget`, `whatsapp`, `voice`, `instagram`, `facebook`, `tiktok`, `youtube`, `contact_form`.
`channel_identifier`	string	—	Eindeutige Posteingangs-ID bei mehreren Kanälen desselben `channel`-Typs. Nur zusammen mit `channel` genutzt.
`from_agent`	string	—	E-Mail des Teammitglieds, von dem die Nachricht gesendet wird. Muss zu einem bestehenden Agenten in eurer Organisation passen, sonst schlägt der Request fehl. Ohne Angabe gilt die Nachricht weiterhin als von eurem Unternehmen gesendet, ohne namentlichen Absender.
`attachment_ids`	UUID[]	—	IDs von Anhängen, bestätigt über den Anhänge-Ablauf unten (max. 10).
`skip_email`	boolean	`false`	Auf `true` setzen, damit die Nachricht gespeichert wird, ohne eine ausgehende Benachrichtigung zu senden — etwa beim Nachtragen bereits anderswo zugestellter Nachrichten.
`metadata`	object	—	Schlüssel/Wert für externe Referenzen (max. 50 Keys; String-Werte max. 2.000 Zeichen).

channel im Regelfall weglassen — die Nachricht wird auf dem Kanal versendet, den das Ticket bereits nutzt.

Idempotenz (optional)

Mit dem Header Idempotency-Key — ein beliebiger, pro echtem Sendeversuch eindeutiger Wert (z. B. eine UUID) — lässt sich ein Request sicher wiederholen (etwa nach einem Timeout), ohne die Nachricht doppelt zu senden.

Erster Request mit einem Key: wird normal verarbeitet. Die Antwort wird 1 Stunde lang gespeichert.
Gleicher Key, gleicher Body, innerhalb von 1 Stunde: keine neue Nachricht wird gesendet. Ihr bekommt genau die Antwort des ersten Requests zurück.
Gleicher Key, anderer Body: wird mit 400 IDEMPOTENCY_KEY_CONFLICT abgelehnt — einen Key nur für Wiederholungen des identischen Requests wiederverwenden.
Kein Key: funktioniert wie oben beschrieben, ohne Schutz vor Duplikaten.

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f29f...eindeutig-pro-versuch" \
  "https://api.armin.cx/public/v1/tickets/1042/messages" \
  -d '{
    "type": "reply",
    "body": "Danke für deine Nachricht! Deine Bestellung wird morgen versendet."
  }'

Anhänge

Eine Datei in drei Aufrufen anhängen: Upload-URL anfordern, Datei hochladen, dann bestätigen — erst danach hier referenzierbar. Vollständiger Ablauf und Limits: Ticket erstellen → Anhänge.

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets/1042/messages" \
  -d '{
    "type": "reply",
    "body": "Hier ist deine Rechnung.",
    "attachment_ids": ["ANHANG_ID"]
  }'

Minimales Beispiel

Antwort auf dem Ticket-eigenen Kanal:

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets/1042/messages" \
  -d '{
    "type": "reply",
    "body": "Danke für deine Nachricht! Deine Bestellung wird morgen versendet."
  }'

Vollständiges Beispiel

Antwort von einem namentlichen Agenten, mit Metadaten:

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets/1042/messages" \
  -d '{
    "type": "reply",
    "body": "Danke für deine Nachricht! Deine Bestellung wird morgen versendet.",
    "html_body": "<p>Danke für deine Nachricht! Deine Bestellung wird morgen versendet.</p>",
    "from_agent": "support@acme.com",
    "metadata": {
      "source": "order-automation"
    }
  }'

Interne Notiz, wird nie an den Kunden gesendet:

curl -sS -X POST \
  -H "cx-api-key: DEIN_API_SCHLÜSSEL" \
  -H "Content-Type: application/json" \
  "https://api.armin.cx/public/v1/tickets/1042/messages" \
  -d '{
    "type": "note",
    "body": "An Logistik eskaliert — warte auf Update vom Versanddienstleister."
  }'

Antwort

201 Created — v1-Erfolgs-Envelope:

{
  "success": true,
  "data": {
    "id": "019b0000-0000-7000-8000-000000000020",
    "ticket_id": "019b0000-0000-7000-8000-000000000001",
    "ticket_number": 1042,
    "role": "agent",
    "direction": "outbound",
    "text": "Danke für deine Nachricht! Deine Bestellung wird morgen versendet.",
    "channel": "email",
    "author_name": "Acme Support",
    "status": "queued",
    "created_at": "2026-08-25T10:00:00.000Z",
    "attachments": []
  }
}

status zeigt den Zustellstatus (queued, sent, delivered, failed, …). Eine reply startet als queued und wird von der bestehenden Sende-Pipeline abgeholt; eine note ist sofort delivered, da sie nie versendet wird.

Fehler

Situation	HTTP	Code
Fehlender/ungültiger API-Schlüssel	401	`API_KEY_REQUIRED`, `INVALID_API_KEY`
Scope `tickets:write` fehlt	403	`FORBIDDEN_SCOPE`
Unbekannte `ticket_number` in dieser Organisation	404	`TICKET_NOT_FOUND`
Ungültiger Body, unbekanntes Feld, `body`/`html_body` fehlt, oder `from_agent` passt zu keinem Agenten	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`
Gleicher `Idempotency-Key` mit anderem Request-Body wiederverwendet	400	`IDEMPOTENCY_KEY_CONFLICT`
Ein vorheriger Request mit diesem `Idempotency-Key` läuft noch	409	`IDEMPOTENCY_KEY_IN_PROGRESS`

Vollständige Liste: Fehler.

Jeder erfolgreiche Request erstellt eine neue Nachricht. Mit dem optionalen Idempotency-Key-Header lässt sich sicher wiederholen, ohne sie zu duplizieren.

Zuerst testen

Unter Einstellungen → API einen Schlüssel mit tickets:write anlegen.
Ein Test-Ticket anlegen (siehe Ticket erstellen) und mit den Beispielen oben eine Nachricht senden.
Prüfen, ob die Nachricht mit dem erwarteten Kanal und Absender im Ticket-Verlauf ankommt.

Test-Schlüssel danach widerrufen.

Weiterführend

OpenAPI-Referenz

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

Ticket erstellen

Ticket samt erster Nachricht anlegen.

Authentifizierung

Scopes, Rotation, Least Privilege.

Rate Limits

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

​Voraussetzungen

​Request

​Request-Body

​Idempotenz (optional)

​Anhänge

​Minimales Beispiel

​Vollständiges Beispiel

​Antwort

​Fehler

​Zuerst testen

​Weiterführend

OpenAPI-Referenz

Ticket erstellen

Authentifizierung

Rate Limits

Voraussetzungen

Request

Request-Body

Idempotenz (optional)

Anhänge

Minimales Beispiel

Vollständiges Beispiel

Antwort

Fehler

Zuerst testen

Weiterführend