API & Webhooks

Verbinden Sie Ihre eigenen Systeme über eine REST-API und Webhooks. Beides hängt von Ihrem Abo ab und wird pro Projekt unter Projekteinstellungen → API eingerichtet (nur Manager:innen).

API-Schlüssel

Aktivieren Sie die API für das Projekt und erstellen Sie dann einen Schlüssel pro angebundenem System, damit Sie ihn einzeln widerrufen können. Jeder Schlüssel erhält nur die Berechtigungen, die er braucht:

Berechtigung	Erlaubt
Unterhaltungen	Lesen; antworten, Notizen hinzufügen, Status, Zuweisung und Tags ändern
Kontakte	Kontakte lesen
Auswertungen	Statistiken lesen
Wissensdatenbank	Lesen und suchen; Einträge erstellen, ändern und löschen
Datenschutz	Texte mit den Datenschutzeinstellungen des Projekts anonymisieren

Senden Sie den Schlüssel als Bearer-Token:

curl https://api.commelia.com/v1/conversations?status=open \
  -H "Authorization: Bearer cml_..."

Interne Notizen gibt die API nie aus.

Webhooks

Webhooks benachrichtigen Ihr System über neue Unterhaltungen, Nachrichten, Zuweisungen, Eskalationen, abgeschlossene Unterhaltungen und Vorschläge für die Wissensdatenbank. In der App wählen Sie Ereignisse, senden einen Test, sehen die letzten Zustellungen ein und senden eine Zustellung erneut.

Jede Zustellung ist ein POST mit JSON-Inhalt, signiert mit HMAC-SHA256. Prüfen Sie den Header Commelia-Signature mit dem Signatur-Secret des Endpunkts:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Fehlgeschlagene Zustellungen werden mit wachsenden Abständen wiederholt. Mit dem Header Commelia-Delivery erkennen Sie Duplikate.