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 aplikację administracyjną i przejdź do Account Settings > Management API (Ustawienia konta > Management API).
2. Kliknij Create Management Key (Utwórz klucz Management), nazwij go, opcjonalnie ustaw białą listę IP oraz limit zapytań (rate limit), a następnie zatwierdź.
3. Skopiuj pełny klucz z okna sukcesu. Tekst jawny jest wyświetlany tylko raz.

Klucz ma postać 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 (body): zagnieżdżone sekcje odzwierciedlające zakładki panelu administracyjnego

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

• 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, stylizacja 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 zbierania 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 wraz z treścią ekranu zgody (zakładka Consent & Privacy)
• whiteLabel - ukrywanie logo, link do własnego logo, hosting we własnej domenie (zakładka Whitelabel)
• security - dozwolone domeny, filtr antyspamowy, limity zapytań rozmowy (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 bazowy, oferowane języki, obsługa języka bazy wiedzy (zakładka Languages)
• advanced - model LLM, temperatura, wielkość kontekstu, limit wiadomości bota, wewnętrzne ustawienia regionalne, Offer Cards (zakładka Model & Advanced)

Tylko pole name znajduje się na najwyższym poziomie, ponieważ identyfikuje bota, zamiast należeć do konkretnej zakładki.

Pasek boczny Bot Settings ma obecnie 15 podzakładek, z czego 13 odpowiada powyższym sekcjom. Dwie podzakładki bez odpowiadającej sekcji to Flow oraz Actions - obie omówione poniżej w sekcji "Poza zakresem API". 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 (request body) i treść odpowiedzi (response body) 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 w przypadku próby przesłania ich w metodach 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 pobrać plik. Aby go zmienić, prześlij nowy plik za pomocą części wieloczęściowej (multipart) avatar (patrz PATCH).
• whiteLabel.whitelabelLogoUrl - w pełni kwalifikowany publiczny adres URL logo w nagłówku White Label. Działa tak samo jak avatarUrl. Aby go zmienić, prześlij nowy plik za pomocą części wieloczęściowej whitelabel_logo (patrz PATCH).

Oba adresy URL korzystają ze schematu + hosta + ścieżki kontekstu bieżącego żądania, więc w przypadku domeny niestandardowej White Label są one zwracane z adresem zakorzenionym w tej domenie (np. https://api.acme.com/aichat/content/...).

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

Rola i konstruowanie promptu

Prompt systemowy, który ostatecznie otrzymuje LLM, jest budowany na jeden z dwóch sposobów w zależności od role.role. Wiedza o tym, na której ścieżce się znajdujesz, pozwala określić, które pola mają znaczenie, a które są zapisywane, lecz 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ść jest nadal zapisywana w ustawieniach bota, po prostu nie jest używana). Szablon uwzględnia:

• role.role - etykieta roli (np. "Customer Support") oraz instrukcje specyficzne dla roli dołączane automatycznie
• name - nazwa bota, wstrzykiwana do zdania otwierającego
• role.language - wartość "Auto Detect" sprawia, że bot dostosowuje się do języka użytkownika; każda inna wartość (np. "English", "Polish") zamienia się w "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, dołączane jako "for the users of the website {url}"
• role.companyDescription - opcjonalne; jeśli nie jest puste, dodawane jako dodatkowy akapit przed instrukcjami dotyczącymi roli

Jest to ścieżka zalecana dla większości botów - automatycznie zyskujesz zachowanie dopasowane do roli oraz barierki bezpieczeństwa.

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

Backend używa role.rawPrompt dosłownie jako całego promptu systemowego. Wartości responseLength, language, websiteAddress, companyDescription są zapisywane, ale nie są wstrzykiwane do promptu - jeśli chcesz, aby którekolwiek z nich wpłynęło na zachowanie bota, musisz samodzielnie zawrzeć je w tekście rawPrompt. Instrukcje dotyczące tonu oraz barierki bezpieczeństwa specyficzne dla ról również nie są dodawane; kontrolujesz cały prompt.

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

Pola typu enum / o zamkniętym zbiorze wartości

Kilka pól akceptuje wyłącznie stały zestaw wartości tekstowych. Wysłanie jakiejkolwiek wartości spoza listy powoduje odrzucenie żądania z błędem 400 validation_failed i wskazaniem ścieżki pola w error.param. W wielkości liter ma znaczenie (case-sensitive).

• 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, 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) oraz inne wartości spoza listy nie są odrzucane przez API, ale tworzą zniekształconą instrukcję w stylu "Output in en, unless...". Wartość domyślna przy tworzeniu to Auto Detect, jeśli pole zostanie pominięte.
• advanced.model - patrz sekcja "Modele tekstowe AI" poniżej; zestaw do wyboru zależy od limitów Twojego konta, a przesłanie wartości, do której Twoje konto nie ma dostępu, zwraca 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Wartości podlegają limitom Twojego konta; wyższe wartości są po cichu ograniczane do limitu
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - przełącznik logiczny. Wartość true zmusza użytkownika do wypełnienia formularza leadów przed rozpoczęciem rozmowy; false pozwala sztucznej inteligencji decydować, 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 struktury, zakresy lub cechy interfejsu panelu administracyjnego, o których warto wiedzieć.

• advanced.temperature - akceptowany zakres wynosi od 0.0 do 1.0, zgodnie z suwakiem w panelu administracyjnym. Wartości spoza tego zakresu są odrzucane z błędem 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - liczba całkowita określająca procent, od 10 do 90 z krokiem co 10. Określa, jak duża część kontekstu czatu jest zarezerwowana na historyczne podsumowania klienta w porównaniu z resztą (baza wiedzy, bieżąca rozmowa, instrukcje). Wartość domyślna: 50. Wartości spoza zakresu 10-90 są odrzucane z błędem 400 validation_failed. Ma zastosowanie tylko wtedy, gdy chatMemory.enabled=true ORAZ chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON zakodowany jako ciąg znaków (string), a nie zagnieżdżony obiekt JSON w żądaniu. Serwer przechowuje surowy ciąg znaków dosłownie; interfejs administracyjny parsuje go po stronie klienta podczas renderowania edytora harmonogramu. Po sparsowaniu ciąg znaków ma postać jednego wpisu dla każdego dnia tygodnia plus klucz 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 zewnętrzne cudzysłowy i ucieczki znaków wewnątrz - jest to jedno pole tekstowe, a nie zagnieżdżony obiekt):

  "{\"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ę komunikat liveChat.outOfHoursMessage, a przekazywanie do czatu na żywo jest blokowane. Walidacja 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 tekst i ujawnią się jako błąd renderowania, gdy człowiek otworzy później bota w panelu. Zweryfikuj strukturę po swojej stronie przed wysłaniem.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krótkie etykiety wyświetlane na przyciskach 👍 / 👎 obok każdej odpowiedzi AI, gdy conversation.conversationRatingEnabled=true. Domyślna treść 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 linię stopki "Powered by ChatLab". Jeśli Twoje konto nie obejmuje funkcji White Label, wartość jest zapisywana, ale ignorowana, a stopka jest zawsze wyświetlana.

• whiteLabel.whitelabelLogoLink - funkcja White Label, zależna od limitów Twojego konta. Docelowy adres URL po kliknięciu własnego logo, gdy hideRoboAssistLogo=true i plik własnego logo został przesłany za pośrednictwem wieloczęściowego parametru whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nie milisekundy), liczba całkowita 0-200. Przerwa między kolejnymi dymkami wiadomości bota, gdy simulateHumanTyping=true. Wartość domyślna: 5.

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

• advanced.internalLocale - kod ustawień regionalnych IETF w formacie ll_CC (podkreślenie, a NIE dywiz ll-CC). 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 BCP-47 ("en-US") nie znajduje się na liście dozwolonych. Domyślnie en_US. Są to ustawienia regionalne używane do formatowania daty/liczb w interfejsie widgetu, niezależne od role.language (języka wypowiedzi bota w rozmowie).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - liczby całkowite (wysyłane jako liczby JSON, np. 30, a nie "30"). Wartość 0 wyłącza limit zapytań na adres IP. Gdy wartość jest różna od zera, widget wymusza limit N wiadomości na czas określony w sekundach, zanim wyświetli odwiedzającemu komunikat security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - liczba całkowita (liczba JSON, np. 1000). Wartość 0 oznacza "brak limitu"; w przeciwnym razie musi być wielokrotnością 1000 (1000, 2000, 10000, ...). Wartości takie jak 100 lub 1500 są odrzucane z błędem 400 validation_failed. Następnie wartość jest po cichu ograniczana do limitu Twojego konta.

Modele tekstowe AI (advanced.model)

Prześlij dokładną wartość API (kolumna po lewej stronie w apostrofach). Wyświetlana nazwa w panelu administracyjnym znajduje się w nawiasach. Limity Twojego konta określają, który podzbiór jest dostępny do wyboru; wysłanie modelu, którego Twoje konto nie może używać, zwraca błąd 400 invalid_parameter. Wartością domyślną dla nowych botów jest 5-MINI.

• 4-O-MINI (GPT 4-o mini)
• 4-O (GPT 4-o)
• 4.1-MINI (GPT 4.1-mini)
• 4.1 (GPT 4.1)
• 5-MINI (GPT 5-mini)
• 5 (GPT 5)
• 5.1 (GPT 5.1)
• 5.4-MINI (GPT 5.4-mini)
• 5.4 (GPT 5.4)
• 5.5 (GPT 5.5)
• GEMINI 2.5 PRO (Gemini 2.5 Pro)
• GEMINI 3 Flash (Gemini 3 Flash)
• GEMINI 3.5 Flash (Gemini 3.5 Flash)
• GEMINI 3.7 Flash (Gemini 3.7 Flash)
• GEMINI 3.8 Flash (Gemini 3.8 Flash)
• GEMINI 3.1 Flash-Lite (Gemini 3.1 Flash-Lite)
• GEMINI 3 PRO (Gemini 3 Pro)

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

Każde pole przesyłane w sieci, wraz z jego typem, ograniczeniem i jednolinijkowym opisem. Semantyka PATCH: pominięcie dowolnego pola (lub przesłanie go jako null) pozostawia zapisaną wartość bez zmian. Taki sam format jest używany w odpowiedzi (z wyłączeniem wieloczęściowej zawartości binarnej; z dodaniem bloku tylko do odczytu meta 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	Nazwa wyświetlana 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 wyłącznie w odpowiedzi:

• meta: { id, createdAt, updatedAt } - tylko do odczytu.
• apiKey - string, obecny tylko w odpowiedzi na 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 "Role and prompt construction")
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}	Oczekiwana 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 wyszukiwaniem RAG
conversationContinuityEnabled	boolean		Jeśli true, powracający odwiedzający wznawiają swoją ostatnią rozmowę
conversationRatingEnabled	boolean		Jeśli true, wyświetlaj ocenę w postaci kciuka w górę/w dół przy wiadomościach bota
positiveRatingTooltip	string		Etykieta podpowiedzi (tooltip) na przycisku pozytywnej oceny
negativeRatingTooltip	string		Etykieta podpowiedzi (tooltip) na przycisku negatywnej oceny
suggestedQuestions	string		Sugerowane pytania / zagajenia rozmowy rozdzielone znakami nowej linii
dynamicSuggestedFollowups	boolean		Jeśli true, AI proponuje kolejne pytania po każdej odpowiedzi
dynamicFollowupsAutoIcons	boolean		Jeśli true, AI automatycznie dobiera ikony emoji dla dynamicznych kolejnych pytań

§ 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 podsumowania każdej rozmowy
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Określa, czy używać domyślnego, czy własnego promptu podsumowania
clientSummaryPrompt	string		Własny prompt używany do podsumowania klienta w wielu rozmowach
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Domyślny a własny prompt profilu klienta
summariesToKnowledgeRatio	int	10-90, krok 10	% okna kontekstu czatu przydzielony na podsumowania w stosunku do wiedzy RAG

§ appearance

Pole	Typ	Ograniczenie	Opis
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 dymka wiadomości odwiedzającego
clientMessageTextColor	string (hex)		Kolor tekstu wiadomości odwiedzającego
responseMessageBubbleColor	string (hex)		Kolor dymka odpowiedzi bota
responseMessageTextColor	string (hex)		Kolor tekstu odpowiedzi bota
chatSubheader	string		Tekst podtytułu wyświetlany pod tytułem czatu
senderPlaceholder	string		Tekst zastępczy (placeholder) w polu wprowadzania wiadomości
resetConversationTooltip	string		Etykieta podpowiedzi (tooltip) na przycisku "resetuj rozmowę"
chatAlignment	string (enum)	∈ {left, right}	Po której stronie ekranu 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 krawędzi bocznej (px)
displayShadow	boolean		Cień pod widgetem
customCss	string		Surowy kod CSS wstrzykiwany do ramki iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Sposób otwierania linków wewnątrz wiadomości bota
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Stan zminimalizowany: ikona przycisku uruchamiającego lub kompaktowy pasek wprowadzania
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ę uruchamiającą na pełną szerokość zamiast z marginesem
welcomeScreenEnabled	boolean		Pokazuj Welcome Screen (ekran powitalny) zamiast przechodzić od razu do czatu
welcomeScreenQuestionsLabel	string		Etykieta nad sugerowanymi pytaniami na ekranie powitalnym
welcomeScreenHideHumanContactForm	boolean		Ukryj akcję formularza kontaktu z człowiekiem w nagłówku podczas wyświetlania ekranu powitalnego. Pojawia się ona ponownie po pierwszej wiadomości odwiedzającego. W botach utworzonych przed 2026-09-02 domyślnie true
welcomeScreenHideLiveChat	boolean		Ukryj akcję czatu na żywo w nagłówku podczas wyświetlania ekranu powitalnego. Pojawia się ona ponownie po pierwszej wiadomości odwiedzającego. W botach utworzonych przed 2026-09-02 domyślnie true
headerActionsLayout	string	DROPDOWN	Sposób prezentacji czatu na żywo i formularza kontaktu z człowiekiem w nagłówku czatu: ICONS (oddzielna ikona dla każdego) lub DROPDOWN (zgrupowane w menu nagłówka). W botach utworzonych przed 2026-09-02 domyślnie ICONS
stackSuggestedQuestions	boolean		Układaj sugerowane pytania pionowo (zamiast obok siebie)
suggestedQuestionsFontSize	int		Rozmiar czcionki kafelków sugerowanych pytań (px)
suggestedQuestionsTextColor	string (hex)		Kolor tekstu kafelka sugerowanego pytania
suggestedQuestionsBackgroundColor	string (hex)		Kolor tła kafelka sugerowanego pytania
autoOpenChat	boolean		Automatycznie otwieraj czat na komputerach
autoOpenChatOnMobiles	boolean		Automatycznie otwieraj czat na urządzeniach mobilnych
autoOpenChatDelay	boolean		Użyj opóźnienia 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	Opóźnienie między dymkami wiadomości (sekundy)
footerMarkdown	string	maks. 255	Własny format markdown stopki wyświetlany pod czatem
avatarUrl	string	tylko do odczytu	Pełny publiczny adres URL awatara; aby go zmienić, prześlij plik przez część multipart avatar

Części multipart w POST/PATCH: avatar (część pliku). Treści odpowiedzi GET pomijają zawartość pliku - przesyłany jest wyłącznie URL.

§ humanSupport

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik ścieżki kontaktu z człowiekiem (Human Support)
email	string	wymagane (create-strict), gdy enabled=true	Adres odbierający wiadomości e-mail ze wsparcia
dialogMessage	string		Wiadomość zachęcająca wyświetlana nad formularzem
thankYouMessage	string		Potwierdzenie wyświetlane po wysłaniu
emailMessageSubjectTemplate	string		Szablon tematu wiadomości e-mail wysyłanej do agenta
emailMessageContentTemplate	string		Szablon treści wiadomości e-mail wysyłanej do agenta
emailPlaceholder	string		Tekst zastępczy (placeholder) w polu e-mail
messagePlaceholder	string		Tekst zastępczy (placeholder) 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. Wartość null zachowuje wbudowany formularz
customFormMapping	string	ciąg zakodowany w formacie JSON	Mapuje pola formularza niestandardowego na pola wiadomości e-mail wsparcia

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

§ leadCollection

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

Reguła create-strict dla wielu pól: enabled=true wymaga włączenia co najmniej jednego z pól: emailEnabled lub phoneEnabled. Pole requirePolicyAccept znajduje się w consent.leadCollectionRequirePolicyAccept, a nie tutaj.

| customFormId | long | id istniejącego formularza niestandardowego | Zastąp wbudowany formularz leada formularzem niestandardowym. Wartość null zachowuje wbudowany formularz | | customFormMapping | string | ciąg zakodowany w formacie JSON | Mapuje pola formularza niestandardowego na pola: imię / e-mail / telefon |

§ liveChat

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik funkcji Live Chat
infoMessage	string		Wiadomość wyjaśniająca przed przekazaniem rozmowy
startMessage	string		Wiadomość pokazywana, gdy rozpoczyna się sesja na żywo
endMessage	string		Wiadomość pokazywana, gdy sesja na żywo dobiega końca
nameLabel	string		Etykieta pola imienia w formularzu wstępnym Live Chat
emailLabel	string		Etykieta pola adresu e-mail w formularzu wstępnym Live Chat
schedule	string	ciąg zakodowany w formacie JSON (przełączniki dni tygodnia + from/to + timezone)	Grafik działania Live Chat - zobacz "Structured fields and ranges", aby poznać dokładny format
outOfHoursMessage	string		Wiadomość pokazywana, gdy według grafiku jesteśmy poza godzinami pracy
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		Etykieta podpowiedzi (tooltip) przy elemencie zamykania czatu
operatorHasJoinedLabel	string		Komunikat pokazywany, gdy dołącza konsultant
operatorDidNotJoinInTimeLabel	string		Komunikat pokazywany, gdy żaden konsultant nie dołączy w wyznaczonym czasie
waitingForOperatorToJoinLabel	string		Komunikat pokazywany podczas oczekiwania na dołączenie konsultanta
waitingForOperatorSeconds	int		Czas oczekiwania na odebranie rozmowy przez konsultanta (sekundy)
redirectToHumanSupportForm	boolean		Jeśli true, przekieruj do formularza Human Support, gdy żaden konsultant nie odbierze rozmowy
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. Pozostawione bez wartości w starszych botach, co oznacza, że funkcja jest włączona

Pole requirePolicyAccept znajduje się w 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 Human Support
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 Live Chat
newConversationConsentDescription	string		Tekst wprowadzający na ekranie zgody na początku 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	zależne od funkcji CUSTOM_DOMAIN	Hostuj czat na skonfigurowanej domenie niestandardowej
whitelabelLogoUrl	string	tylko do odczytu	Pełny publiczny adres URL logo White Label; aby go zmienić, prześlij plik przez część multipart whitelabel_logo

Części multipart w POST/PATCH: whitelabel_logo (część pliku). Treści odpowiedzi GET pomijają zawartość pliku - przesyłany jest wyłącznie 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 dla tego bota
countryFilterMode	string	BLACKLIST lub WHITELIST	Sposób interpretacji list krajów. Same listy pozostają dostępne tylko dla administratora
talkMessagesRateLimit	int	>= 0; 0 wyłącza	Maksymalna liczba wiadomości użytkownika dozwolona w oknie limitu zapytań
talkMessagesRateLimitDurationSeconds	int	>= 0	Długość okna limitu zapytań (sekundy)
talkMessagesRateLimitHitMessage	string		Wiadomość pokazywana 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łosowej w planie	Włącz pełne rozmowy głosowe
voiceId	string	identyfikator głosu specyficzny dla dostawcy (np. alloy)	Który syntetyczny głos mówi
model	string	np. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Model głosowy. Rozliczany za minutę, stawki różnią się w zależności od modelu
turnDetection	string	specyficzne dla dostawcy	Tryb wykrywania kolejki wypowiedzi (turn-taking)
audioPrompt	string		Dodatkowy prompt systemowy używany tylko dla wypowiedzi głosowych
welcomeMessage	string		Mówione powitanie na rozpoczęcie
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 pojedynczej rozmowy głosowej
maxDurationMessage	string		Wiadomość pokazywana po osiągnięciu limitu czasu

§ multilingual

Pole	Typ	Ograniczenie	Opis
enabled	boolean		Przełącznik trybu wielojęzycznego
mode	string	AUTODETECT lub tryb ustalonej listy	Sposób, w jaki bot dobiera język odpowiedzi
baseLanguage	string	kod języka	Język, w którym stworzone są teksty własne bota
languages	string	rozdzielone przecinkami kody języków	Języki oferowane odwiedzającemu
knowledgeLanguageMode	string		Sposób traktowania 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 sekcję "AI text models" powyżej	Identyfikator LLM (np. 5-MINI)
temperature	decimal	0.0-1.0	Temperatura próbkowania (odpowiada suwakowi w interfejsie)
chatContextSize	int	∈ {8000, 16000, 32000}; po cichu ograniczane do limitu Twojego konta	Okno tokenów dla historii rozmów
botMessagesLimit	long	0 lub wielokrotność 1000 (np. 1000, 2000, 10000)	Maksymalna liczba odpowiedzi bota na rozmowę (0 = brak limitu)
internalLocale	string	kod ustawień regionalnych w formacie ll_CC	Ustawienia regionalne dla etykiet interfejsu widgetu (różne od role.language)
productsViewEnabled	boolean		Jeśli true, udostępniaj Offer Cards (karty ofert) e-commerce wewnątrz czatu
includeProductsInKnowledgeBase	boolean		Jeśli true, indeksuj katalog produktów jako część bazy wiedzy

Poza zakresem API

Interfejs administratora zawiera kilka obszarów, które celowo nie zostały udostępnione w tej wersji Management API:

• Zakładka Flow (Ścieżka) - wizualny edytor ścieżek rozmowy (etapy i przejścia). Niedostępny przez Management API.
• Zakładka Actions (Akcje) - zarządzane integracje e-commerce / rezerwacji, AI Search oraz niestandardowe funkcje API. Wywoływanie narzędzi (tool calling) nigdy nie było częścią Management API.
• Sam kreator niestandardowych formularzy - tworzenie i edycja własnych formularzy nie są udostępnione. Możesz jednak przypisać istniejący formularz do bota za pomocą pól leadCollection.customFormId i humanSupport.customFormId.
• Własne ikony otwarcia / zamknięcia 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 pozostają dostępne wyłącznie dla administratora. Udostępniony jest tylko tryb interpretacji za pośrednictwem pola security.countryFilterMode.

Punkty końcowe

POST /v1/management/bots

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

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

• Content-Type: application/json
• Ciało żądania jest obiektem JSON z konfiguracją bota (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) - plik graficzny z awatarem bota
• Część plikowa whitelabel_logo (opcjonalna) - logo White Label (dotyczy tylko sytuacji, gdy Twoje konto obejmuje tę funkcję)

W obiekcie JSON wymagane jest tylko pole name; każde inne pole przyjmuje taką samą wartość domyślną, jaką ustawiłby kreator w panelu administracyjnym.

Pełne ciało żądania

Oto maksymalny JSON data - każda sekcja jest wypełniona. Przesyłaj 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-MINI",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

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

• name - wymagane, maksymalnie 150 znaków
• advanced.temperature - zakres od 0.0 do 1.0
• chatMemory.summariesToKnowledgeRatio - liczba całkowita od 10 do 90 (wartość procentowa, krok 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - zakres od 0 do 500
• appearance.footerMarkdown - maksymalnie 255 znaków
• humanSupport.enabled=true wymaga podania wartości humanSupport.email
• leadCollection.enabled=true wymaga, aby co najmniej jedno z pól: leadCollection.emailEnabled lub leadCollection.phoneEnabled miało wartość true; włączony kanał wymaga również ustawienia swojej etykiety, a także leaveDetailsMessage i thankYouMessage
• Pola z narzuconymi limitami (advanced.chatContextSize, advanced.botMessagesLimit itd.) są automatycznie przycinane do limitów Twojego konta

Pola, których wartość na serwerze wynosi null, są pomijane w ciele JSON - w przesyłanych danych znajdują się wyłącznie pola z wartościami różnymi od null.

Pełne ciało odpowiedzi (201)

Taka sama struktura jak w żądaniu, uzupełniona o blok meta (tylko do odczytu) oraz jednorazowy klucz apiKey na najwyższym poziomie. Adresy URL plików tylko do odczytu (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) są uzupełniane przez serwer, gdy przesłano odpowiadające im 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-MINI",
    "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ę wyłącznie przy tworzeniu - jest to nowo wygenerowany klucz Bot Talk API powiązany z nowym botem. Wartość w postaci jawnego tekstu jest wyświetlana tylko raz i nie można jej później pobrać z API; zapisz ją natychmiast po swojej stronie.

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

Przykłady curl

Tryb A - czysty 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}

Zwraca 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_..."

Pełne ciało odpowiedzi (200)

Taka sama struktura jak w odpowiedzi na POST, z wyłączeniem 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.

Aktualny awatar oraz logo White Label są udostępniane w postaci pełnych adresów URL tylko do odczytu (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - osadzonych na tym samym schemacie, hoście i ścieżce kontekstu, które obsłużyły to żądanie. Pobierz pliki binarne, wykonując żądanie GET bezpośrednio pod te adresy URL; aby podmienić którykolwiek z plików, prześlij nowy za pomocą części avatar / whitelabel_logo w żądaniu multipart w metodzie PATCH. Pola z tymi adresami URL są ignorowane, jeśli zostaną przesłane w ciele żą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-MINI",
    "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 bota źródłowego (GET), usuń pola identyfikacyjne zarządzane przez serwer, wyślij wynik (POST).

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

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

2. Usuń blok meta najwyższego poziomu. Obiekt meta (id, createdAt, updatedAt) jest zarządzany przez serwer i służy tylko do odczytu - pozostawienie go w ciele POST nie spowoduje błędu (serwer go zignoruje), ale jego usunięcie jasno wyraża intencję i zachowuje porządek w ładunku danych. Opcjonalnie zmień 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 oczyszczone ciało (POST), aby utworzyć klona. Zobacz sekcję referencyjną POST /v1/management/bots powyżej, aby sprawdzić 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). Wartość tekstowa apiKey jest zwracana tylko w tej odpowiedzi na utworzenie - skopiuj ją przed odrzuceniem ciała odpowiedzi; nie można jej później odzyskać.

Dwie ważne uwagi:

• Pliki nie są klonowane. Pola appearance.avatarUrl oraz 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 bajty z adresów źródłowych URL i prześlij je jako części multipart avatar / whitelabel_logo - w żądaniu POST tworzącym zasób (Tryb B) albo w kolejnym żądaniu PATCH.
• Klucze Bot Talk nie są klonowane. Każdy bot ma własną pulę kluczy Bot Talk. Pojedynczy apiKey zwrócony przez żądanie POST jest jedynym kluczem 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 bota, którego jesteś właścicielem. Modyfikowane są tylko te sekcje i pola, które przesłano w formacie JSON; wszystko, co pominięto (lub przesłano jako null), pozostaje niezmienione. Częściowa aktualizacja działa na poziomie poszczególnych pól w ramach przesłanej sekcji.

Akceptowane są dwa równorzędne nagłówki Content-Type (tak samo jak przy POST):

Tryb A - czysty JSON (zalecany, gdy aktualizujesz tylko ustawienia):

• Content-Type: application/json
• Ciało żądania jest obiektem JSON z aktualizacją (brak opakowania data)

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

• część JSON data (opcjonalna) - aktualizacja. Wysyłaj tylko wtedy, gdy chcesz zmienić pola. Pomiń całkowicie, jeśli chcesz tylko przesłać awatar lub logo.
• część plikowa avatar (opcjonalna) - zamienia awatar
• część plikowa whitelabel_logo (opcjonalna) - zamienia logo White Label (dotyczy tylko sytuacji, gdy Twój plan obejmuje White Label)

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

Pełne ciało żądania (maksymalny zakres)

W tym miejscu można przesłać dowolne pole akceptowane przez POST /v1/management/bots. Poniższy przykład przedstawia pełny zakres; w praktyce wysyłasz tylko te klucze, które chcesz zmienić (zobacz "Minimalna częściowa aktualizacja" poniżej) - każdy pominięty klucz (lub wysł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ć - wszystkie pozostałe zostaną zachowane.

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

Przykłady poleceń Curl

Tryb A - czysty 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 zamianie 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 - zamiana tylko awatara (bez 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 aktualizacji, 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 aktualizacji z sekcji Pełne ciało żądania (maksymalny zakres) powyżej na bocie z przykładu GET - zmienione pola odzwierciedlają nowe wartości, nietknięte pola zostają zachowane, a wartość meta.updatedAt ulega aktualizacji.

{
  "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

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

Ciało odpowiedzi (200)

{
  "subscriptionType": "standard",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType to zapisany małymi literami identyfikator bieżącego planu konta (np. standard w powyższym przykładzie). Plany pochodzą z dynamicznego katalogu, więc dokładny zestaw identyfikatorów może ulegać zmianom w czasie w miarę dodawania lub zmiany nazw planów - traktuj to pole jako zwykły ciąg znaków, a nie stały typ wyliczeniowy.
• Pola messages.used / limit / remaining oznaczają limity i wykorzystanie wiadomości w bieżącym okresie rozliczeniowym.
• Pola bots.used / limit / remaining zliczają aktywne boty w ramach 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 powłoka (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.