Response Templates API

Die Response Templates API verwaltet Textbausteine (Antwort-Vorlagen), die Agents im Ticket-Composer einfügen. Bausteine sind mehrsprachig (de/en/fr/es/it) und haben einen Scope (PERSONAL / AGENT_GROUP / ORGANIZATION), der Sichtbarkeit und Verwaltungsrecht bestimmt. Mount: /api/response-templates.

🔐 Auth: Nur für angemeldete Benutzer — API-Keys erhalten 403, da persönliche Bausteine an einen Benutzer gebunden sind. Welche Rechte eine Änderung erfordert, hängt vom Scope des Bausteins ab (PERSONAL → manageOwn und Eigentümer, geteilt → manageShared). Siehe RBAC →.

Endpunkte

GET / liefert die im Composer einfügbaren Bausteine (nach Scope sichtbar, nur isActive). GET /manage liefert verwaltbare Bausteine: manageShared sieht alle shared (ORGANIZATION + AGENT_GROUP) plus eigene PERSONAL; nur manageOwn sieht ausschließlich eigene PERSONAL. Für Änderungen gilt je Scope: PERSONAL erfordert manageOwn UND Owner-Schaft, ORGANIZATION/AGENT_GROUP erfordern manageShared.

Antwortform

Beide Listen liefern die Bausteine unter data — ohne Seitenzahlen, weil die Menge je Benutzer klein bleibt und vollständig ausgeliefert wird. Die Picker-Liste sortiert nach Kategorie, dann Name; die Verwaltungs-Liste stellt den Scope voran. POST und PATCH :id liefern das Objekt nackt, die beiden übrigen Mutationen antworten 204 ohne Body.

{
  "data": [
    {
      "id": "clx-tpl-ack",
      "name": "Acknowledgement",
      "category": "General",
      "scope": "ORGANIZATION",
      "ownerId": null,
      "agentGroupId": null,
      "isActive": true,
      "translations": {
        "de": { "body": "Vielen Dank für Ihre Anfrage. Wir kümmern uns darum." },
        "en": { "body": "Thank you for your request. We are on it." }
      },
      "agentGroup": null
    }
  ]
}

ownerId ist nur bei PERSONAL gesetzt — daran erkennt der Picker die eigenen Bausteine. Bei scope AGENT_GROUP trägt agentGroup die Zielgruppe mit id, name und isArchived; Bausteine archivierter Gruppen bleiben in der Verwaltung sichtbar (mit Hinweis) und verschwinden aus dem Picker.

Scopes

Baustein anlegen

POST /api/response-templates

{
  "name": "Acknowledgement",
  "category": "General",
  "scope": "ORGANIZATION",
  "isActive": true,
  "translations": {
    "de": { "body": "Vielen Dank für Ihre Anfrage. Wir kümmern uns darum." },
    "en": { "body": "Thank you for your request. We are on it." }
  }
}

// scope AGENT_GROUP — agentGroupId Pflicht:{
  "name": "Network Standard Reply",
  "scope": "AGENT_GROUP",
  "agentGroupId": "clx-group-network",
  "translations": { "de": { "body": "Bitte starten Sie zunächst Ihren Router neu …" } }
}

Felder: name (1–120), category? (max 60, Leerstring → null), scope (Default PERSONAL), agentGroupId (Pflicht nur bei AGENT_GROUP, sonst verboten), translations (Record aus de/en/fr/es/it → { body 1–5000 }, mind. 1 Sprache), isActive (Default true). ownerId setzt immer der Server (der angemeldete Benutzer). Der Body wird streng geprüft: ein unbekanntes Feld ist ein 400 — so fällt ein Tippfehler im Feldnamen sofort auf, statt still ignoriert zu werden. Dasselbe gilt für die Query von GET / (nur search, max 200 Zeichen, und category).

Baustein aktualisieren

PATCH /api/response-templates/:id

{ "name": "Acknowledgement (short)", "translations": { "de": { "body": "…" } } }

⚠️ scope ist beim Update nicht änderbar, weil sich damit Eigentümer und Sichtbarkeit des Bausteins ändern würden. Ein GROUP↔ORG-Umzug = Löschen + Neuanlegen. Ein agentGroupId-Wechsel innerhalb AGENT_GROUP ist erlaubt. Ein PATCH mit leeren translations ist abgelehnt (mind. 1 Sprache).

Verwendung im Ticket-Composer

Bausteine werden über den Picker (GET /) in den Ticket-Antwort-Composer eingefügt. Da das Body-Limit pro Sprachfassung dem Ticket-Message-Limit entspricht (5000 Zeichen), prüft der Picker beim Einfügen die Gesamtlänge (vorhandener Text + Baustein); ist sie zu lang, wird nicht eingefügt und ein Hinweis angezeigt, statt den Text abzuschneiden.

🎫 Ticket-Nachrichten und Antwort-Flow: Tickets API →.

Fehlercodes

🔒 Ein fremder PERSONAL-Baustein antwortet auf jede Änderung mit 404, nicht mit 403: Ein 403 würde bestätigen, dass es diesen Baustein gibt. Persönliche Bausteine bleiben deshalb auch für Verwalter mit manageShared unsichtbar.

Permissions (responseTemplates)