REST-API · EasyLiveChat

§ 00Was die REST-API ist

EasyLiveChat stellt unter /api/v1/* eine REST-API bereit, damit externer Code — Ihr eigenes Backend, eine CRM-Integration, ein Zapier- oder n8n-Flow, ein Migrationsskript — Ihren Arbeitsbereich lesen und schreiben kann, ohne dass ein menschlicher Agent angemeldet ist. Jeder Aufruf wird mit einem im Dashboard erstellten, mandantenbezogenen API-Schlüssel authentifiziert.

Wenn Sie schon einmal die Stripe-, Slack- oder GitHub-API aufgerufen haben, funktioniert das genauso: ein langlebiges Geheimtoken im Authorization-Header, JSON-Request- und Response-Bodies, vorhersehbare HTTP-Statuscodes.

Ein API-Schlüssel trägt nie 2FA oder ein Passwort — das ist der ganze Sinn. Es sind Zugangsdaten, die Sie in andere Software einbetten, damit diese im Namen Ihres Mandanten handeln kann, aber nur mit den Bereichen, die Sie ihr geben.

§ 01Plan-Verfügbarkeit

Die REST-API ist in jedem kostenpflichtigen Plan verfügbar und wird während der 14-tägigen Testphase freigeschaltet. Es gibt keine Abrechnung pro Aufruf.

Sobald die Testphase abläuft, wechselt die API in den Nur-Lese-Modus — Schreibvorgänge geben 402 zurück, bis der Arbeitsbereich aktualisiert wird. Lesevorgänge funktionieren weiter, damit Ihre historischen Exporte nie unterbrochen werden.

§ 02Authentifizierung

Erstellen Sie einen Schlüssel unter https://app.livechattools.com/settings/api-keys. Wählen Sie die kleinste Menge an Geltungsbereichen, die die Integration tatsächlich braucht. Sie können einen Schlüssel von derselben Seite jederzeit widerrufen — er funktioniert sofort nicht mehr, ohne Auswirkungen auf das Dashboard oder die Mobil-Logins Ihrer Agenten.

Übergeben Sie den Schlüssel bei jeder Anfrage, entweder als Bearer-Token oder über x-api-key:

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

Überprüfen Sie, ob der Schlüssel funktioniert, bevor Sie ihn irgendwo einbauen — /me gibt Ihre Geltungsbereiche und Ihren Mandanten zurück:

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

Der Klarschlüssel wird nur einmal bei der Erstellung angezeigt. Verloren? Widerrufen Sie ihn und erstellen Sie einen neuen — der Originalwert kann nicht wiederhergestellt werden.

§ 03Geltungsbereiche

Geltungsbereiche werden bei jeder Anfrage geprüft. Ein Schlüssel mit nur :read-Bereichen kann nie versehentlich Daten ändern — nützlich für reine Lese-Dashboards, BI-Exporte oder Analyse-Pipelines.

Bereich	Erlaubt
conversations:read	Gespräche und ihre Nachrichten auflisten und lesen.
conversations:write	Gespräche schließen, wieder öffnen oder neu zuweisen.
messages:read	Nachrichtenverlauf eines Gesprächs lesen.
messages:write	Eine neue Nachricht als Agent senden.
contacts:read	Kontakte auflisten und durchsuchen.

Prinzip der geringsten Rechte — pro Integration ein eigener Schlüssel. Ein durchgesickerter Nur-Lese-Schlüssel auf Ihrer Reporting-Pipeline ist viel weniger schädlich als ein einziger "Alleskönner"-Schlüssel, der im ganzen Stack geteilt wird.

§ 04Endpunkte

Jeder Pfad ist unter /api/v1 verankert. Antworten sind JSON. Zeiten sind ISO 8601 UTC.

`GET /api/v1/me`

Gibt die Identität des Schlüssels und den Mandanten zurück. Kein Geltungsbereich erforderlich — nützlich für Verbindungstests.

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

`GET /api/v1/conversations`

Gespräche neueste zuerst auflisten. Alle Filter sind optional.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, Standard 50
?cursor= ID der letzten Zeile der vorherigen Seite

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

`GET /api/v1/conversations/:id`

Ein einzelnes Gespräch mit angehängtem Kontakt abrufen.

`GET /api/v1/conversations/:id/messages`

Paginierter Nachrichtenverlauf eines Gesprächs, neueste zuerst.

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

`POST /api/v1/conversations/:id/messages`

Senden Sie eine ausgehende Nachricht in einem Gespräch. Sie wird wie die Antwort eines menschlichen Agenten an den passenden Kanal (Widget, WhatsApp, Telegram, Messenger, Instagram) weitergeleitet.

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId ist optional — wenn weggelassen, wird die Nachricht dem ersten aktiven OWNER oder ADMIN im Arbeitsbereich zugeordnet. Geben Sie eine explizite ID an, wenn ein bestimmtes Bot-Konto in der Konversation erscheinen soll.

`PATCH /api/v1/conversations/:id`

Aktualisieren Sie den Status eines Gesprächs (OPEN · SNOOZED · CLOSED) oder den zugewiesenen Agenten. Übergeben Sie assignedAgentId: null, um die Zuweisung aufzuheben.

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

`GET /api/v1/contacts`

Kontakte im Arbeitsbereich auflisten. ?q= sucht in Name, E-Mail oder Telefon.

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05Paginierung

Alle Listen-Endpunkte verwenden Cursor-Paginierung. Die Antwortform ist:

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

Um die nächste Seite zu holen, übergeben Sie nextCursor als ?cursor= in der nächsten Anfrage. Wenn nextCursor null ist, haben Sie das Ende erreicht.

§ 06Fehler

Fehler liefern immer einen JSON-Body mit Fehlercode und (wo hilfreich) einer menschenlesbaren Nachricht. Der HTTP-Status spiegelt die Bedeutung wider:

Status	Code	Bedeutung
401	UNAUTHENTICATED	Fehlender, ungültiger oder widerrufener Schlüssel.
402	TRIAL_EXPIRED	Testphase abgelaufen — Schreibvorgänge sind blockiert, Lesevorgänge funktionieren noch.
403	FORBIDDEN	Schlüssel ist gültig, aber der für diesen Endpunkt benötigte Geltungsbereich fehlt.
404	NOT_FOUND	Das Gespräch, der Kontakt oder eine andere Ressource existiert in Ihrem Mandanten nicht.
400	INVALID_BODY	Im Anfragebody fehlen erforderliche Felder oder die Typen sind falsch.
429	RATE_LIMITED	Zu viele Anfragen — zurückziehen und nach einigen Sekunden erneut versuchen.

§ 07Webhooks (Begleiter)

Die REST-API ist großartig zum Abrufen und Senden nach Ihrem Zeitplan. Für Push-Benachrichtigungen, wenn auf der EasyLiveChat-Seite etwas passiert — eine neue Kundennachricht, ein geschlossenes Gespräch, ein neuer Agent — konfigurieren Sie ausgehende Webhooks in Einstellungen → Webhooks.

Nachrichten, die Sie über POST /api/v1/conversations/:id/messages senden, lösen auch den message.created-Webhook aus. Wenn Sie also sowohl eine Integration zum Senden als auch eine zum Empfangen haben, sehen Sie Ihre eigenen Schreibvorgänge über den Webhook-Kanal zurück.

§ 08Rate Limits

Jeder Mandant erhält bis zu 240 Anfragen pro Minute und Pfad, geteilt über alle Schlüssel dieses Mandanten. Beim Erreichen des Limits wird 429 mit einem Retry-After-Header zurückgegeben.

Wenn Ihre Integration legitim eine höhere Obergrenze braucht (Massenimport, Massen-Versand), schreiben Sie an den Support — wir heben sie für Ihren Mandanten an.

Bearbeitung vorschlagen