Management API

Przegląd Management API

Management API służy do prac administracyjnych (back-office), które nie obejmują wysyłania wiadomości na czacie:

• programowe tworzenie bota za pomocą POST /v1/management/bots
• odczyt konkretnego bota, którego jesteś właścicielem, za pomocą GET /v1/management/bots/{bot_id}
• aktualizacja konkretnego bota za pomocą PATCH /v1/management/bots/{bot_id}
• odczyt wykorzystania subskrypcji za pomocą GET /v1/usage

Klucze Management są powiązane z Twoim kontem, a nie z żadnym konkretnym botem. Są one celowo odseparowane od kluczy Bot Talk, dzięki czemu przejęty klucz czatu nie może modyfikować Twoich botów ani odczytywać danych rozliczeniowych.

Podstawowy adres URL (Base URL)

https://api.chatlab.com/aichat

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

Pierwsze kroki

1. Otwórz panel administracyjny i przejdź do Account Settings > Management API (Ustawienia konta > Management API).
2. Kliknij Create Management Key (Utwórz klucz Management), nadaj mu nazwę, opcjonalnie ustaw białą listę IP oraz limit zapytań (rate limit), a następnie zatwierdź.
3. Wybierz tylko te uprawnienia, których potrzebuje Twoja integracja, i skopiuj pełny klucz z okna z potwierdzeniem. Klucz w postaci jawnego tekstu jest wyświetlany tylko raz.
4. Zapisz go na swoim serwerze, a nie w kodzie przeglądarki ani w publicznym repozytorium. Wykonaj zapytanie tylko do odczytu, takie jak GET /v1/usage z uprawnieniem usage, aby zweryfikować dostęp.
5. Unieważnij nieużywane lub naruszone klucze na stronie Management API.

Klucz wygląda następująco: mk_abcdefghijklmnopqrstuvwxyz012345. Prefiks mk_ odróżnia go od kluczy Bot Talk (ck_).

Uwierzytelnianie

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Wysłanie klucza mk_ do /v1/chat (lub dowolnego innego punktu końcowego Bot Talk) zwraca błąd 403 key_type_not_allowed. Wysłanie klucza ck_ do /v1/management/* zwraca ten sam błąd.

Limity

• Maksymalnie 5 aktywnych kluczy Management API na użytkownika
• Maksymalnie 10 żądań na minutę na klucz (algorytm token bucket, pojemność 10, płynne uzupełnianie w tempie ~1 token co 6 sekund). Możliwość zmniejszenia limitu w momencie tworzenia - ustaw niższą wartość rateLimitPerMinute, a limit spadnie, a tempo uzupełniania odpowiednio się przeskaluje.

Uprawnienia

Każdy klucz Management posiada dowolny podzbiór trzech poniższych uprawnień. Co najmniej jedno musi zostać wybrane podczas tworzenia; w przeciwnym razie żądanie zostanie odrzucone z błędem 400 invalid_request_error. Wywołanie punktu końcowego z kluczem, który nie posiada wymaganego uprawnienia, zwraca 403 insufficient_permissions.

• bot_read - wymagane dla GET /v1/management/bots/{bot_id}
• bot_management - wymagane dla POST /v1/management/bots oraz PATCH /v1/management/bots/{bot_id}
• usage - wymagane dla GET /v1/usage

Struktura treści: zagnieżdżone sekcje odzwierciedlające zakładki interfejsu administracyjnego

POST i PATCH przyjmują treść JSON podzieloną na 13 sekcji. Każda sekcja odpowiada podzakładce w pasku bocznym Bot Settings (Ustawienia bota) w panelu administracyjnym, dzięki czemu klucze JSON pokrywają się z widocznymi zakładkami: jeśli zmienisz consent.humanSupportRequirePolicyAccept przez API, zobaczysz przełączenie tego samego przełącznika w zakładce Consent & Privacy (Zgoda i prywatność) w panelu administracyjnym.

• role - persona bota, surowy prompt, długość odpowiedzi, język, kontekst strony / firmy (zakładka Role & Behavior)
• conversation - wiadomość powitalna, doprecyzowywanie zapytań, ciągłość rozmowy, przełącznik oceniania + podpowiedzi, treść sugerowanych pytań + dynamiczne pytania uzupełniające (zakładka Chat Conversation)
• chatMemory - przełącznik pamięci czatu, prompty podsumowań, alokacja kontekstu (zakładka Summaries & Memory)
• appearance - kolory, teksty, wymiary, własny CSS, ekran powitalny, styl sugerowanych pytań, zachowanie automatycznego otwierania, symulacja pisania przez człowieka, stopka w markdownie (zakładka Appearance)
• humanSupport - formularz kontaktu z człowiekiem (zakładka Human Contact Form)
• leadCollection - formularz pozyskiwania leadów (zakładka Lead Collection)
• liveChat - przekazywanie do Live Chat (zakładka Live Chat)
• consent - wszystkie cztery przełączniki zgody na politykę prywatności oraz treść ekranu zgody (zakładka Consent & Privacy)
• whiteLabel - ukrywanie logo, własny link do logo, hosting we własnej domenie (zakładka Whitelabel)
• security - dozwolone domeny, filtr antyspamowy, limity częstotliwości rozmów (zakładka Security)
• voice - wprowadzanie głosowe i rozmowy głosowe: model, głos, języki, prompt, limit czasu trwania (zakładka Voice Conversation)
• multilingual - tryb wielojęzyczny, język podstawowy, oferowane języki, obsługa języka bazy wiedzy (zakładka Languages)
• advanced - model LLM, temperatura, rozmiar kontekstu, limit wiadomości bota, wewnętrzne ustawienia regionalne, Offer Cards (zakładka Model & Advanced)

Wśród zapisywalnych ustawień tylko name znajduje się na najwyższym poziomie, ponieważ identyfikuje bota, zamiast należeć do konkretnej zakładki.

Pasek boczny Bot Settings ma obecnie 16 podzakładek, a 13 z nich odpowiada powyższym sekcjom. Trzy podzakładki bez odpowiadającej im sekcji to Flow, Actions oraz Forms - wszystkie trzy omówiono w sekcji "Poza zakresem API" poniżej. 13 zakładek, które mają swoje odpowiedniki, to Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation oraz Languages.

Treść żądania i treść odpowiedzi mają tę samą strukturę. Odpowiedź zawiera dwa dodatkowe elementy:

• meta - tylko do odczytu: identyfikator bota i znaczniki czasu. Usuń go, aby przekształcić odpowiedź GET w prawidłową treść POST.
• apiKey - obecny tylko podczas tworzenia - nowo wygenerowany klucz Bot Talk API dla nowego bota.

Dwa pola w ramach wspólnej struktury są tylko do odczytu - zwracane w odpowiedzi, ignorowane przy próbie wysłania ich w POST/PATCH:

• appearance.avatarUrl - w pełni kwalifikowany publiczny adres URL obrazu awatara bota (np. https://api.chatlab.com/aichat/content/avatar_xyz.png). Pobierz go bezpośrednio metodą GET, aby zapisać plik. Aby go zmienić, prześlij nowy plik za pomocą części wieloczęściowej avatar (zobacz PATCH).
• whiteLabel.whitelabelLogoUrl - w pełni kwalifikowany publiczny adres URL logo nagłówka White Label. Taki sam schemat jak w avatarUrl. Aby go zmienić, prześlij nowy plik za pomocą części wieloczęściowej whitelabel_logo (zobacz PATCH).

Oba adresy URL używają schematu + hosta + ścieżki kontekstu bieżącego żądania, więc w przypadku domeny niestandardowej White Label są zwracane z tą domeną jako adresem bazowym (np. https://api.acme.com/aichat/content/...).

Wyślij null dla sekcji, aby pominąć ją przy PATCH; wyślij null dla pola wewnątrz sekcji, aby pominąć tylko to pojedyncze pole. Wartość null na poziomie pola nigdy nie czyści zapisanej wartości - oznacza jedynie "nie modyfikuj".

Konstrukcja roli i promptu

Prompt systemowy, który ostatecznie otrzymuje LLM, jest budowany na jeden z dwóch sposobów w zależności od role.role. Świadomość wybranej ścieżki pozwala określić, które pola mają znaczenie, a które są zapisywane, ale ignorowane.

Ścieżka A - role.role to CUSTOMER_SUPPORT, SALES lub LEAD_COLLECTION_AGENT (oparta na szablonie)

Backend składa prompt z wbudowanego szablonu i całkowicie ignoruje role.rawPrompt (wartość ta jest nadal zapisana przy bocie, lecz nieużywana). Szablon uwzględnia:

• role.role - etykietę roli (np. "Customer Support") oraz instrukcje specyficzne dla roli dołączane automatycznie
• name - nazwę bota, wstawianą do zdania początkowego
• role.language - "Auto Detect" przestawia bota na podążanie za językiem użytkownika; każda inna wartość (np. "English", "Polish") staje się instrukcją "Output in {language}, unless user uses another language"
• role.responseLength - mapowane na docelową liczbę słów: Concise ≈ 50 słów, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - opcjonalne; jeśli nie jest puste, dodawane jako "for the users of the website {url}"
• role.companyDescription - opcjonalne; jeśli nie jest puste, dołączane na początku jako dodatkowy akapit przed instrukcjami roli

Jest to ścieżka zalecana dla większości botów - bez dodatkowej pracy otrzymujesz zachowanie dopasowane do roli oraz mechanizmy bezpieczeństwa.

Ścieżka B - role.role to CUSTOM (prompt dostarczony przez wywołującego)

Backend używa role.rawPrompt jako promptu roli i dołącza stałe wytyczne platformy dotyczące długości odpowiedzi. Działa to niezależnie od role.responseLength: opcjonalne ustawienie Concise/Normal/Detailed nie jest wstrzykiwane dla roli CUSTOM. Podobnie language, websiteAddress oraz companyDescription są zapisywane, ale nie trafiają do tego promptu roli. Wszelkie wymagania dotyczące języka, docelowej długości odpowiedzi czy kontekstu firmy należy umieścić bezpośrednio w rawPrompt. Dodatkowe instrukcje wykonawcze i pobrany kontekst również mogą zostać dostarczone, więc rawPrompt nie stanowi całego wejścia modelu. Instrukcje tonu predefiniowanej roli nie są dodawane, ale wybranie CUSTOM nie usuwa wszystkich instrukcji platformy.

Używaj CUSTOM tylko wtedy, gdy prompt oparty na szablonie nie pasuje do Twojego przypadku użycia (np. potrzebujesz wysoce specyficznej persony branżowej, własnych ograniczeń bezpieczeństwa lub niestandardowego formatu danych wyjściowych).

Pola wyliczeniowe / o ograniczonym zbiorze wartości

Pola wyliczeniowe i ograniczone odrzucają nieprawidłowe wartości kodem 400 invalid_parameter. Inne pola to zwykłe ciągi znaków, nawet jeśli interfejs oferuje stałą listę. Używaj udokumentowanej pisowni i waliduj przesyłane dane zamiast zakładać, że każdy nieobsługiwany ciąg zostanie odrzucony.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - pełna angielska nazwa języka z listy rozwijanej w panelu administracyjnym, np. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi oraz około 80 innych. Wartość jest zapisywana dosłownie i wstawiana do szablonu promptu, więc dwuliterowe kody ISO (en, pl) i inne wartości spoza listy nie są odrzucane przez API, ale powodują wygenerowanie zniekształconej instrukcji, takiej jak "Output in en, unless...". Domyślnie Auto Detect, jeśli zostanie pominięte podczas tworzenia.
• advanced.model - zobacz "Modele tekstowe AI" poniżej. Jest to ciąg znaków, a nie zweryfikowany enum w schemacie żądania; użyj obsługiwanej wartości, a nie dowolnej nazwy modelu.
• advanced.chatContextSize - użyj 8000, 16000 lub 32000, zgodnie z interfejsem. Wartości powyżej limitu konta są po cichu przycinane; obiekt DTO nie wymusza tego trzyelementowego zestawu.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - przełącznik logiczny. true zmusza użytkownika do wypełnienia formularza leada przed rozpoczęciem rozmowy; false pozwala sztucznej inteligencji zdecydować, kiedy wyświetlić formularz (domyślnie).

Pola ustrukturyzowane i zakresy

Pola, które wyglądają jak zwykłe ciągi znaków lub liczby, ale w rzeczywistości mają specyficzne formaty, zakresy lub specyfikę interfejsu administracyjnego, o których warto wiedzieć.

• advanced.temperature - dopuszczalny zakres to od 0.0 do 1.0, zgodnie z suwakiem w panelu administracyjnym. Wartości spoza tego zakresu są odrzucane kodem 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - wartość całkowita w procentach, 10-90; interfejs używa kroków co 10, ale API akceptuje liczby całkowite z całego zakresu. Domyślnie 50. Przy włączonej pamięci i kontekście większym niż 8k dzieli budżet wiedzy i pamięci po zarezerwowaniu miejsca na prompt i ostatnią rozmowę, a nie cały kontekst modelu. Przy 8k to ustawienie nie przydziela żadnego budżetu na podsumowania.

• liveChat.schedule - JSON zakodowany jako ciąg znaków, a nie zagnieżdżony obiekt JSON w przesyłanych danych. Serwer przechowuje surowy ciąg dosłownie; interfejs administracyjny analizuje go po stronie klienta podczas renderowania edytora harmonogramu. Po przetworzeniu ciąg ma postać jednego wpisu na każdy dzień tygodnia oraz klucza timezone:

  • każdy klucz dnia tygodnia (monday-sunday) mapuje na {enabled: boolean, from: "H:MM", to: "H:MM"} w formacie 24-godzinnym
  • timezone to nazwa strefy IANA (np. "Europe/Warsaw", "America/New_York")

  Przykładowa wartość (zwróć uwagę na cudzysłowy zewnętrzne i ucieczki cudzysłowów wewnętrznych - jest to jedno pole tekstowe, a nie obiekt zagnieżdżony):

  "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}"
  

  Poza wymienionymi godzinami odwiedzającemu wyświetla się liveChat.outOfHoursMessage, a przekazanie do czatu na żywo zostaje wstrzymane. Weryfikacja wewnętrznej struktury odbywa się wyłącznie po stronie klienta w panelu administracyjnym - nieprawidłowy format JSON lub nierozpoznane klucze zostaną zaakceptowane przez API jako zwykły ciąg tekstowy i ujawnią się jako błąd renderowania, gdy ktoś otworzy bota w panelu. Zweryfikuj strukturę po swojej stronie przed wysłaniem.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krótkie etykiety widoczne przy elementach oceniania rozmowy 👍 / 👎, gdy conversation.conversationRatingEnabled=true. Domyślny tekst to "I like the response" / "I don't like the response". Widoczne dla użytkowników końcowych.

• whiteLabel.hideRoboAssistLogo - funkcja White Label, zależna od limitów Twojego konta. Ukrywa napis "Powered by ChatLab" w stopce. Jeśli Twoje konto nie obejmuje White Label, wartość jest zapisywana, ale ignorowana, a stopka renderuje się zawsze.

• whiteLabel.whitelabelLogoLink - funkcja White Label, zależna od limitów Twojego konta. Docelowy adres URL kliknięcia dla własnego logo, gdy hideRoboAssistLogo=true i przesłano plik własnego logo za pomocą części wieloczęściowej whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nie milisekundy), liczba całkowita 0-200. Przerwa między kolejnymi dymkami bota, gdy simulateHumanTyping=true. Domyślnie 5.

• appearance.autoOpenChatDelaySeconds - sekundy, liczba całkowita. Opóźnienie przed automatycznym otwarciem widgetu, gdy autoOpenChat=true i autoOpenChatDelay=true.

• advanced.internalLocale - kod języka i regionu IETF w formacie ll_CC (ze znakiem podkreślenia, a NIE ll-CC z myślnikiem). Akceptowane wartości pochodzą ze stałej listy około 95 ustawień regionalnych: en_US, pl_PL, de_DE, fr_FR, es_ES, it_IT, pt_PT, nl_NL, ru_RU, zh_CN, zh_TW, ja_JP, ko_KR, ar_SA, hi_IN, tr_TR, cs_CZ, da_DK, fi_FI, sv_SE, no_NO, el_GR, he_IL i wielu innych. Wysłanie samego dwuliterowego kodu ("en") lub formatu BCP-47 ("en-US") nie znajduje się na liście dozwolonych wartości. Domyślnie en_US. Są to ustawienia regionalne używane do formatowania dat i liczb w interfejsie widgetu, odrębne od role.language (języka wypowiedzi bota w rozmowie).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - liczby całkowite (wysyłane jako liczby w formacie JSON, np. 30, a nie "30"). Ustaw limit wiadomości na 0, aby wyłączyć ten limit oparty na sesji. Przy włączaniu podaj dodatnią wartość czasu trwania. Backend egzekwuje N wiadomości na sesję w podanym czasie w sekundach przed wyświetleniem odwiedzającemu security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - liczba całkowita (liczba w formacie JSON, np. 1000). 0 oznacza brak dodatkowego limitu na bota, przy czym nadal obowiązuje limit kredytów konta; w przeciwnym razie musi to być wielokrotność 1000 (1000, 2000, 10000, ...). Wartości takie jak 100 lub 1500 są odrzucane kodem 400 invalid_parameter. Jest to miesięczny limit kredytów bota, a nie liczba wiadomości na rozmowę. Mechanizm mapujący nie przycina tej wartości do limitu konta; budżet konta nadal ogranicza rzeczywiste zużycie.

Modele tekstowe AI (advanced.model)

Użyj dokładnego identyfikatora modelu zwróconego w advanced.model podczas odczytu bota skonfigurowanego z wybranym modelem w sekcji Settings > Model & Advanced (Ustawienia > Model i zaawansowane). Bieżącą wartością domyślną przy tworzeniu jest 5.6-LUNA. W identyfikatorach wielkość liter ma znaczenie i różnią się one od nazw wyświetlanych; na przykład 5.6-LUNA jest wyświetlany jako GPT 5.6-luna.

Katalog modeli zmienia się z czasem. Nie zakładaj, że dowolny ciąg znaków lub publiczny identyfikator modelu dostawcy jest obsługiwany tylko dlatego, że schemat żądania przyjmuje ciąg znaków. Odczytaj zapisaną konfigurację i przetestuj utworzonego chatbota przed wdrożeniem go na środowisko produkcyjne.

Opis pól (pełny schemat żądania)

Obsługiwane sekcje i pola wraz z ich typami oraz istotnymi ograniczeniami. Semantyka PATCH: każde pominięte pole (lub przesłane jako null) pozostawia zapisaną wartość bez zmian. Taka sama struktura jest używana w odpowiedzi (z wyłączeniem binarnej zawartości multipart; z dodatkiem bloku meta tylko do odczytu w każdej odpowiedzi oraz apiKey wyłącznie w odpowiedzi na utworzenie).

Poziom główny

Pole	Typ	Ograniczenie	Opis
name	string	maks. 150, wymagane przy tworzeniu	Wyświetlana nazwa bota
role	object		Zobacz § role
conversation	object		Zobacz § conversation
chatMemory	object		Zobacz § chatMemory
appearance	object		Zobacz § appearance
humanSupport	object		Zobacz § humanSupport
leadCollection	object		Zobacz § leadCollection
liveChat	object		Zobacz § liveChat
consent	object		Zobacz § consent
whiteLabel	object		Zobacz § whiteLabel
security	object		Zobacz § security
advanced	object		Zobacz § advanced

Elementy występujące tylko w odpowiedzi:

• meta: { id, createdAt, updatedAt } - tylko do odczytu.
• apiKey - string, obecny wyłącznie w odpowiedzi POST /v1/management/bots - nowo wygenerowany klucz Bot Talk dla nowego bota, zwracany dokładnie raz.

§ role

Pole	Typ	Ograniczenie	Opis
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Szablon persony; wybiera szablon promptu (zobacz "Konstrukcja roli i promptu")
language	string	pełna angielska nazwa języka (English, Polish, ...) lub Auto Detect	Główny język przekazywany do szablonu promptu
responseLength	string	∈ {Concise, Normal, Detailed}	Pożądana szczegółowość odpowiedzi AI
websiteAddress	string		Strona internetowa używana jako kontekst promptu
companyDescription	string		Opis firmy używany jako kontekst promptu
rawPrompt	string		Własny prompt systemowy - używany dosłownie tylko wtedy, gdy role=CUSTOM

§ conversation

Pole	Typ	Ograniczenie	Opis
welcomeMessage	string		Pierwsza wiadomość pokazywana odwiedzającemu po otwarciu
queryRefinementEnabled	boolean		Jeśli true, doprecyzuj pytanie odwiedzającego przed pobraniem danych RAG
conversationContinuityEnabled	boolean		Jeśli true, powracający odwiedzający wznawiają swoją ostatnią rozmowę
conversationRatingEnabled	boolean		Jeśli true, wyświetlaj przyciski oceny rozmowy (kciuk w górę/w dół)
positiveRatingTooltip	string		Podpowiedź (tooltip) na przycisku pozytywnej oceny
negativeRatingTooltip	string		Podpowiedź (tooltip) na przycisku negatywnej oceny
suggestedQuestions	string		Sugerowane pytania / zagajenia rozmowy rozdzielone nową linią
dynamicSuggestedFollowups	boolean		Jeśli true, AI proponuje dalsze pytania po każdej odpowiedzi
positiveRatingMessage	string		Wiadomość wyświetlana po pozytywnej ocenie
negativeRatingMessage	string		Wiadomość wyświetlana po negatywnej ocenie
hideSuggestedQuestionsAfterFirstUse	boolean		Ukrywaj statyczne sugestie po ich użyciu
dynamicFollowupsAutoIcons	boolean		Jeśli true, AI automatycznie dobiera ikony emoji dla dynamicznych sugestii

§ chatMemory

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Główny przełącznik funkcji pamięci czatu
summaryConversationsEnabled	boolean		Zapisuj podsumowania poszczególnych rozmów
conversationSummaryPrompt	string		Własny prompt używany do podsumowywania każdej rozmowy
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Czy używać domyślnego, czy własnego promptu podsumowania
clientSummaryPrompt	string		Własny prompt używany do podsumowywania profilu klienta w kolejnych rozmowach
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Domyślny kontra własny prompt profilu klienta
summariesToKnowledgeRatio	int	10-90 (krok w interfejsie 10)	% dostępnego budżetu wiedzy/pamięci przydzielony na podsumowania przy kontekstach powyżej 8k

§ appearance

Pole	Typ	Ograniczenie	Opis
launcherLabelLine1	string	maks. 60	Pierwsza linia tekstu przycisku uruchamiającego (launcher)
launcherLabelLine2	string	maks. 60	Druga linia tekstu przycisku uruchamiającego (launcher)
launcherTextColor	string		Kolor tekstu przycisku uruchamiającego
launcherDismissEnabled	boolean		Zezwalaj na ukrywanie przycisku uruchamiającego
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Krój pisma widgetu
chatDrawerEnabled	boolean		Włącz prezentację w formie wysuwanego panelu (drawer)
launcherColor	string (hex)		Kolor tła przycisku uruchamiającego (ikony czatu)
headerColor	string (hex)		Kolor tła nagłówka czatu
titleColor	string (hex)		Kolor tytułu w nagłówku czatu
subtitleColor	string (hex)		Kolor podtytułu w nagłówku czatu
clientMessageBubbleColor	string (hex)		Kolor dymku wiadomości odwiedzającego
clientMessageTextColor	string (hex)		Kolor tekstu wiadomości odwiedzającego
responseMessageBubbleColor	string (hex)		Kolor dymku odpowiedzi bota
responseMessageTextColor	string (hex)		Kolor tekstu odpowiedzi bota
chatSubheader	string		Krótki opis (tagline) wyświetlany pod tytułem czatu
senderPlaceholder	string		Tekst zastępczy (placeholder) w polu wprowadzania wiadomości
resetConversationTooltip	string		Podpowiedź (tooltip) na przycisku resetowania rozmowy
chatAlignment	string (enum)	∈ {left, right}	Strona ekranu, do której jest zakotwiczony czat
launcherBottomMargin	int	0-500	Odległość przycisku uruchamiającego od dolnej krawędzi (px)
launcherSideMargin	int	0-500	Odległość przycisku uruchamiającego od bocznej krawędzi (px)
displayShadow	boolean		Cień pod widgetem
customCss	string		Kod CSS wstrzykiwany bezpośrednio do ramki iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Sposób otwierania linków w wiadomościach bota
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Stan zminimalizowany: ikona launchera, kompaktowy pasek wprowadzania lub pigułka (pill)
chatDesktopWidthPx	int		Szerokość widgetu na komputerach
chatDesktopHeightPx	int		Wysokość widgetu na komputerach
chatMobileSizePercent	int		Rozmiar widgetu na urządzeniach mobilnych jako % widoku (viewport)
messageFontSize	int		Rozmiar czcionki tekstu wiadomości (px)
showChatbotBubblesDesktop	boolean		Pokazuj pływające dymki zachęcające na komputerach
showChatbotBubblesMobile	boolean		Pokazuj pływające dymki zachęcające na urządzeniach mobilnych
chatbotBubblesDelaySeconds	int		Opóźnienie przed pojawieniem się dymków zachęcających (sekundy)
launcherIconFullSize	boolean		Renderuj własną ikonę launchera od krawędzi do krawędzi (bez marginesu wewnętrznego)
welcomeScreenEnabled	boolean		Pokazuj ekran powitalny (Welcome Screen) zamiast od razu przechodzić do czatu
welcomeScreenQuestionsLabel	string		Etykieta nad sugerowanymi pytaniami na ekranie powitalnym
welcomeScreenHideHumanContactForm	boolean		Ukryj formularz kontaktu z człowiekiem w nagłówku, dopóki wyświetlany jest ekran powitalny. Pojawia się ponownie po pierwszej wiadomości odwiedzającego. Boty utworzone przed 2026-09-02 domyślnie przyjmują wartość true
welcomeScreenHideLiveChat	boolean		Ukryj opcję czatu na żywo w nagłówku, dopóki wyświetlany jest ekran powitalny. Pojawia się ponownie po pierwszej wiadomości odwiedzającego. Boty utworzone przed 2026-09-02 domyślnie przyjmują wartość true
headerActionsLayout	string	ICONS lub DROPDOWN	Sposób udostępniania opcji Live Chat i formularza kontaktu w nagłówku czatu: ICONS (osobna ikona dla każdego) lub DROPDOWN (zgrupowane w menu nagłówka). Boty utworzone przed 2026-09-02 domyślnie przyjmują wartość ICONS
stackSuggestedQuestions	boolean		Układaj sugerowane pytania pionowo (zamiast obok siebie)
suggestedQuestionsFontSize	int		Rozmiar czcionki przycisków sugerowanych pytań (px)
suggestedQuestionsTextColor	string (hex)		Kolor tekstu przycisków sugerowanych pytań
suggestedQuestionsBackgroundColor	string (hex)		Kolor tła przycisków sugerowanych pytań
autoOpenChat	boolean		Automatycznie otwieraj czat na komputerach
autoOpenChatOnMobiles	boolean		Automatycznie otwieraj czat na urządzeniach mobilnych
autoOpenChatDelay	boolean		Stosuj opóźnienie przed automatycznym otwarciem
autoOpenChatDelaySeconds	int		Czas opóźnienia automatycznego otwarcia (sekundy)
simulateHumanTyping	boolean		Dziel odpowiedź bota na dymki z animacją pisania
simulateHumanTypingDelay	int	0-200	Odstęp czasowy między dymkami wiadomości (sekundy)
footerMarkdown	string	maks. 255	Niestandardowy tekst Markdown w stopce pod czatem
avatarUrl	string	tylko do odczytu	Pełny publiczny adres URL awatara; aby go zmienić, prześlij plik przez część multipart avatar

Multipart przy POST/PATCH: avatar (część pliku). Ciała odpowiedzi GET pomijają zawartość pliku - przesyłany jest tylko adres URL.

§ humanSupport

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik ścieżki wsparcia przez człowieka
email	string	wymagane (create-strict), gdy enabled=true	Adres odbierający wiadomości e-mail wsparcia przez człowieka
dialogMessage	string		Wiadomość zachęcająca wyświetlana nad formularzem
thankYouMessage	string		Potwierdzenie wyświetlane po przesłaniu formularza
emailMessageSubjectTemplate	string		Szablon tematu wiadomości e-mail wysyłanej do konsultanta
emailMessageContentTemplate	string		Szablon treści wiadomości e-mail wysyłanej do konsultanta
emailPlaceholder	string		Tekst zastępczy w polu e-mail
messagePlaceholder	string		Tekst zastępczy w polu wiadomości
emailWithConversationContent	boolean		Jeśli true, dołącz zapis rozmowy do treści wiadomości e-mail
customFormId	long	ID istniejącego formularza niestandardowego	Zastąp wbudowany formularz kontaktowy formularzem niestandardowym. Przy tworzeniu pominięcie powoduje użycie formularza wbudowanego; przy PATCH wartość null pozostawia bieżący wybór bez zmian
customFormMapping	string	JSON zakodowany jako ciąg znaków	Mapuje pola niestandardowego formularza na pola wiadomości e-mail wsparcia

requirePolicyAccept znajduje się w sekcji consent.humanSupportRequirePolicyAccept, a nie tutaj.

§ leadCollection

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik formularza leadów
nameEnabled	boolean		Zbieraj imię i nazwisko
nameLabel	string		Etykieta w polu imienia i nazwiska
emailEnabled	boolean		Zbieraj adres e-mail
emailLabel	string	wymagane (create-strict), gdy enabled=true ORAZ emailEnabled=true	Etykieta w polu adresu e-mail
phoneEnabled	boolean		Zbieraj numer telefonu
phoneLabel	string	wymagane (create-strict), gdy enabled=true ORAZ phoneEnabled=true	Etykieta w polu numeru telefonu
leaveDetailsMessage	string	wymagane (create-strict), gdy enabled=true	Wiadomość zachęcająca odwiedzającego do pozostawienia danych
thankYouMessage	string	wymagane (create-strict), gdy enabled=true	Potwierdzenie wyświetlane po przesłaniu formularza
requireBeforeNewConversation	boolean		Jeśli true, formularz musi zostać przesłany przed rozpoczęciem czatu; jeśli false, AI decyduje, kiedy wyświetlić formularz
emailNotificationEnabled	boolean		Wysyłaj e-mail do właściciela po każdym zebranym leadzie
emailNotificationAddress	string		Odbiorca powiadomień (domyślnie adres e-mail konta)
emailWithConversationContent	boolean		Jeśli true, dołącz zapis rozmowy do powiadomienia

| customFormId | long | ID istniejącego formularza niestandardowego | Zastąp wbudowany formularz leada formularzem niestandardowym. Przy tworzeniu pominięcie powoduje użycie formularza wbudowanego; przy PATCH wartość null pozostawia bieżący wybór bez zmian | | customFormMapping | string | JSON zakodowany jako ciąg znaków | Mapuje pola niestandardowego formularza na imię i nazwisko / e-mail / telefon |

Reguła create-strict między polami: enabled=true wymaga przynajmniej jednego z pól emailEnabled lub phoneEnabled. requirePolicyAccept znajduje się w sekcji consent.leadCollectionRequirePolicyAccept, a nie tutaj.

§ liveChat

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik funkcji Live Chat
infoMessage	string		Wiadomość wyjaśniająca przed przekazaniem rozmowy
startMessage	string		Wiadomość wyświetlana po rozpoczęciu sesji na żywo
endMessage	string		Wiadomość wyświetlana po zakończeniu sesji na żywo
nameLabel	string		Etykieta w polu imienia w formularzu wstępnym Live Chat
emailLabel	string		Etykieta w polu e-mail w formularzu wstępnym Live Chat
schedule	string	JSON zakodowany jako ciąg znaków (przełączniki dni tygodnia + from/to + timezone)	Harmonogram działania czatu na żywo - dokładną strukturę znajdziesz w sekcji "Pola ustrukturyzowane i zakresy"
outOfHoursMessage	string		Wiadomość wyświetlana, gdy harmonogram wskazuje, że zespół jest niedostępny
closeModalMessage	string		Tytuł okna modalnego "Zamknąć czat na żywo?"
closeModalConfirmLabel	string		Etykieta przycisku potwierdzenia w oknie zamykania
closeModalCancelLabel	string		Etykieta przycisku anulowania w oknie zamykania
closeModalTooltipText	string		Podpowiedź (tooltip) przycisku zamykania czatu
operatorHasJoinedLabel	string		Etykieta wyświetlana po dołączeniu operatora
operatorDidNotJoinInTimeLabel	string		Etykieta wyświetlana, gdy żaden operator nie dołączy przed upływem limitu czasu
waitingForOperatorToJoinLabel	string		Etykieta wyświetlana podczas oczekiwania na operatora
waitingForOperatorSeconds	int		Limit czasu na odebranie rozmowy przez operatora (sekundy)
redirectToHumanSupportForm	boolean		Jeśli true, przekieruj do formularza wsparcia przez człowieka, gdy żaden operator nie odbierze rozmowy
requireAdminOnline	boolean		Wymagaj obecności dostępnego operatora zgodnie z ustawieniami statusu dostępności
presenceMode	string		Tryb dostępności; użyj wartości pobranej z bota skonfigurowanego w interfejsie
hideHumanSupportWhenLiveChatAvailable	boolean		Ukrywaj formularz kontaktowy, gdy czat na żywo jest dostępny
missedEmailEnabled	boolean	domyślnie true	Wyślij e-mail do właściciela bota, gdy prośba o czat na żywo pozostała bez odpowiedzi. Niezdefiniowane w starszych botach, co oznacza stan włączony

requirePolicyAccept znajduje się w sekcji consent.liveChatRequirePolicyAccept, a nie tutaj.

§ consent

Pole	Typ	Ograniczenie	Opis
newConversationRequirePolicyAccept	boolean		Wymagaj zgody na politykę prywatności przed rozpoczęciem nowej rozmowy
humanSupportRequirePolicyAccept	boolean		Wymagaj zgody na politykę prywatności przed przesłaniem formularza wsparcia przez człowieka
leadCollectionRequirePolicyAccept	boolean		Wymagaj zgody na politykę prywatności przed przesłaniem formularza zbierania leadów
liveChatRequirePolicyAccept	boolean		Wymagaj zgody na politykę prywatności przed rozpoczęciem sesji czatu na żywo
newConversationConsentDescription	string		Tekst wstępu na ekranie zgody przy rozpoczęciu rozmowy
privacyPolicyConsentCheckboxLabel	string		Etykieta obok pola wyboru zgody (zwykle zawiera link do polityki prywatności)

§ whiteLabel

Pole	Typ	Ograniczenie	Opis
hideRoboAssistLogo	boolean	funkcja White Label; zależna od limitów konta	Ukryj domyślne logo ChatLab w stopce
whitelabelLogoLink	string	funkcja White Label; zależna od limitów konta	Adres URL, do którego prowadzi własne logo w stopce
assignToCustomDomain	boolean	wymaga funkcji CUSTOM_DOMAIN	Udostępniaj czat we własnej skonfigurowanej domenie
whitelabelLogoUrl	string	tylko do odczytu	Pełny publiczny adres URL logo White Label; aby je zmienić, prześlij plik przez część multipart whitelabel_logo

Multipart przy POST/PATCH: whitelabel_logo (część pliku). Ciała odpowiedzi GET pomijają zawartość pliku - przesyłany jest tylko adres URL.

§ security

Pole	Typ	Ograniczenie	Opis
allowedDomains	string		Rozdzielona przecinkami lista domen uprawnionych do osadzenia widgetu (puste = brak białej listy)
spamFilterEnabled	boolean		Włącz filtr antyspamowy dla wiadomości przychodzących tego bota
countryFilterMode	string	BLACKLIST lub WHITELIST	Sposób interpretacji list krajów. Same listy pozostają dostępne tylko dla administratorów
talkMessagesRateLimit	int	>= 0; 0 wyłącza	Maksymalna liczba wiadomości użytkownika dozwolona w oknie limitu zapytań (rate limit)
talkMessagesRateLimitDurationSeconds	int	>= 0	Długość okna limitu zapytań (sekundy)
talkMessagesRateLimitHitMessage	string		Wiadomość wyświetlana odwiedzającemu po osiągnięciu limitu zapytań

§ voice

Pole	Typ	Ograniczenie	Opis
inputEnabled	boolean		Pozwól odwiedzającemu dyktować wiadomości (mowa na tekst)
conversationEnabled	boolean	wymaga funkcji głosowych w planie	Włącz pełne rozmowy głosowe
voiceId	string	identyfikator głosu u dostawcy (np. alloy)	Wybór syntetycznego głosu
model	string	np. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Model głosu. Rozliczany za minutę, stawki różnią się w zależności od modelu
turnDetection	string	zależne od dostawcy	Tryb naprzemienności wypowiedzi (turn-taking)
audioPrompt	string		Dodatkowy prompt systemowy używany tylko podczas wypowiedzi głosowych
welcomeMessage	string		Odtwarzana kwestia powitalna
language	string	kod języka	Główny język głosu
additionalLanguages	string	rozdzielone przecinkami kody języków	Dodatkowe języki akceptowane przez agenta głosowego
maxDurationSeconds	int		Sztywny limit czasu trwania pojedynczej rozmowy głosowej
maxDurationMessage	string		Wiadomość wyświetlana po osiągnięciu limitu czasu

§ multilingual

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik trybu wielojęzycznego
mode	string	AUTODETECT lub FIXED_LIST	Sposób wyboru języka odpowiedzi przez bota
baseLanguage	string	kod języka	Język, w którym przygotowano treści własne bota
languages	string	rozdzielone przecinkami kody języków	Języki oferowane odwiedzającemu
knowledgeLanguageMode	string	NONE, MAIN lub DYNAMIC	Sposób traktowania bazy wiedzy w innych językach
knowledgeLanguageFallback	string	kod języka	Język używany w przypadku braku dopasowania

§ advanced

Pole	Typ	Ograniczenie	Opis
model	string	zależne od limitów konta; zobacz wyżej "Modele tekstowe AI"	Identyfikator LLM (np. 5.6-LUNA)
temperature	decimal	0.0-1.0	Temperatura próbkowania (odpowiada suwakowi w interfejsie)
chatContextSize	int	∈ {8000, 16000, 32000}; automatycznie ograniczane do limitu konta	Skonfigurowany budżet kontekstu, obejmujący instrukcje, historię i bazę wiedzy
botMessagesLimit	long	0 lub wielokrotność 1000 (np. 1000, 2000, 10000)	Miesięczny limit kredytów wiadomości bota (0 = brak dodatkowego limitu bota; nadal obowiązuje budżet konta)
internalLocale	string	kod ustawień regionalnych w formacie ll_CC	Ustawienia regionalne (locale) dla etykiet interfejsu widgetu (odrębne od role.language)
productsViewEnabled	boolean		Jeśli true, wyświetlaj karty ofert e-commerce (Offer Cards) wewnątrz czatu
includeProductsInKnowledgeBase	boolean		Jeśli true, indeksuj katalog produktów jako część bazy wiedzy

Poza zakresem API

Panel administracyjny udostępnia kilka obszarów, które celowo nie zostały udostępnione w tej wersji Management API:

• Trenowanie i usuwanie - te punkty końcowe nie pozwalają wyświetlać listy wszystkich botów, zarządzać zbiorami danych do trenowania ani usuwać botów. Do tych działań należy używać aplikacji.
• Zakładka Flow (Ścieżki) - wizualny edytor ścieżek rozmowy (Flow Editor - etapy i przejścia). Niedostępny przez Management API.
• Zakładka Actions (Akcje) - zarządzane integracje e-commerce / rezerwacji, funkcja AI Search oraz własne funkcje API. Wywoływanie narzędzi (tool calling) nigdy nie było częścią Management API.
• Sam kreator niestandardowych formularzy - tworzenie i edytowanie formularzy niestandardowych nie jest dostępne przez API. Możesz jednak przypisać istniejący formularz do bota za pomocą leadCollection.customFormId i humanSupport.customFormId.
• Własne ikony otwierania/zamykania czatu - customLauncherIconVisible, openChatIcon, closeChatIcon. API udostępnia wyłącznie główne części multipart avatar oraz whitelabel_logo.
• Listy adresów IP i krajów - same wpisy są dostępne wyłącznie dla administratorów. Udostępniony jest jedynie tryb interpretacji za pomocą security.countryFilterMode.

Punkty końcowe

POST /v1/management/bots

Utwórz nowego bota. Akceptowane są dwa równorzędne nagłówki Content-Type; wybierz ten, który jest dla Ciebie wygodniejszy.

Tryb A - zwykły JSON (zalecany, gdy nie musisz przesyłać awatara / logo w tym samym żądaniu):

• Content-Type: application/json
• Treść żądania jest konfiguracją bota w formacie JSON (bez opakowania data)
• Pliki (awatar / logo) można przesłać później za pomocą drugiego żądania PATCH w trybie B

Tryb B - multipart/form-data (użyj, gdy przesyłasz pliki w tym samym żądaniu):

• Content-Type: multipart/form-data; boundary=...
• Część JSON data (wymagana, Content-Type: application/json) - konfiguracja bota w zagnieżdżonej strukturze opisanej powyżej
• Część plikowa avatar (opcjonalna) - obraz awatara bota
• Część plikowa whitelabel_logo (opcjonalna) - logo White Label (dotyczy tylko sytuacji, gdy Twoje konto obejmuje funkcję White Label)

W formacie JSON wymagane jest wyłącznie pole name; każde inne pole przyjmuje tę samą wartość domyślną, jaką ustawiłby kreator w panelu administracyjnym.

Przykładowa treść żądania

Oto maksymalny JSON data - z wypełnioną każdą sekcją. Wyślij tylko te sekcje, na których Ci zależy; wszystkie pozostałe przyjmą wartości domyślne.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Reguły walidacji z własnymi komunikatami błędów:

• name - wymagane, maks. 150 znaków
• advanced.temperature - od 0.0 do 1.0
• chatMemory.summariesToKnowledgeRatio - liczba całkowita od 10 do 90 (procent, krok 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - od 0 do 500
• appearance.footerMarkdown - maks. 255 znaków
• humanSupport.enabled=true wymaga ustawienia humanSupport.email
• leadCollection.enabled=true wymaga, aby przynajmniej jedno z pól leadCollection.emailEnabled lub leadCollection.phoneEnabled miało wartość true; niezależnie od tego, który kanał jest włączony, wymaga on również swojej etykiety oraz leaveDetailsMessage i thankYouMessage
• advanced.chatContextSize jest ograniczane do maksymalnego rozmiaru kontekstu obsługiwanego przez Twoje konto. Nie zakładaj, że inne pola numeryczne są automatycznie przycinane.

Pola, których wartość na serwerze wynosi null, są pomijane w treści JSON - przez sieć przesyłane są wyłącznie pola z wartościami innymi niż null.

Przykładowa treść odpowiedzi (201)

Struktura jest taka sama jak w żądaniu, z dodatkiem bloku meta tylko do odczytu oraz jednorazowego pola apiKey na najwyższym poziomie. Adresy URL plików tylko do odczytu (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) są uzupełniane przez serwer, gdy przesłano odpowiednie części multipart.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Pole apiKey pojawia się tylko podczas tworzenia - jest to nowo wygenerowany klucz Bot Talk powiązany z nowym botem. Czysty tekst jest pokazywany tylko raz i nie można go później pobrać z API; zapisz go natychmiast po swojej stronie.

Nagłówek odpowiedzi Location zawiera adres URL nowego bota (/v1/management/bots/{id}).

Przykłady cURL

Tryb A - zwykły JSON (najprostszy):

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}}'

Tryb B - multipart z awatarem:

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"name":"Helpdesk Bot","conversation":{"welcomeMessage":"Hi!"}};type=application/json' \
  -F 'avatar=@./avatar.png'

GET /v1/management/bots/{bot_id}

Pobierz bieżącą konfigurację bota, którego jesteś właścicielem.

Przykład cURL

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..."

Przykładowa treść odpowiedzi (200)

Struktura jest taka sama jak w odpowiedzi POST, bez jednorazowego pola apiKey. Blok meta jest dołączony. Zwraca błąd 404 not_found_error, jeśli bot nie istnieje lub nie należy do Twojego konta.

Bieżący awatar i logo White Label są udostępniane jako w pełni kwalifikowane adresy URL tylko do odczytu (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - oparte na tym samym schemacie, hoście i ścieżce kontekstu, które obsłużyły to żądanie. Pobierz pliki, wykonując żądanie GET bezpośrednio na te adresy URL; aby zastąpić dowolny z plików, prześlij nowy plik za pomocą części multipart avatar / whitelabel_logo w żądaniu PATCH. Te pola URL są ignorowane, jeśli zostaną wysłane w treści żądania.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Normal",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hi! How can I help today?",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "What are your hours?\nHow do I cancel?\nWhere is my order?",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize this conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about this customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#1A73E8",
    "headerColor": "#1A73E8",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI support assistant",
    "senderPlaceholder": "Type a message...",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we will get back to you.",
    "thankYouMessage": "Thanks - we received your message.",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details and we will get in touch.",
    "thankYouMessage": "Thanks - we will be in touch shortly.",
    "requireBeforeNewConversation": false,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Klonowanie bota

Ciało żądania POST /v1/management/bots i ciało odpowiedzi GET /v1/management/bots/{bot_id} mają taką samą strukturę, więc klonowanie to trzyetapowy proces: pobierz (GET) źródło, usuń pola tożsamości zarządzane przez serwer, wyślij (POST) wynik.

1. Pobierz (GET) bota źródłowego.

curl https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -o source-bot.json

2. Usuń blok najwyższego poziomu meta. Obiekt meta (id, createdAt, updatedAt) jest zarządzany przez serwer i służy tylko do odczytu - pozostawienie go w ciele POST nie zaszkodzi (serwer go zignoruje), ale usunięcie go jasno wyraża intencję i usuwa zbędne dane z treści żądania. Opcjonalnie zmodyfikuj name, aby odróżnić klona od źródła.

jq 'del(.meta) | .name = "Helpdesk Bot (clone)"' source-bot.json > clone-body.json

3. Wyślij (POST) oczyszczone ciało, aby utworzyć klona. Zobacz dokumentację POST /v1/management/bots powyżej, aby poznać pełną strukturę ciała i reguły walidacji.

curl -X POST https://api.chatlab.com/aichat/v1/management/bots \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d @clone-body.json

Odpowiedź zawiera meta.id nowego bota oraz nowo wygenerowany apiKey (klucz Bot Talk dla klona). Jawny tekst apiKey jest zwracany wyłącznie w tej odpowiedzi utworzenia - skopiuj go przed odrzuceniem ciała odpowiedzi; nie można go później odzyskać.

Kopiuje to obsługiwane ustawienia, a nie w pełni wytrenowanego chatbota. Treści do trenowania, historia rozmów, integracje/akcje, Flow oraz definicje formularzy nie są klonowane przez te punkty końcowe. Skonfiguruj je oddzielnie w aplikacji.

Dodatkowe uwagi:

• Pliki nie są klonowane. Pola appearance.avatarUrl i whiteLabel.whitelabelLogoUrl są tylko do odczytu i wskazują na pliki bota źródłowego. Jeśli potrzebujesz tego samego awatara lub logo White Label na klonie, pobierz pliki ze źródłowych adresów URL i prześlij je jako części multipart avatar / whitelabel_logo - w wywołaniu POST tworzącym bota (Tryb B) lub w kolejnym PATCH.
• Klucze Bot Talk nie są klonowane. Każdy bot ma własną pulę kluczy Bot Talk. Pojedynczy klucz apiKey zwrócony przez żądanie POST tworzące bota jest jedynym generowanym automatycznie; w razie potrzeby utwórz dodatkowe klucze w zakładce API bota.

PATCH /v1/management/bots/{bot_id}

Zaktualizuj jedno lub więcej pól posiadanego bota. Zmodyfikowane zostaną tylko sekcje / pola obecne w JSON; wszystko pominięte (lub przesłane jako null) pozostaje nienaruszone. Semantyka częściowej aktualizacji ma zastosowanie dla każdego pola w obrębie przesłanej sekcji.

Akceptowane są dwa równoważne nagłówki Content-Type (tak samo jak w POST):

Tryb A - zwykły JSON (zalecany, gdy aktualizujesz tylko ustawienia):

• Content-Type: application/json
• Ciało żądania jest kodem JSON modyfikacji (bez wrappera data)

Tryb B - multipart/form-data (używaj przy przesyłaniu plików):

• Część JSON data (opcjonalna) - modyfikacja. Przesyłaj tylko wtedy, gdy chcesz zmienić pola. Pomiń całkowicie, jeśli chcesz jedynie przesłać awatar lub logo.
• Część plikowa avatar (opcjonalna) - zastąpienie awatara
• Część plikowa whitelabel_logo (opcjonalna) - zastąpienie logo White Label (dotyczy tylko sytuacji, gdy Twoje konto obejmuje funkcję White Label)

Wszystkie trzy części są opcjonalne w PATCH, ale przynajmniej jedna musi być obecna, aby wywołanie miało sens.

Przykładowe ciało żądania (wiele sekcji)

Można tu przesłać dowolne pole akceptowane przez POST /v1/management/bots. Poniższy przykład ilustruje kilka sekcji, a nie każde obsługiwane pole; w praktyce przesyłasz tylko te klucze, które chcesz zmienić (zobacz "Minimalna częściowa aktualizacja" poniżej) - każdy pominięty klucz (lub przesłany jako null) pozostawia zapisaną wartość bez zmian.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Minimalna częściowa aktualizacja

Zaktualizuj pojedyncze pole za pomocą PATCH, wysyłając dokładnie te klucze, które chcesz zmienić - cała reszta zostanie zachowana.

{
  "appearance": {
    "launcherColor": "#abcdef"
  }
}

Przykłady curl

Tryb A - zwykły JSON (najprostszy):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance":{"launcherColor":"#abcdef"}}'

Tryb B - multipart (przy wymianie awatara / logo):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"appearance":{"launcherColor":"#abcdef"}};type=application/json' \
  -F 'avatar=@./new-avatar.png'

Tryb B - wymiana samego awatara (brak zmian w polach):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'avatar=@./new-avatar.png'

Ciało odpowiedzi (200)

Taka sama struktura jak w GET /v1/management/bots/{bot_id} - pełna konfiguracja bota po zastosowaniu modyfikacji, w tym blok meta. Brak pola apiKey. Zwraca 404 not_found_error, jeśli bot nie istnieje lub nie należy do Twojego konta.

Poniższy przykład przedstawia odpowiedź po zastosowaniu powyższej modyfikacji Pełne ciało żądania (wiele sekcji) na bocie z przykładu GET - zmienione pola odzwierciedlają nowe wartości, nietknięte pola zostają zachowane, a wartość meta.updatedAt rośnie.

{
  "name": "Helpdesk Bot",
  "role": {
    "rawPrompt": "You are a friendly support assistant for Acme Inc. Be concise.",
    "role": "CUSTOMER_SUPPORT",
    "language": "English",
    "responseLength": "Concise",
    "websiteAddress": "https://acme.com",
    "companyDescription": "Acme sells industrial widgets."
  },
  "conversation": {
    "welcomeMessage": "Hello there!",
    "queryRefinementEnabled": true,
    "conversationContinuityEnabled": true,
    "conversationRatingEnabled": true,
    "positiveRatingTooltip": "Helpful",
    "negativeRatingTooltip": "Not helpful",
    "suggestedQuestions": "Pricing\nShipping times\nReturns policy",
    "dynamicSuggestedFollowups": true,
    "dynamicFollowupsAutoIcons": true
  },
  "chatMemory": {
    "enabled": true,
    "summaryConversationsEnabled": true,
    "conversationSummaryPrompt": "Summarize the conversation in 3 sentences.",
    "clientSummaryPrompt": "Summarize what we know about the customer.",
    "clientSummaryPromptType": "DEFAULT",
    "conversationSummaryPromptType": "DEFAULT",
    "summariesToKnowledgeRatio": 50
  },
  "appearance": {
    "launcherColor": "#abcdef",
    "headerColor": "#abcdef",
    "titleColor": "#FFFFFF",
    "subtitleColor": "#FFFFFF",
    "clientMessageBubbleColor": "#000000",
    "clientMessageTextColor": "#FFFFFF",
    "responseMessageBubbleColor": "#F4F4F4",
    "responseMessageTextColor": "#000000",
    "chatSubheader": "AI assistant",
    "senderPlaceholder": "Type a message",
    "resetConversationTooltip": "Restart conversation",
    "chatAlignment": "right",
    "launcherBottomMargin": 20,
    "launcherSideMargin": 20,
    "displayShadow": true,
    "customCss": ".rcw-conversation-container { border-radius: 16px; }",
    "chatMessageLinkTarget": "_blank",
    "minimizedDisplayMode": "icon",
    "chatDesktopWidthPx": 400,
    "chatDesktopHeightPx": 600,
    "chatMobileSizePercent": 100,
    "messageFontSize": 14,
    "showChatbotBubblesDesktop": true,
    "showChatbotBubblesMobile": false,
    "chatbotBubblesDelaySeconds": 5,
    "welcomeScreenEnabled": false,
    "welcomeScreenQuestionsLabel": "Quick start",
    "welcomeScreenHideHumanContactForm": false,
    "welcomeScreenHideLiveChat": false,
    "headerActionsLayout": "DROPDOWN",
    "stackSuggestedQuestions": false,
    "suggestedQuestionsFontSize": 14,
    "suggestedQuestionsTextColor": "#000000",
    "suggestedQuestionsBackgroundColor": "#F4F4F4",
    "autoOpenChat": false,
    "autoOpenChatOnMobiles": false,
    "autoOpenChatDelay": false,
    "autoOpenChatDelaySeconds": 5,
    "simulateHumanTyping": true,
    "simulateHumanTypingDelay": 5,
    "footerMarkdown": "Powered by Acme",
    "avatarUrl": "https://api.chatlab.com/aichat/content/avatar_a8f3b2c1_2026060110.png"
  },
  "humanSupport": {
    "enabled": true,
    "email": "support@acme.com",
    "dialogMessage": "Leave us a message and we'll get back to you.",
    "thankYouMessage": "Thanks!",
    "emailMessageSubjectTemplate": "[Acme support] New message from {customerName}",
    "emailMessageContentTemplate": "{message}\n\n - \n{conversationTranscript}",
    "emailPlaceholder": "your@email.com",
    "messagePlaceholder": "How can we help?",
    "emailWithConversationContent": true
  },
  "leadCollection": {
    "enabled": true,
    "nameEnabled": true,
    "nameLabel": "Your name",
    "emailEnabled": true,
    "emailLabel": "Email",
    "phoneEnabled": false,
    "phoneLabel": "Phone",
    "leaveDetailsMessage": "Please leave your details.",
    "thankYouMessage": "Thanks!",
    "requireBeforeNewConversation": true,
    "emailNotificationEnabled": true,
    "emailNotificationAddress": "leads@acme.com",
    "emailWithConversationContent": true
  },
  "liveChat": {
    "enabled": false,
    "infoMessage": "Connecting you with a human agent...",
    "startMessage": "You are now chatting with our team.",
    "endMessage": "Live chat has ended.",
    "nameLabel": "Your name",
    "emailLabel": "Email",
    "schedule": "{\"monday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"tuesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"wednesday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"thursday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"friday\":{\"enabled\":true,\"from\":\"9:00\",\"to\":\"17:00\"},\"saturday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"sunday\":{\"enabled\":false,\"from\":\"9:00\",\"to\":\"17:00\"},\"timezone\":\"Europe/Warsaw\"}",
    "outOfHoursMessage": "We are currently offline.",
    "closeModalMessage": "End the live chat session?",
    "closeModalConfirmLabel": "Yes, end",
    "closeModalCancelLabel": "Cancel",
    "closeModalTooltipText": "End live chat",
    "operatorHasJoinedLabel": "An agent has joined.",
    "operatorDidNotJoinInTimeLabel": "No agent available right now.",
    "waitingForOperatorToJoinLabel": "Waiting for an agent...",
    "waitingForOperatorSeconds": 60,
    "redirectToHumanSupportForm": true
  },
  "consent": {
    "newConversationRequirePolicyAccept": false,
    "humanSupportRequirePolicyAccept": false,
    "leadCollectionRequirePolicyAccept": true,
    "liveChatRequirePolicyAccept": false,
    "newConversationConsentDescription": "By starting a conversation you agree to our terms.",
    "privacyPolicyConsentCheckboxLabel": "I have read and accepted the privacy policy."
  },
  "whiteLabel": {
    "hideRoboAssistLogo": false,
    "whitelabelLogoLink": "https://acme.com",
    "assignToCustomDomain": false,
    "whitelabelLogoUrl": "https://api.chatlab.com/aichat/content/custom_logo_4287_2026060110.png"
  },
  "security": {
    "allowedDomains": "acme.com,support.acme.com",
    "spamFilterEnabled": true,
    "talkMessagesRateLimit": 30,
    "talkMessagesRateLimitDurationSeconds": 60,
    "talkMessagesRateLimitHitMessage": "Please slow down."
  },
  "advanced": {
    "model": "5",
    "temperature": 0.2,
    "chatContextSize": 32000,
    "botMessagesLimit": 2000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T12:45:08Z"
  }
}

GET /v1/usage

Odczytaj bieżące wykorzystanie subskrypcji dla konta, do którego należy klucz Management.

Ciało odpowiedzi (200)

{
  "subscriptionType": "your-plan-id",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType to pisany małymi literami identyfikator bieżącego planu konta (your-plan-id to przykładowy placeholder). Plany pochodzą z dynamicznego katalogu, więc dokładny zestaw identyfikatorów może się z czasem zmieniać w miarę dodawania lub zmiany nazw planów - traktuj to jako nieprzejrzysty ciąg znaków, a nie stały enum.
• messages.used / limit / remaining to kredyty wiadomości na bieżący miesiąc kalendarzowy, resetowane pierwszego dnia miesiąca, a nie w dniu odnowienia subskrypcji. Są to wartości ważone kredytami, a nie surowa liczba odpowiedzi.
• bots.used / limit / remaining zliczają posiadane boty, w tym boty wstrzymane, w ramach całkowitego limitu botów na Twoim koncie.

Nagłówki limitu zapytań (rate limit)

Odpowiedzi, które docierają do etapu sprawdzania limitu zapytań (czyli przeszły uwierzytelnianie i białą listę IP), zawierają:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1715430000

• X-RateLimit-Limit - limit przypadający na klucz, rzeczywiście zastosowany do tego wywołania (domyślnie 10 lub Twoja skonfigurowana wartość rateLimitPerMinute, jeśli jest niższa).
• 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 jest to pełne zresetowanie puli; pula uzupełnia się w sposób ciągły). Gdy pula jest pełna, wartość ta oznacza bieżący czas.

W odpowiedziach 429 rate_limit_exceeded ustawiany jest także nagłówek Retry-After, wyrażony w pełnych sekundach do momentu zwolnienia przynajmniej 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 uwierzytelniania i weryfikacji IP.

Format błędów

Taka sama struktura odpowiedzi (envelope) jak w Bot Talk API:

{
  "error": {
    "type": "permission_error",
    "code": "key_type_not_allowed",
    "message": "This endpoint requires a MANAGEMENT API key.",
    "param": null
  }
}

Błędy walidacji używają code: "invalid_parameter" i dodają ścieżkę do niepoprawnego pola na początku komunikatu, dzięki czemu sekcję powodującą błąd można łatwo zlokalizować:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "humanSupport.email Human support email is required when humanSupport.enabled=true"
  }
}

Nieprawidłowe wartości dla pól typu enum / o zamkniętym zbiorze wartości (np. chatMemory.clientSummaryPromptType = "BOGUS") zawierają ścieżkę do pola, odrzuconą wartość oraz listę dozwolonych wartości:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "chatMemory.clientSummaryPromptType 'BOGUS' is not a valid value. Allowed: CUSTOM, DEFAULT"
  }
}

Powiązane materiały

Informacje o endpointach do obsługi konwersacji i strumieniowaniu SSE znajdziesz w dokumentacji Bot Talk API.