API v2-gesprekken

Gebruik deze endpoints om gespreksgeschiedenis te lezen en met API v2-berichten te werken. Elk endpoint op deze pagina vereist Authorization: Bearer YOUR_API_KEY en toegang tot {agentId}.

Bereik van gesprekken

Alleen-lezen gespreksendpoints gebruiken standaard source=api_v2. Zet source=widget om widget- en Playground-gesprekken terug te geven; Playground-rijen worden opgeslagen met de bron widget. Zet source=all om API v2-, widget- en Playground-gesprekken terug te geven. Resultaten blijven altijd beperkt tot de agent van het geauthenticeerde account. Een ongeldige source-waarde of meer dan één source-queryparameter geeft 400 VALIDATION_INVALID_BODY terug. Chat-vervolg, retry, feedback, berichtenlijsten en per-gebruikersreads blijven beperkt tot API v2-gesprekken.

Responseobjecten

Gesprekssamenvattingen bevatten:

Berichtobjecten bevatten:

Berichtrijen van het type tool worden weggelaten uit gesprekstranscripten en berichtenlijsten.

Gesprekken weergeven

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

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

Authenticatie: Bearer API-sleutel met toegang tot {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'

Succes: 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
  }
}

Ongeldige limieten, cursors, source-waarden en dubbele source-parameters geven 400 VALIDATION_INVALID_BODY terug.

Gesprekken exporteren

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

Exporteren gebruikt dezelfde volgorde van gesprekken en hetzelfde cursorcontract als het endpoint voor de lijst, maar beperkt elke pagina tot 20 gesprekken. Elk gesprek bevat alle niet-toolberichten, gesorteerd van oud naar nieuw.

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

Succes: 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
  }
}

Een gesprek ophalen

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

De response bevat het volledige transcript zonder toolberichten, gesorteerd van oud naar nieuw. Dit endpoint gebruikt geen cursorpaginering; gebruik het endpoint voor de berichtenlijst voor gepagineerde toegang tot API v2-berichten.

Succes: 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
  }
}

Een ontbrekend gesprek binnen de geselecteerde bron geeft 404 RESOURCE_NOT_FOUND terug.

Berichten weergeven

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}. Het gesprek moet een API v2-gesprek zijn.

Berichtcursors zijn de enige v2-pagineringscursor waarvan het server-side ID-onderdeel als numerieke string wordt gevalideerd, omdat berichten bigint-ID's gebruiken. Elke andere gepagineerde v2-resource valideert UUID-ID's. Behandel beide vormen als ondoorzichtig; construeer of decodeer cursors nooit zelf. Berichten binnen elke geretourneerde pagina zijn gesorteerd van oud naar nieuw.

Succes: 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
  }
}

Een ontbrekend API v2-gesprek geeft 404 RESOURCE_NOT_FOUND terug; ongeldige limieten en cursors geven 400 VALIDATION_INVALID_BODY terug.

Een antwoord van de assistant opnieuw proberen

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}. Het gesprek moet een API v2-gesprek zijn.

Retry verwijdert het voorgaande gebruikersbericht, het geselecteerde antwoord van de assistant en elk later bericht, en speelt vervolgens die gebruikerstekst opnieuw af om het antwoord opnieuw te genereren. Als het opslaan van de regeneratie mislukt, worden de verwijderde rijen hersteld.

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}'

Succes: 200 OK. Bij stream: true is de response een Server-Sent Events-stream met dezelfde eventindeling als chat. Bij stream: false is de response:

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

Onjuist gevormde JSON geeft 400 VALIDATION_INVALID_JSON terug. Ongeldige body's geven 400 VALIDATION_INVALID_BODY terug. Zie CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND, en INTERNAL_SERVER_ERROR in de foutcatalogus.

Een toolresultaat indienen

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

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

Response: Een overeenkomende wachtende actie wordt één keer geclaimd en de voortzetting komt als text/event-stream. Onbekende of verlopen aanroepen geven 404; concurrerende of conflicterende resultaten geven 409.

Feedback op een bericht instellen of wissen

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}. Het gesprek moet een API v2-gesprek zijn.

{messageId} moet omgezet kunnen worden naar een positief geheel getal en moet een AI-assistant-bericht in het opgegeven gesprek aanduiden.

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"}'

Succes: 200 OK

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

Onjuist gevormde JSON geeft 400 VALIDATION_INVALID_JSON terug; een ongeldige body geeft 400 VALIDATION_INVALID_BODY terug; een ontbrekend gesprek geeft 404 RESOURCE_NOT_FOUND terug; een ontbrekend bericht geeft 404 RESOURCE_MESSAGE_NOT_FOUND terug; en een doel dat geen AI-assistant is, geeft 422 RESOURCE_MESSAGE_NOT_ASSISTANT terug.

Gesprekken van een gebruiker weergeven

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

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

Authenticatie: Bearer API-sleutel met toegang tot {agentId}.

{userId} moet 1 tot en met 128 tekens bevatten en mag alleen letters, cijfers, ., _, en - bevatten.

Alleen API v2-chat schrijft userId, dus dit endpoint geeft uitsluitend API v2-gesprekken terug. De response bij succes is dezelfde gepagineerde envelop met gesprekssamenvattingen als bij Gesprekken weergeven.

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

Succes: 200 OK. Ongeldige gebruikers-ID's, limieten, cursors, of gebruik van source geven 400 VALIDATION_INVALID_BODY terug.

Gerelateerde referentie

• API v2-overzicht en chat
• API v2-foutcatalogus
• Contacten en geverifieerde identiteit