Conversations API

Gespräche auflisten und Nachrichten abrufen über die Conversations-Endpunkte.

Übersicht

Die Conversations API ermöglicht den Zugriff auf alle Chat-Gespräche deines Tenants. Du kannst Gespräche auflisten, filtern und die einzelnen Nachrichten eines Gesprächs abrufen.

BerechtigungBenötigter Scope: conversations:read

Gespräche auflisten

GET /api/v1/conversations

Query-Parameter

Parameter	Typ	Standard	Beschreibung
limit	number	20	Ergebnisse pro Seite (1-100)
offset	number	0	Ergebnisse überspringen
botId	string	-	Nach Bot-ID filtern
status	string	-	Filtert nach Status: active, completed, handover
from	string	-	Startdatum (ISO-8601)
to	string	-	Enddatum (ISO-8601)
sort	string	desc	Sortierung: asc oder desc (nach Erstellungsdatum)

Beispiel-Request

curl -X GET "https://app.lymbe.ai/api/v1/conversations?limit=10&status=completed" \
  -H "X-API-Key: lymbe_sk_dein_api_key"

Beispiel-Response

conversations-response.jsonjson

{
  "conversations": [
    {
      "id": "conv_abc123",
      "botId": "bot_xyz789",
      "status": "completed",
      "messageCount": 12,
      "leadCaptured": true,
      "visitorInfo": {
        "ip": "203.0.113.42",
        "userAgent": "Mozilla/5.0...",
        "referrer": "https://google.com",
        "page": "https://example.com/preise"
      },
      "startedAt": "2026-03-15T14:22:00Z",
      "endedAt": "2026-03-15T14:35:12Z",
      "createdAt": "2026-03-15T14:22:00Z"
    },
    {
      "id": "conv_def456",
      "botId": "bot_xyz789",
      "status": "completed",
      "messageCount": 8,
      "leadCaptured": false,
      "visitorInfo": {
        "ip": "198.51.100.7",
        "userAgent": "Mozilla/5.0...",
        "referrer": null,
        "page": "https://example.com/kontakt"
      },
      "startedAt": "2026-03-15T10:05:00Z",
      "endedAt": "2026-03-15T10:12:30Z",
      "createdAt": "2026-03-15T10:05:00Z"
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Nachrichten eines Gesprächs

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

Beispiel-Request

curl -X GET "https://app.lymbe.ai/api/v1/conversations/conv_abc123/messages" \
  -H "X-API-Key: lymbe_sk_dein_api_key"

Beispiel-Response

messages-response.jsonjson

{
  "messages": [
    {
      "id": "msg_001",
      "conversationId": "conv_abc123",
      "role": "bot",
      "content": "Hallo! Wie kann ich dir helfen?",
      "timestamp": "2026-03-15T14:22:00Z"
    },
    {
      "id": "msg_002",
      "conversationId": "conv_abc123",
      "role": "user",
      "content": "Was kostet der Pro-Plan?",
      "timestamp": "2026-03-15T14:22:15Z"
    },
    {
      "id": "msg_003",
      "conversationId": "conv_abc123",
      "role": "bot",
      "content": "Der Pro-Plan kostet 49 EUR pro Monat und enthält bis zu 5 Bots, 10.000 Nachrichten und erweiterte Analytics. Möchtest du mehr Details?",
      "metadata": {
        "sourceDocuments": [
          {
            "title": "Preisseite",
            "chunk": "Der Pro-Plan kostet 49 EUR/Monat...",
            "score": 0.94
          }
        ],
        "tokensUsed": 156,
        "latencyMs": 820
      },
      "timestamp": "2026-03-15T14:22:18Z"
    },
    {
      "id": "msg_004",
      "conversationId": "conv_abc123",
      "role": "user",
      "content": "Ja, gerne. Kann ich auch monatlich kündigen?",
      "timestamp": "2026-03-15T14:22:45Z"
    },
    {
      "id": "msg_005",
      "conversationId": "conv_abc123",
      "role": "bot",
      "content": "Ja, alle Pläne sind monatlich kündbar. Es gibt keine Mindestlaufzeit. Du kannst jederzeit in deinen Einstellungen kündigen oder den Plan wechseln.",
      "metadata": {
        "sourceDocuments": [
          {
            "title": "FAQ",
            "chunk": "Alle Pläne sind monatlich kündbar...",
            "score": 0.91
          }
        ],
        "tokensUsed": 132,
        "latencyMs": 750
      },
      "timestamp": "2026-03-15T14:22:48Z"
    }
  ]
}

Node.js Beispiel

conversations-example.tstypescript

const API_KEY = process.env.LYMBE_API_KEY!;
const BASE = 'https://app.lymbe.ai/api/v1';

interface Conversation {
  id: string;
  botId: string;
  status: 'active' | 'completed' | 'handover';
  messageCount: number;
  leadCaptured: boolean;
  startedAt: string;
  endedAt: string | null;
}

// Alle abgeschlossenen Gespräche der letzten 7 Tage abrufen
async function getRecentConversations(): Promise<Conversation[]> {
  const from = new Date();
  from.setDate(from.getDate() - 7);

  const params = new URLSearchParams({
    status: 'completed',
    from: from.toISOString(),
    limit: '100',
  });

  const res = await fetch(`${BASE}/conversations?${params}`, {
    headers: { 'X-API-Key': API_KEY },
  });

  if (!res.ok) throw new Error(`API-Fehler: ${res.status}`);

  const data = await res.json();
  return data.conversations;
}

// Nachrichten eines Gesprächs abrufen
async function getMessages(conversationId: string) {
  const res = await fetch(`${BASE}/conversations/${conversationId}/messages`, {
    headers: { 'X-API-Key': API_KEY },
  });

  if (!res.ok) throw new Error(`API-Fehler: ${res.status}`);

  const data = await res.json();
  return data.messages;
}

VorherigeAuthentifizierung NächsteLeads