REST-API

Gespräche

Gespräche deiner Assistenten auflisten und den Nachrichtenverlauf eines Gesprächs abrufen.

Wofür

Mit diesen Endpunkten holst du die Gespräche deiner Assistenten in eigene Systeme, etwa zur Archivierung, für ein eigenes Reporting oder um Gespräche einem Kunden im CRM zuzuordnen. Im Portal findest du dieselben Gespräche im Posteingang.

Nur lesenDie API kann Gespräche nicht anlegen und keine Nachrichten schreiben. Neue Gespräche entstehen über das Widget und die anderen Kanäle.

GET /conversations

Liefert Gespräche aller Assistenten deines Workspaces, die neuesten zuerst.

Parameter

Parameter	Typ	Standard	Bedeutung
`limit`	Zahl	50	Anzahl je Seite, höchstens 100
`offset`	Zahl	0	Wie viele Einträge übersprungen werden
`botId`	Text	–	Nur Gespräche dieses Assistenten (Kennung aus /bots)

Beispiel

curlbash

curl "https://app.lymbe.ai/api/v1/conversations?limit=20&botId=BOT_ID" \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL"

Antwort 200json

{
  "conversations": [
    {
      "id": "cmg1a2b3c0001",
      "sessionId": "sess_8f2k…",
      "bot": { "id": "BOT_ID", "name": "Website-Assistent" },
      "messageCount": 6,
      "createdAt": "2026-10-17T09:12:44.000Z",
      "updatedAt": "2026-10-17T09:15:02.000Z"
    }
  ],
  "pagination": { "total": 412, "limit": 20, "offset": 0, "hasMore": true }
}

Felder

Feld	Bedeutung
`id`	Kennung des Gesprächs, für `/conversations/{id}/messages`
`sessionId`	Kennung der Sitzung im Widget
`bot`	Kennung und Name des Assistenten
`messageCount`	Anzahl Nachrichten im Gespräch
`createdAt` / `updatedAt`	Beginn und letzte Änderung (ISO 8601, UTC)
`pagination.hasMore`	`true`, wenn es weitere Seiten gibt

Alle Gespräche durchblättern

fetchjavascript

const base = 'https://app.lymbe.ai/api/v1';
const headers = { 'x-api-key': process.env.LYMBE_API_KEY };
const alle = [];
let offset = 0;

while (true) {
  const res = await fetch(base + '/conversations?limit=100&offset=' + offset, { headers });
  if (!res.ok) throw new Error('Lymbe API: ' + res.status);
  const { conversations, pagination } = await res.json();
  alle.push(...conversations);
  if (!pagination.hasMore) break;
  offset += pagination.limit;
}

Grenze beachtenJede Seite zählt zu den 100 Anfragen pro Stunde. Für große Bestände ist der einmalige Datenexport oft der bessere Weg.

GET /conversations/{id}/messages

Liefert alle Nachrichten eines Gesprächs in zeitlicher Reihenfolge, die älteste zuerst.

curlbash

curl https://app.lymbe.ai/api/v1/conversations/cmg1a2b3c0001/messages \
  -H "x-api-key: lymbe_DEIN_SCHLUESSEL"

Antwort 200json

{
  "conversationId": "cmg1a2b3c0001",
  "messages": [
    { "id": "m1", "role": "user", "content": "Haben Sie samstags geöffnet?", "createdAt": "2026-10-17T09:12:44.000Z", "toolCalls": null, "toolResults": null },
    { "id": "m2", "role": "assistant", "content": "Ja, samstags von 9 bis 14 Uhr.", "createdAt": "2026-10-17T09:12:47.000Z", "toolCalls": null, "toolResults": null }
  ]
}

Feld	Bedeutung
`role`	`user` (Besucher), `assistant` (Assistent) oder andere Rollen, etwa für Antworten deines Teams im Live-Chat
`content`	Text der Nachricht
`toolCalls` / `toolResults`	Werkzeuge, die der Assistent dabei genutzt hat, sonst `null`

Ist das Gespräch nicht in deinem Workspace, kommt 404 mit Conversation not found.

Datenschutz

Nachrichten enthalten, was Besucher geschrieben haben, oft auch Namen, E-Mail-Adressen oder Telefonnummern. Speichere sie nur, wenn du sie brauchst.
Gespräche, die nach deiner Aufbewahrungsfrist gelöscht werden, verschwinden auch aus der API. Kopien in deinen Systemen musst du selbst löschen.

Häufige Fragen

Frage	Antwort
Kann ich nach Status filtern, z. B. nur offene Gespräche?	Nein. Die Liste kennt nur `limit`, `offset` und `botId`. Andere Parameter werden ignoriert.
Kann ich die Nachrichten direkt im Browser abrufen?	Nein. Der Nachrichten-Endpunkt erlaubt keine Aufrufe von fremden Websites, und dein Schlüssel gehört ohnehin auf den Server.
Wie erfahre ich sofort von neuen Gesprächen?	Die API meldet nichts von selbst. Frag die Liste in Abständen ab oder nutze die Benachrichtigungen für neue Anfragen und Übergaben.

Weiter: Leads · Posteingang im Portal

VorherigeAuthentifizierung NächsteLeads