API v2 Unterhaltungen

Verwenden Sie diese Endpunkte, um den Unterhaltungsverlauf zu lesen und mit API-v2-Nachrichten zu arbeiten. Jeder Endpunkt auf dieser Seite erfordert Authorization: Bearer YOUR_API_KEY und Zugriff auf {agentId}.

Umfang der Unterhaltungen

Schreibgeschützte Unterhaltungs-Endpunkte verwenden standardmäßig source=api_v2. Setzen Sie source=widget, um Widget- und Playground-Unterhaltungen zurückzugeben; Playground-Datensätze werden mit der Quelle widget gespeichert. Setzen Sie source=all, um API-v2-, Widget- und Playground-Unterhaltungen zurückzugeben. Die Ergebnisse bleiben stets auf den Agenten des authentifizierten Kontos beschränkt. Ein ungültiger source-Wert oder mehr als ein source-Abfrageparameter führt zu 400 VALIDATION_INVALID_BODY. Chat-Fortsetzung, Wiederholung, Feedback, Nachrichtenauflistung und nutzerbezogene Abfragen bleiben auf API-v2-Unterhaltungen beschränkt.

Antwortobjekte

Unterhaltungszusammenfassungen enthalten:

Nachrichtenobjekte enthalten:

Nachrichtenzeilen vom Typ „Tool“ werden aus Unterhaltungsverläufen und Nachrichtenlisten ausgeschlossen.

Unterhaltungen auflisten

Path: /api/v2/agents/{agentId}/conversations

GET /api/v2/agents/{agentId}/conversations

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations?source=all&limit=20' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Erfolg: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing"
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Ungültige Limits, Cursor, Quellwerte und doppelte Source-Parameter führen zu 400 VALIDATION_INVALID_BODY.

Unterhaltungen exportieren

Path: /api/v2/agents/{agentId}/conversations/export

GET /api/v2/agents/{agentId}/conversations/export

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Der Export verwendet dieselbe Sortierreihenfolge der Unterhaltungen und denselben Cursor-Vertrag wie der Listen-Endpunkt, begrenzt jedoch jede Seite auf 20 Unterhaltungen. Jede Unterhaltung enthält alle Nicht-Tool-Nachrichten, sortiert vom ältesten zum neuesten.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/export?source=api_v2' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Erfolg: 200 OK

{
  "data": [
    {
      "id": "b2mD4kL8pQ1sT6vX",
      "title": "Where is my order?",
      "createdAt": 1784332800,
      "updatedAt": 1784332860,
      "userId": "customer_123",
      "source": "api_v2",
      "status": "ongoing",
      "messages": [
        {
          "id": "122",
          "role": "user",
          "parts": [{ "type": "text", "text": "Where is my order?" }],
          "createdAt": 1784332800,
          "feedback": null,
          "metadata": null
        }
      ]
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Eine Unterhaltung abrufen

Path: /api/v2/agents/{agentId}/conversations/{conversationId}

GET /api/v2/agents/{agentId}/conversations/{conversationId}

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

Die Antwort enthält den vollständigen Nicht-Tool-Verlauf, sortiert vom ältesten zum neuesten. Dieser Endpunkt ist nicht cursor-paginiert; verwenden Sie für den seitenweisen Zugriff auf API-v2-Nachrichten den Nachrichtenlisten-Endpunkt.

Erfolg: 200 OK

{
  "data": {
    "id": "b2mD4kL8pQ1sT6vX",
    "title": "Where is my order?",
    "createdAt": 1784332800,
    "updatedAt": 1784332860,
    "userId": "customer_123",
    "source": "api_v2",
    "status": "ongoing",
    "messages": [
      {
        "id": "122",
        "role": "user",
        "parts": [{ "type": "text", "text": "Where is my order?" }],
        "createdAt": 1784332800,
        "feedback": null,
        "metadata": null
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 1
  }
}

Eine im ausgewählten Source-Wert fehlende Unterhaltung führt zu 404 RESOURCE_NOT_FOUND.

Nachrichten auflisten

Path: /api/v2/agents/{agentId}/conversations/{conversationId}/messages

GET /api/v2/agents/{agentId}/conversations/{conversationId}/messages

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}. Die Unterhaltung muss eine API-v2-Unterhaltung sein.

Nachrichten-Cursor sind der einzige v2-Paginierungscursor, dessen serverseitige ID-Komponente als numerischer String validiert wird, da Nachrichten Bigint-IDs verwenden. Jede andere paginierte v2-Ressource validiert UUID-IDs. Behandeln Sie beide Formen als undurchsichtig; konstruieren oder dekodieren Sie Cursor niemals. Nachrichten innerhalb jeder zurückgegebenen Seite sind vom ältesten zum neuesten sortiert.

Erfolg: 200 OK

{
  "data": [
    {
      "id": "122",
      "role": "user",
      "parts": [{ "type": "text", "text": "Where is my order?" }],
      "createdAt": 1784332800,
      "feedback": null,
      "metadata": null
    },
    {
      "id": "123",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "Please share your order number." }],
      "createdAt": 1784332860,
      "feedback": "positive",
      "metadata": null
    }
  ],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 2
  }
}

Eine fehlende API-v2-Unterhaltung führt zu 404 RESOURCE_NOT_FOUND; ungültige Limits und Cursor führen zu 400 VALIDATION_INVALID_BODY.

Eine Assistant-Antwort wiederholen

Path: /api/v2/agents/{agentId}/conversations/{conversationId}/retry

POST /api/v2/agents/{agentId}/conversations/{conversationId}/retry

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}. Die Unterhaltung muss eine API-v2-Unterhaltung sein.

Retry löscht die vorangehende Nutzernachricht, die ausgewählte Assistant-Antwort sowie alle späteren Nachrichten und spielt anschließend den Nutzertext erneut ab, um die Antwort neu zu generieren. Schlägt die Persistierung der Neugenerierung fehl, werden die gelöschten Zeilen wiederhergestellt.

curl -X POST 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"messageId":"123","stream":false}'

Erfolg: 200 OK. Bei stream: true ist die Antwort ein Server-Sent-Events-Stream im selben Ereignisformat wie Chat. Bei stream: false lautet die Antwort:

{
  "data": {
    "id": "124",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Here is a regenerated answer." }],
    "metadata": {
      "conversationId": "b2mD4kL8pQ1sT6vX",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

Fehlerhaftes JSON führt zu 400 VALIDATION_INVALID_JSON. Ungültige Bodys führen zu 400 VALIDATION_INVALID_BODY. Siehe CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND und INTERNAL_SERVER_ERROR im Fehlerkatalog.

Ein Tool-Ergebnis übermitteln

Path: /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

POST /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

{
  "toolCallId": "call_123",
  "output": { "available": true }
}

Antwort: Eine passende ausstehende Aktion wird genau einmal beansprucht; die Fortsetzung kommt als text/event-stream. Unbekannte oder abgelaufene Aufrufe geben 404 zurück, konkurrierende oder abweichende Ergebnisse 409.

Nachrichten-Feedback setzen oder entfernen

Path: /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

PATCH /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}. Die Unterhaltung muss eine API-v2-Unterhaltung sein.

{messageId} muss sich in eine positive Ganzzahl umwandeln lassen und eine KI-Assistant-Nachricht in der angegebenen Unterhaltung identifizieren.

curl -X PATCH 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/conversations/b2mD4kL8pQ1sT6vX/messages/123/feedback' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"feedback":"positive"}'

Erfolg: 200 OK

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "Please share your order number." }],
    "createdAt": 1784332860,
    "feedback": "positive",
    "metadata": null
  }
}

Fehlerhaftes JSON führt zu 400 VALIDATION_INVALID_JSON; ein ungültiger Body führt zu 400 VALIDATION_INVALID_BODY; eine fehlende Unterhaltung führt zu 404 RESOURCE_NOT_FOUND; eine fehlende Nachricht führt zu 404 RESOURCE_MESSAGE_NOT_FOUND; und ein Ziel, das keine KI-Assistant-Nachricht ist, führt zu 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Unterhaltungen eines Nutzers auflisten

Path: /api/v2/agents/{agentId}/users/{userId}/conversations

GET /api/v2/agents/{agentId}/users/{userId}/conversations

Authentifizierung: Bearer-API-Schlüssel mit Zugriff auf {agentId}.

{userId} muss 1 bis 128 Zeichen lang sein und darf nur Buchstaben, Zahlen, ., _ und - enthalten.

Nur API-v2-Chat schreibt userId, daher gibt dieser Endpunkt ausschließlich API-v2-Unterhaltungen zurück. Seine Erfolgsantwort verwendet denselben paginierten Unterhaltungszusammenfassungs-Umschlag wie Unterhaltungen auflisten.

curl 'https://your-domain.com/api/v2/agents/955f28f1-8515-40bb-802c-f3f730bf0343/users/customer_123/conversations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Erfolg: 200 OK. Ungültige Nutzer-IDs, Limits, Cursor oder eine ungültige Verwendung von source führen zu 400 VALIDATION_INVALID_BODY.

Referenz

• API-v2-Übersicht und Chat
• API-v2-Fehlerkatalog
• Kontakte und verifizierte Identität