API v2

API v2 to ustrukturyzowane REST API do zarządzania agentami i tworzenia niestandardowych rozwiązań czatu. Dodaje ono zarządzanie agentami, przesyłanie strumieniowe czatu, historię konwersacji, informację zwrotną o wiadomościach, kontakty, leady, źródła, ustawienia oraz punkty końcowe trenowania.

Dostęp do API wymaga planu Hobby lub wyższego z aktywnymi rozliczeniami.

Bazowy adres URL

https://your-domain.com/api/v2

Uwierzytelnianie

Z wyjątkiem kontroli stanu usługi, wysyłaj klucz API swojego obszaru roboczego jako token typu bearer:

Authorization: Bearer YOUR_API_KEY

Twórz i unieważniaj klucze API w sekcji Ustawienia > Klucze API.

Format odpowiedzi

Większość odpowiedzi w przypadku powodzenia zwraca obiekt zasobu albo otoczkę data:

{
  "data": []
}

Punkty końcowe zwracające listy stosują paginację kursorową:

{
  "data": [],
  "pagination": {
    "cursor": null,
    "hasMore": false,
    "total": 0
  }
}

Błędy wykorzystują ustrukturyzowany obiekt error:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Każda odpowiedź v2 zawiera nagłówek x-request-id. Podaj go w kontakcie z pomocą techniczną w sprawie żądania API.

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.

Stan usługi

GET /api/v2/health

Kontrola stanu usługi nie wymaga uwierzytelnienia.

Sukces: 200 OK

{
  "status": "ok",
  "timestamp": 1784332800
}

timestamp to bieżący znacznik czasu Unix w sekundach.

Czat

POST /api/v2/agents/{agentId}/chat

Żądanie:

{
  "message": "What plans do you offer?",
  "conversationId": "optional-existing-conversation-id",
  "userId": "optional-user-id",
  "stream": true
}

Odpowiedzi strumieniowe wykorzystują zdarzenia Server-Sent Events. Strumień zawiera zdarzenia message-start, text-start, text-delta, text-end, message-metadata, finish oraz [DONE]. Błąd strumienia lub hooka kończącego emituje zdarzenie error z error.code ustawionym na CHAT_STREAMING_ERROR; ten kod dotyczy wyłącznie protokołu SSE i jest niezależny od ustrukturalnego katalogu błędów REST. message-metadata zawiera identyfikator wiadomości asystenta, jeśli zapis się powiódł, a także identyfikator konwersacji, identyfikator użytkownika, przyczynę zakończenia oraz zużycie. Jego pole messageId ma wartość null, gdy żadna wiadomość asystenta nie została zapisana. Gdy odpowiedź zatrzymuje się na akcji po stronie klienta, strumień emituje także zdarzenie tool-call z { "id", "name", "arguments" }; prześlij wynik do endpointu tool-result, aby wznowić konwersację — odpowiedź na to żądanie strumieniuje kontynuację.

Odpowiedzi bez przesyłania strumieniowego zwracają:

{
  "data": {
    "id": "123",
    "role": "assistant",
    "parts": [{ "type": "text", "text": "..." }],
    "pendingToolCall": null,
    "metadata": {
      "userMessageId": "122",
      "conversationId": "abc123",
      "userId": "user_123",
      "finishReason": "stop",
      "usage": { "credits": 1 }
    }
  }
}

W odpowiedziach bez przesyłania strumieniowego wartości data.id oraz metadata.userMessageId to liczbowe identyfikatory wiadomości zserializowane jako ciągi znaków, lub null, gdy odpowiadająca wiadomość nie została zapisana. metadata.userId to podany lub zapisany identyfikator użytkownika, albo null. pendingToolCall ma wartość null, chyba że odpowiedź została wstrzymana na wywołaniu narzędzia po stronie klienta; wówczas zawiera { "id", "name", "arguments" } dla endpointu wyników narzędzi.

Podsumowanie punktów końcowych

Informacja zwrotna

Użyj informacji zwrotnej, aby oznaczyć wiadomości asystenta API v2 jako positive, negative lub null. Schemat żądania, odpowiedź oraz zachowanie w przypadku błędów opisano w sekcji Konwersacje, wiadomości i informacje zwrotne.

Paginacja

Traktuj kursory jako nieprzejrzyste tokeny zwracane przez API. W kolejnym żądaniu prześlij wartość pagination.cursor bez zmian; nie konstruuj jej ani nie dekoduj.

Kontakty akceptują dodatkowo parametr search. Leady akceptują inkluzywne filtry dat i godzin w formacie ISO 8601: createdAfter oraz createdBefore. Źródła akceptują sourceType z wartościami web_crawl, file_upload, text_snippet lub qna_entry.

Format kursora jest wewnętrznym szczegółem implementacji. Klienci muszą traktować każdy kursor jako nieprzejrzysty i przesyłać go bez zmian, bez konstruowania ani dekodowania.

Najczęstsze błędy

Pełny wykaz wszystkich 27 zadeklarowanych kodów, statusów HTTP, wyzwalaczy oraz kodów zarezerwowanych znajdziesz w pełnym katalogu błędów API v2.

Materiały źródłowe

• Katalog błędów
• Agenci i ustawienia
• Konwersacje, wiadomości, ponowienia prób i informacje zwrotne
• Źródła i trenowanie
• Kontakty i leady
• Kanał Instagram

Kolejne kroki

• Utwórz klucz API
• Skonfiguruj weryfikację tożsamości
• Przejrzyj błędy API v2
• Zarządzaj agentami i ustawieniami
• Pracuj z konwersacjami
• Zarządzaj źródłami i trenowaniem
• Zarządzaj kontaktami i leadami
• Zarządzaj kanałem Instagram