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).

Podświetlona zakładka API; Create API Key znajduje się w treści strony

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 curl z sekcji Quick Start (Szybki start) zawiera gotowy do uruchomienia przykład.

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

Okno dialogowe Create API Key

  1. Skopiuj pełny klucz z okna z potwierdzeniem. Klucz w postaci jawnego tekstu wyświetla się tylko raz.

Klucz wygląda jak ck_abcdefghijklmnopqrstuvwxyz012345. Każdy klucz jest przypisany do jednego konkretnego bota, więc każde żądanie wysłane z tym kluczem łączy się z tym botem - bot jest identyfikowany przez klucz i nigdy nie pojawia się w adresie URL.

  1. Ze swojego serwera uruchom poniższy przykład curl, używając swojego klucza i krótkiej wiadomości testowej. Zapisz zwrócony conversationId, a następnie użyj go ponownie do kolejnej wiadomości. Potwierdź odpowiedź i rozmowę w zakładce bota Chatlogs (historia rozmów).

Przechowuj klucze ck_ na swoim serwerze, a nie w kodzie JavaScript strony ani w paczkach aplikacji mobilnych. Uprawnienie Conversations (Rozmowy) daje dostęp do zapisanych rozmów tego bota ze wszystkimi odwiedzającymi, dlatego Twoja aplikacja musi autoryzować każdego użytkownika końcowego przed zwróceniem tych danych. Użyj opcji Revoke (Odwołaj) lub Delete (Usuń) w zakładce API, aby wycofać klucz; żadna z tych akcji nie wyświetli ponownie jego jawnej postaci.

Zanim zaczniesz, utwórz i wytrenuj swojego chatbota oraz sprawdź, czy Twoje konto obejmuje dostęp do API i ma kredyty wiadomości.

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 4 000 znaków
  • Liczba jednoczesnych strumieni SSE na klucz zależy od limitów Twojego konta

Punkty końcowe

POST /v1/chat

Wyślij wiadomość do bota i odbierz pełną odpowiedź w pojedynczej odpowiedzi JSON.

Ciało żą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. 4 000 znaków.
  • conversationId - opcjonalny 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 przyjmujący {source, userName, userEmail, userPhone}. Obecnie używane jest tutaj tylko pole userEmail, służące do wyprowadzenia identyfikatora klienta; kanał jest rejestrowany jako API. Nie polegaj na zapisywaniu pozostałych pól metadanych w rekordzie leada.

Ciało odpowiedzi (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role ma zawsze wartość "assistant"; message.content zawiera pełną odpowiedź.
  • model to identyfikator modelu, na którym bot działał podczas tego wywołania.
  • usage.creditsUsed raportuje obecnie 2 plus jeden na każde zgłoszone wywołanie narzędzia dla ukończonej tury. Ten licznik w odpowiedzi nie uwzględnia mnożników kredytów dla modelu/kontekstu i nie może służyć jako rejestr rozliczeniowy. Użyj danych o zużyciu z Management API, aby sprawdzić zużycie na koncie, oraz zobacz kredyty wiadomości.
  • actions zawiera listę wykonań narzędzi uruchomionych podczas tej tury. Obecnie emitowane są wyłącznie wpisy function_call (z polami type, name, status: "completed").

POST /v1/chat/stream

Wariant strumieniowy /v1/chat. Zwraca Content-Type: text/event-stream z wykorzystaniem Server-Sent Events (SSE).

Ciało żądania

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

Ciało odpowiedzi (zdarzenia SSE)

  • message.reset - odrzuć tekst zgromadzony dla bieżącej odpowiedzi i zacznij ponownie zbierać fragmenty delta. Może się to zdarzyć przy ponownym uruchomieniu generowania; dołączenie obu wersji spowodowałoby wyświetlenie zduplikowanej lub zastąpionej odpowiedzi.
  • message.delta - fragment treści { "content": "..." }. Wiele takich zdarzeń przesyłanych jest strumieniowo w miarę napływania tokenów.
  • action - wykonanie narzędzia { "type", "name", "status": "executing" }. Emitowane, gdy bot wywołuje funkcję.
  • message.done - zdarzenie końcowe z polami conversationId, model, usage oraz (jeśli występują) listą ukończonych akcji actions.
  • error - wysyłane, jeśli generowanie zakończy się niepowodzeniem; strumień zostaje następnie przerwany.

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

Przykład 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 dla bota powiązanego z Twoim kluczem, ze wszystkich źródeł (widget, WhatsApp, API itp.).

Parametry zapytania

  • limit - 1-100, domyślnie 20. Wartości spoza zakresu są ograniczane do dozwolonych granic.
  • cursor - nieprzejrzysta wartość zwrócona w polu nextCursor na poprzedniej stronie. Pomiń dla pierwszej strony.

Ciało 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
}
  • lastMessagePreview jest skracane do 100 znaków z przyrostkiem ....
  • nextCursor ma wartość null na ostatniej stronie; przekaż je jako cursor, aby pobrać kolejną.

GET /v1/conversations/{conversation_id}

Zachowane wiadomości z rozmowy udostępniane przez ten punkt końcowy.

Ciało 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 i assistant; wewnętrzne wiadomości system oraz wiadomości narzędzi są odfiltrowywane. Zwraca 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 odpowiedzi:

{
  "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 (invalid_parameter)
  • 415 invalid_request_error - nieobsługiwany typ zawartości (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 wiadomości
  • 403 permission_error - zablokowany adres IP (ip_blocked), adres IP spoza białej listy klucza (ip_not_whitelisted) lub typ klucza nie pozwala na korzystanie z 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 dla tego adresu URL
  • 429 rate_limit_error - zbyt wiele żądań (rate_limit_exceeded) lub zbyt wiele jednoczesnych strumieni (concurrent_streams_exceeded)
  • 500 api_error - błąd wewnętrzny

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