API v2 – konwersacje

Za pomocą tych punktów końcowych odczytujesz historię konwersacji i pracujesz z wiadomościami API v2. Każdy punkt końcowy na tej stronie wymaga nagłówka Authorization: Bearer YOUR_API_KEY oraz dostępu do {agentId}.

Zakres konwersacji

Punkty końcowe do odczytu konwersacji domyślnie używają source=api_v2. Ustaw source=widget, aby zwrócić konwersacje z widżetu i Playgroundu; wiersze z Playgroundu są zapisywane ze źródłem widget. Ustaw source=all, aby zwrócić konwersacje z API v2, widżetu i Playgroundu. Wyniki zawsze pozostają ograniczone do agenta uwierzytelnionego konta. Nieprawidłowa wartość source lub podanie więcej niż jednego parametru zapytania source skutkuje błędem 400 VALIDATION_INVALID_BODY. Kontynuacja czatu, ponawianie odpowiedzi, informacja zwrotna, lista wiadomości oraz odczyty dla poszczególnych użytkowników pozostają ograniczone do konwersacji API v2.

Obiekty odpowiedzi

Podsumowania konwersacji zawierają:

Obiekty wiadomości zawierają:

Wiadomości reprezentujące wywołania narzędzi są pomijane w transkryptach konwersacji i na listach wiadomości.

Lista konwersacji

Ścieżka: /api/v2/agents/{agentId}/conversations

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {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'

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

Nieprawidłowe wartości limit, cursor, source oraz zduplikowane parametry source skutkują błędem 400 VALIDATION_INVALID_BODY.

Eksportowanie konwersacji

Ścieżka: /api/v2/agents/{agentId}/conversations/export

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Eksport wykorzystuje tę samą kolejność konwersacji i tę samą umowę dotyczącą kursora co punkt końcowy listy, ale ogranicza każdą stronę do 20 konwersacji. Każda konwersacja zawiera wszystkie wiadomości niebędące wywołaniami narzędzi, uporządkowane od najstarszych do najnowszych.

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

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

Pobieranie konwersacji

Ścieżka: /api/v2/agents/{agentId}/conversations/{conversationId}

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

Odpowiedź zawiera cały transkrypt bez wywołań narzędzi, uporządkowany od najstarszych do najnowszych. Ten punkt końcowy nie obsługuje paginacji kursorowej; aby uzyskać stronicowany dostęp do wiadomości API v2, użyj punktu końcowego listy wiadomości.

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

Brak konwersacji w wybranym źródle skutkuje błędem 404 RESOURCE_NOT_FOUND.

Lista wiadomości

Ścieżka: /api/v2/agents/{agentId}/conversations/{conversationId}/messages

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}. Konwersacja musi być konwersacją API v2.

Kursory wiadomości są jedynym kursorem paginacji w API v2, w którym komponent identyfikatora po stronie serwera jest walidowany jako ciąg liczbowy, ponieważ wiadomości używają identyfikatorów typu bigint. Każdy inny paginowany zasób v2 waliduje identyfikatory UUID. Traktuj obie formy jako nieprzejrzyste; nigdy nie konstruuj ani nie dekoduj kursorów samodzielnie. Wiadomości w obrębie każdej zwróconej strony są uporządkowane od najstarszych do najnowszych.

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

Brak konwersacji API v2 skutkuje błędem 404 RESOURCE_NOT_FOUND; nieprawidłowe wartości limit i cursor skutkują błędem 400 VALIDATION_INVALID_BODY.

Ponawianie odpowiedzi asystenta

Ścieżka: /api/v2/agents/{agentId}/conversations/{conversationId}/retry

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}. Konwersacja musi być konwersacją API v2.

Ponowna próba usuwa poprzedzającą wiadomość użytkownika, wybraną odpowiedź asystenta oraz każdą późniejszą wiadomość, a następnie odtwarza tekst tej wiadomości użytkownika, aby wygenerować odpowiedź na nowo. Jeśli zapis zregenerowanej odpowiedzi się nie powiedzie, usunięte wiersze zostają przywrócone.

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

Sukces: 200 OK. Przy stream: true odpowiedź jest strumieniem zdarzeń Server-Sent Events w tym samym formacie zdarzeń co czat. Przy stream: false odpowiedź wygląda następująco:

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

Zniekształcony JSON skutkuje błędem 400 VALIDATION_INVALID_JSON. Nieprawidłowa treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY. Zobacz CHAT_RETRY_MESSAGE_NOT_FOUND, CHAT_RETRY_NO_USER_MESSAGE, RESOURCE_NOT_FOUND i INTERNAL_SERVER_ERROR w katalogu błędów.

Przesyłanie wyniku narzędzia

Ścieżka: /api/v2/agents/{agentId}/conversations/{conversationId}/tool-result

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

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

Odpowiedź: Pasująca oczekująca akcja jest przejmowana tylko raz, a kontynuacja jest zwracana jako text/event-stream. Nieznane lub wygasłe wywołania zwracają 404; konkurencyjne albo sprzeczne wyniki zwracają 409.

Ustawianie lub czyszczenie informacji zwrotnej o wiadomości

Ścieżka: /api/v2/agents/{agentId}/conversations/{conversationId}/messages/{messageId}/feedback

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}. Konwersacja musi być konwersacją API v2.

{messageId} musi dać się przekonwertować na dodatnią liczbę całkowitą i musi identyfikować wiadomość asystenta AI w podanej konwersacji.

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

Sukces: 200 OK

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

Zniekształcony JSON skutkuje błędem 400 VALIDATION_INVALID_JSON; nieprawidłowa treść żądania skutkuje błędem 400 VALIDATION_INVALID_BODY; brak konwersacji skutkuje błędem 404 RESOURCE_NOT_FOUND; brak wiadomości skutkuje błędem 404 RESOURCE_MESSAGE_NOT_FOUND; a wskazanie celu, który nie jest wiadomością asystenta AI, skutkuje błędem 422 RESOURCE_MESSAGE_NOT_ASSISTANT.

Lista konwersacji użytkownika

Ścieżka: /api/v2/agents/{agentId}/users/{userId}/conversations

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

Uwierzytelnianie: klucz API typu Bearer z dostępem do {agentId}.

{userId} musi mieć od 1 do 128 znaków i może zawierać wyłącznie litery, cyfry, ., _ oraz -.

Wyłącznie czat API v2 zapisuje userId, dlatego ten punkt końcowy zwraca tylko konwersacje API v2. Jego odpowiedź w przypadku powodzenia ma tę samą stronicowaną otoczkę z podsumowaniami konwersacji co Lista konwersacji.

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

Sukces: 200 OK. Nieprawidłowe identyfikatory użytkowników, wartości limit, cursor lub nieprawidłowe użycie source skutkują błędem 400 VALIDATION_INVALID_BODY.

Powiązane materiały

• Przegląd API v2 i czat
• Katalog błędów API v2
• Kontakty i zweryfikowana tożsamość