Centrum Pomocy
Chat API

Bot Talk API

Ostatnia aktualizacja:

Bot Talk API

Bot Talk API to interfejs REST API służący do komunikacji z jednym, konkretnym chatbotem z poziomu Twojej własnej aplikacji - dedykowanych aplikacji, narzędzi wewnętrznych lub tworzonych przez Ciebie automatyzacji. Tworzysz klucz API w zakładce bota API, a następnie wywołujesz punkt końcowy czatu z tym kluczem przekazanym jako token Bearer, aby otrzymywać odpowiedzi bota - w postaci pojedynczej odpowiedzi lub strumieniowo przez SSE.

Pierwsze kroki

  1. Wybierz swojego chatbota i przejdź do zakładki API u góry strony bota (Select Bot > API [Wybierz bota > API]).

Zakładka Bot Talk API

  1. Kliknij Create API Key (Utwórz klucz API).

Zakładka API z wyróżnionym przyciskiem Create API Key

Licznik obok przycisku pokazuje, ile kluczy jest aktywnych („1 of 5 API keys active”). Link View API Documentation (Wyświetl dokumentację API) otwiera tę dokumentację, a fragment kodu curl w sekcji Quick Start (Szybki start) zapewnia gotowy do uruchomienia przykład.

  1. W oknie dialogowym Create API Key (Utwórz klucz API) nadaj kluczowi nazwę, opcjonalnie ustaw białą listę IP oraz limit zapytań (rate limit), wybierz odpowiednie uprawnienia, a następnie kliknij Create (Utwórz).

Okno dialogowe Create API Key

  1. Skopiuj pełny klucz z okna potwierdzenia. Zwykły tekst jest wyświetlany tylko raz.

Klucz ma postać zbliżoną do ck_abcdefghijklmnopqrstuvwxyz012345. Każdy klucz jest przypisany do tego jednego bota, więc każde żądanie wykonane z jego użyciem komunikuje się z tym botem - bot jest identyfikowany za pomocą klucza i nigdy nie pojawia się w adresie URL.

Bazowy adres URL

https://api.chatlab.com/aichat

Wszystkie punkty końcowe w tym artykule są względne wobec tego bazowego adresu URL.

Uprawnienia klucza

Każdy klucz posiada jedno lub oba poniższe uprawnienia, ustawiane za pomocą przełączników w oknie dialogowym Create API Key:

  • Chat (send messages and receive responses) [Czat (wysyłanie wiadomości i odbieranie odpowiedzi)] - zezwala na korzystanie z punktów końcowych /v1/chat oraz /v1/chat/stream.
  • Conversation history (list and read past conversations) [Historia rozmów (wyświetlanie listy i odczyt wcześniejszych rozmów)] - zezwala na korzystanie z punktów końcowych /v1/conversations.

W zakładce API przyznane uprawnienia każdego klucza są widoczne w postaci plakietek Chat i Conversations.

Uwierzytelnianie

Przesyłaj klucz w nagłówku Authorization przy każdym żądaniu:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Żądania bez nagłówka Authorization: Bearer ... zwracają błąd 401 missing_api_key. Nieznane klucze zwracają 401 invalid_api_key, a unieważnione klucze zwracają 401 revoked_api_key. Pięć nieudanych prób w ciągu minuty z tego samego adresu IP uruchamia blokadę na 60 minut.

Limity

  • Maksymalnie 5 aktywnych kluczy Bot Talk na bota
  • Maksymalnie 60 żądań na minutę na klucz (algorytm token bucket, pojemność 60, płynne uzupełnianie w tempie 1 tokena na sekundę). Wartość można zmniejszyć podczas tworzenia - ustaw niższy parametr rateLimitPerMinute, a górny limit spadnie, wraz z proporcjonalnym dostosowaniem tempa uzupełniania.
  • Maksymalna długość wiadomości to 4000 znaków
  • Liczba jednoczesnych strumieni SSE na klucz zależy od limitów Twojego konta

Punkty końcowe

POST /v1/chat

Wysyła wiadomość do bota i odbiera pełną odpowiedź w pojedynczej strukturze JSON.

Treść żądania

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - wymagany ciąg znaków, maks. 4000 znaków.
  • conversationId - opcjonalny identyfikator UUID. Pomiń w przypadku nowej rozmowy; użyj ponownie wartości zwróconej wcześniej przez serwer, aby dopisać wiadomość do istniejącej rozmowy.
  • metadata - opcjonalny obiekt: {source, userName, userEmail, userPhone}. Pole userEmail jest również używane do wygenerowania wewnętrznego identyfikatora klienta.

Treść odpowiedzi (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • Pole message.role zawsze ma wartość "assistant", a message.content zawiera pełną odpowiedź.
  • Pole model to identyfikator modelu, na którym bot pracował podczas tego wywołania.
  • Pole usage.creditsUsed uwzględnia wiadomość użytkownika + odpowiedź bota (zazwyczaj 2), powiększone o jeden dodatkowy kredyt za każde zrealizowane wywołanie narzędzia.
  • Pole actions zawiera listę wywołań narzędzi, które zostały uruchomione w tej turze. Obecnie zwracane są wyłącznie wpisy function_call (z polami type, name, status: "completed").

POST /v1/chat/stream

Strumieniowy wariant punktu /v1/chat. Zwraca nagłówek Content-Type: text/event-stream z wykorzystaniem technologii Server-Sent Events.

Treść żądania

Taka sama struktura jak w przypadku POST /v1/chat. Flaga stream w treści nie jest wymagana - to użycie tej ścieżki aktywuje SSE.

Treść odpowiedzi (zdarzenia SSE)

  • message.delta - fragment treści { "content": "..." }. Wiele takich fragmentów jest przesyłanych strumieniowo w miarę napływania kolejnych tokenów.
  • action - wywołanie narzędzia { "type", "name", "status": "executing" }. Emitowane w momencie, gdy bot uruchamia wywołanie funkcji.
  • message.done - zdarzenie końcowe zawierające conversationId, model, usage oraz (jeśli wystąpiły) listę ukończonych akcji actions.
  • error - wysyłane w przypadku niepowodzenia generowania odpowiedzi; po nim następuje zakończenie strumienia.

Komentarze podtrzymujące połączenie SSE (:keepalive) są wysyłane co 15 sekund podczas długiego procesu generowania. Limity czasu po stronie serwera: 30 sekund na pierwszy token, 120 sekund łącznie na cały strumień.

Przykład wywołania curl

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Zwraca listę rozmów bota powiązanego z Twoim kluczem, ze wszystkich źródeł (widget, WhatsApp, API itp.).

Parametry zapytania

  • limit - od 1 do 100, domyślnie 20. Wartości spoza zakresu są automatycznie przycinane.
  • cursor - nieprzejrzysta wartość zwracana w polu nextCursor na poprzedniej stronie. Pomiń w przypadku pierwszej strony.

Treść odpowiedzi (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • Pole lastMessagePreview jest skracane do 100 znaków i uzupełniane przyrostkiem ....
  • Pole nextCursor ma wartość null na ostatniej stronie; przekaż je jako cursor, aby pobrać kolejną stronę.

GET /v1/conversations/{conversation_id}

Pełna historia rozmowy.

Treść odpowiedzi (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Zwracane są wyłącznie role user oraz assistant; wewnętrzne wiadomości typu system oraz wiadomości narzędzi są odfiltrowywane. Zwraca błąd 404 not_found_error, jeśli rozmowa nie należy do bota powiązanego z Twoim kluczem.

Aby sprawdzić konfigurację bota, użyj punktu końcowego Management API GET /v1/management/bots/{bot_id} z kluczem Management API.

Nagłówki limitu zapytań (rate limit)

Odpowiedzi, które dotrą do etapu sprawdzania limitów (tj. po pomyślnym uwierzytelnieniu i weryfikacji białej listy IP), zawierają nagłówki:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limit na dany klucz faktycznie zastosowany do tego wywołania (domyślnie 60 lub skonfigurowana niższa wartość rateLimitPerMinute).
  • X-RateLimit-Remaining - liczba tokenów pozostałych w puli bezpośrednio po tym wywołaniu.
  • X-RateLimit-Reset - czas w sekundach uniksowych (Unix epoch), w którym dostępny będzie następny token (nie oznacza pełnego zresetowania puli; pula uzupełnia się w sposób ciągły). Gdy pula jest pełna, wartość ta odpowiada bieżącemu czasowi.

W przypadku odpowiedzi 429 rate_limit_exceeded ustawiany jest także nagłówek Retry-After, wyrażony w pełnych sekundach pozostałych do momentu zwolnienia co najmniej jednego tokena.

Błędy poprzedzające uwierzytelnienie (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) oraz 403 ip_not_whitelisted nie zawierają nagłówków X-RateLimit-* - mechanizm limitowania jest odpytywany dopiero po pomyślnym zakończeniu uwierzytelnienia i weryfikacji adresu IP.

Format błędów

Wszystkie błędy korzystają ze wspólnej struktury:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Typowe kody HTTP:

  • 400 invalid_request_error - nieprawidłowe dane wejściowe (kody: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - brakujący klucz (missing_api_key), nieznany klucz (invalid_api_key) lub unieważniony klucz (revoked_api_key)
  • 402 quota_exceeded_error - wyczerpano kredyty na wiadomości
  • 403 permission_error - zablokowany adres IP (ip_blocked), adres IP spoza białej listy klucza (ip_not_whitelisted) lub typ klucza niezezwalający na dostęp do tego punktu końcowego (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - rozmowa nie należy do tego bota
  • 405 invalid_request_error (method_not_allowed) - nieprawidłowa metoda HTTP pod danym adresem URL
  • 429 rate_limit_error - zbyt wiele żądań (rate_limit_exceeded) lub zbyt wiele równoczesnych strumieni (concurrent_streams_exceeded)
  • 500 api_error - błąd wewnętrzny serwera

Powiązane tematy

Informacje na temat operacji na poziomie konta (tworzenie botów, aktualizacja botów, pobieranie danych o zużyciu) znajdziesz w dokumentacji Management API.

Szukaj we wszystkich artykułachZapytaj agenta