Management API

Přehled Management API

Management API slouží k činnostem v back-office, které nezahrnují odesílání chatových zpráv:

• vytvoření bota programově pomocí POST /v1/management/bots
• načtení konkrétního bota, kterého vlastníte, pomocí GET /v1/management/bots/{bot_id}
• aktualizace konkrétního bota pomocí PATCH /v1/management/bots/{bot_id}
• zjištění využití předplatného pomocí GET /v1/usage

Klíče Management API jsou vázány na váš účet, nikoli na konkrétního bota. Jsou záměrně odděleny od klíčů Bot Talk API, aby kompromitovaný chatovací klíč nemohl upravovat vaše boty ani číst vaše fakturační údaje.

Základní URL

https://api.chatlab.com/aichat

Všechny koncové body v tomto článku jsou relativní k této základní URL.

Začínáme

1. Otevřete administrátorskou aplikaci a přejděte do Account Settings > Management API (Nastavení účtu > Management API).
2. Klikněte na Create Management Key (Vytvořit klíč Management), pojmenujte jej, volitelně nastavte povolené IP adresy a limit četnosti a poté formulář odešlete.
3. Zkopírujte celý klíč z potvrzovacího okna. Text v nezašifrované podobě se zobrazí pouze jednou.

Klíč vypadá jako mk_abcdefghijklmnopqrstuvwxyz012345. Předpona mk_ jej odlišuje od klíčů Bot Talk (ck_).

Autentizace

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Odeslání klíče mk_ na /v1/chat (nebo jakýkoli jiný koncový bod Bot Talk) vrátí chybu 403 key_type_not_allowed. Odeslání klíče ck_ na /v1/management/* vrátí stejnou chybu.

Limity

• Maximálně 5 aktivních klíčů Management API na uživatele
• Maximálně 10 požadavků za minutu na klíč (token bucket, kapacita 10, plynulé doplňování ~1 token každých 6 sekund). Lze snížit při vytvoření - nastavte nižší rateLimitPerMinute, čímž klesne strop i rychlost doplňování.

Oprávnění

Každý klíč Management nese libovolnou podmnožinu tří níže uvedených oprávnění. Alespoň jedno musí být vybráno při vytvoření; jinak je požadavek odmítnut s chybou 400 invalid_request_error. Volání koncového bodu s klíčem, který postrádá požadované oprávnění, vrátí 403 insufficient_permissions.

• bot_read - vyžadováno pro GET /v1/management/bots/{bot_id}
• bot_management - vyžadováno pro POST /v1/management/bots a PATCH /v1/management/bots/{bot_id}
• usage - vyžadováno pro GET /v1/usage

Struktura těla požadavku: vnořené sekce odpovídající záložkám v administraci

POST a PATCH přijímají tělo JSON seskupené do 13 sekcí. Každá sekce odpovídá podzáložce v bočním panelu Bot Settings (Nastavení bota) v administraci, takže JSON klíče a viditelné záložky se přesně shodují: pokud přes API změníte consent.humanSupportRequirePolicyAccept, uvidíte přepnutí stejného přepínače na záložce Consent & Privacy (Souhlas a soukromí) v administraci.

• role - osobnost bota, výchozí prompt, délka odpovědí, jazyk, kontext webu / společnosti (záložka Role & Behavior)
• conversation - uvítací zpráva, zpřesňování dotazů, kontinuita konverzace, přepínač hodnocení + nápovědy, obsah navrhovaných otázek + dynamické doplňující otázky (záložka Chat Conversation)
• chatMemory - přepínač paměti chatu, prompty pro shrnutí, přidělení kontextu (záložka Summaries & Memory)
• appearance - barvy, texty, rozměry, vlastní CSS, uvítací obrazovka, stylování navrhovaných otázek, chování automatického otevření, simulace psaní člověkem, markdown v zápatí (záložka Appearance)
• humanSupport - formulář pro kontaktování člověka (záložka Human Contact Form)
• leadCollection - formulář pro sběr leadů (záložka Lead Collection)
• liveChat - předání na live chat (záložka Live Chat)
• consent - všechny čtyři přepínače souhlasu se zásadami ochrany osobních údajů a text obrazovky se souhlasem (záložka Consent & Privacy)
• whiteLabel - skrytí loga, odkaz vlastního loga, hosting na vlastní doméně (záložka Whitelabel)
• security - povolené domény, spamový filtr, limity četnosti zpráv (záložka Security)
• voice - hlasový vstup a hlasové konverzace: model, hlas, jazyky, prompt, maximální délka (záložka Voice Conversation)
• multilingual - vícejazyčný režim, výchozí jazyk, nabízené jazyky, zpracování jazyka znalostní báze (záložka Languages)
• advanced - LLM model, teplota, velikost kontextu, limit zpráv bota, interní jazyková lokalizace, Offer Cards (záložka Model & Advanced)

V kořenové úrovni se nachází pouze pole name, protože identifikuje bota a nepatří pod žádnou konkrétní záložku.

Boční panel Bot Settings má v současnosti 15 podzáložek a 13 z nich mapuje na výše uvedené sekce. Dvě podzáložky nemají žádnou odpovídající sekci: Flow a Actions - obě jsou popsány níže v sekci „Mimo rozsah API". Mezi 13 mapovaných patří Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation a Languages.

Tělo požadavku a tělo odpovědi sdílejí stejnou strukturu. Odpověď přidává dva prvky navíc:

• meta - pouze pro čtení: ID bota a časová razítka. Odstraňte tuto část, pokud chcete odpověď z GET převést na platné tělo pro POST.
• apiKey - přítomno pouze při vytvoření - nově vygenerovaný klíč Bot Talk API pro nového bota.

Dvě pole uvnitř sdílené struktury jsou pouze pro čtení - vrací se v odpovědi, ale při pokusu o jejich odeslání v POST/PATCH jsou ignorována:

• appearance.avatarUrl - plně kvalifikovaná veřejná URL adresa obrázku avatara bota (např. https://api.chatlab.com/aichat/content/avatar_xyz.png). Přímým voláním GET stáhnete binární data. Chcete-li obrázek změnit, nahrajte nový soubor přes multipart část avatar (viz PATCH).
• whiteLabel.whitelabelLogoUrl - plně kvalifikovaná veřejná URL adresa loga v záhlaví pro white-label. Stejný vzor jako u avatarUrl. Chcete-li logo změnit, nahrajte nový soubor přes multipart část whitelabel_logo (viz PATCH).

Obě URL adresy používají schéma + hostitele + cestu kontextu z aktuálního požadavku, takže na vlastní doméně white-label se vrací s kořenem na této doméně (např. https://api.acme.com/aichat/content/...).

Pokud chcete sekci v PATCH přeskočit, odešlete pro ni null; pro přeskočení jednoho pole v rámci sekce odešlete null pro toto konkrétní pole. Hodnota null na úrovni pole nikdy nevymaže uloženou hodnotu - znamená pouze „neměnit".

Sestavení role a promptu

Systémový prompt, který LLM skutečně obdrží, je sestaven jedním ze dvou způsobů v závislosti na role.role. Podle zvolené větve poznáte, která pole jsou podstatná a která se pouze ukládají, ale ignorují.

Větev A - role.role je CUSTOMER_SUPPORT, SALES nebo LEAD_COLLECTION_AGENT (řízeno šablonou)

Backend sestaví prompt z vestavěné šablony a zcela ignoruje role.rawPrompt (hodnota zůstává u bota uložena, ale nepoužije se). Šablona zahrnuje:

• role.role - označení role (např. „Customer Support") a automaticky připojené pokyny specifické pro danou roli
• name - jméno bota vložené do úvodní věty
• role.language - "Auto Detect" přepne bota tak, aby sledoval jazyk uživatele; jakákoli jiná hodnota (např. "English", "Polish") se převede na pokyn „Output in {language}, unless user uses another language"
• role.responseLength - mapuje se na cílový počet slov: Concise ≈ 50 slov, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - volitelné; pokud není prázdné, připojí se jako „for the users of the website {url}"
• role.companyDescription - volitelné; pokud není prázdné, vloží se jako další odstavec před pokyny k roli

Toto je doporučená větev pro většinu botů - získáte chování vyladěné pro danou roli a bezpečnostní mantinely bez nutnosti vlastního nastavování.

Větev B - role.role je CUSTOM (prompt dodaný volajícím)

Backend použije role.rawPrompt doslovně jako celý systémový prompt. Hodnoty responseLength, language, websiteAddress, companyDescription se ukládají, ale nevkládají se do promptu - pokud chcete některou z nich promítnout do chování bota, musíte ji do textu rawPrompt zahrnout sami. Pokyny k tónu komunikace ani bezpečnostní mantinely specifické pro danou roli se nepřidávají; celý prompt máte plně pod kontrolou.

Používejte CUSTOM pouze tehdy, když vám prompt řízený šablonou nevyhovuje (např. potřebujete osobnost pro velmi specifický obor, vlastní bezpečnostní omezení nebo nestandardní formát výstupu).

Výčtová pole (enum) s pevně danými hodnotami

Několik polí přijímá pouze pevnou sadu řetězcových hodnot. Odeslání jakékoli hodnoty mimo seznam je odmítnuto s chybou 400 validation_failed a cestou k danému poli v error.param. U hodnot se rozlišují velká a malá písmena.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - celý anglický název jazyka z rozevíracího seznamu v administraci, např. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi a přibližně 80 dalších. Hodnota je uložena doslovně a dosazena do šablony promptu, takže dvoupísmenné kódy ISO (en, pl) a další hodnoty mimo seznam sice API neodmítne, ale vygenerují zkomolený pokyn jako „Output in en, unless...". Pokud pole při vytvoření vynecháte, výchozí hodnota je Auto Detect.
• advanced.model - viz část „AI textové modely" níže; volitelná sada závisí na limitech vašeho účtu a jakákoli hodnota, kterou váš účet nemůže použít, vrátí chybu 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Podléhá limitům vašeho účtu; vyšší hodnoty jsou tiše omezeny na povolené maximum
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - logická hodnota (boolean). true donutí uživatele vyplnit formulář pro sběr leadů před zahájením konverzace; false nechá rozhodnutí o zobrazení formuláře na AI (výchozí).

Strukturovaná pole a číselné rozsahy

Pole, která vypadají jako jednoduché řetězce nebo čísla, ale ve skutečnosti mají specifické struktury, rozsahy nebo zvláštnosti v administrátorském rozhraní, o kterých je dobré vědět.

• advanced.temperature - povolený rozsah je 0.0 až 1.0, což odpovídá posuvníku v administrátorském rozhraní. Hodnoty mimo tento rozsah jsou odmítnuty s chybou 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - celé číslo v procentech, 10-90 s krokem 10. Určuje, jaká část kontextu chatu je vyhrazena pro historická shrnutí klienta oproti zbytku (znalostní báze, aktuální konverzace, instrukce). Výchozí hodnota je 50. Hodnoty mimo 10-90 jsou odmítnuty s chybou 400 validation_failed. Platí pouze tehdy, když chatMemory.enabled=true A ZÁROVEŇ chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON kódovaný jako řetězec, nikoli jako vnořený JSON objekt v těle přenosu. Server ukládá nezpracovaný řetězec doslovně; administrátorské rozhraní jej parsuje na straně klienta při vykreslování editoru rozvrhu. Po rozparsování má řetězec podobu jedné položky pro každý den v týdnu plus klíč timezone:

  • každý klíč dne v týdnu (monday-sunday) odpovídá struktuře {enabled: boolean, from: "H:MM", to: "H:MM"} ve 24hodinovém formátu
  • timezone je název časového pásma podle IANA (např. "Europe/Warsaw", "America/New_York")

  Příklad hodnoty (všimněte si vnějších uvozovek a ošetřených vnitřních uvozovek - jde o jedno textové pole, nikoli o vnořený objekt):

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

  Mimo uvedené hodiny se návštěvníkovi zobrazí liveChat.outOfHoursMessage a přepojení na live chat je potlačeno. Ověření vnitřní struktury probíhá pouze na straně klienta v administraci - neplatný JSON nebo nerozpoznané klíče API přijme jako prostý text a projeví se chybou vykreslení až ve chvíli, kdy člověk později bota otevře v administraci. Před odesláním si strukturu zkontrolujte na své straně.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krátké popisky zobrazené u tlačítek 👍 / 👎 vedle každé odpovědi AI, pokud je conversation.conversationRatingEnabled=true. Výchozí text je „I like the response" / „I don't like the response". Viditelné pro koncové uživatele.

• whiteLabel.hideRoboAssistLogo - funkce White Label, která podléhá limitům vašeho účtu. Skryje řádek „Powered by ChatLab" v zápatí. Pokud váš účet white-labeling nezahrnuje, hodnota se sice uloží, ale ignoruje se a zápatí se vždy vykreslí.

• whiteLabel.whitelabelLogoLink - funkce White Label, která podléhá limitům vašeho účtu. Cílová URL adresa pro proklik vlastního loga, pokud je hideRoboAssistLogo=true a je nahrán soubor s vlastním logem přes multipart část whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nikoli milisekundy), celé číslo 0-200. Prodleva mezi jednotlivými zprávami bota, pokud je simulateHumanTyping=true. Výchozí hodnota je 5.

• appearance.autoOpenChatDelaySeconds - sekundy, celé číslo. Zpoždění před automatickým otevřením widgetu, pokud platí autoOpenChat=true a autoOpenChatDelay=true.

• advanced.internalLocale - kód jazyka a regionu IETF ve formátu ll_CC (podtržítko, NIKOLI ll-CC s pomlčkou). Přijímané hodnoty pocházejí z pevného seznamu ~95 lokalizací: 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 a mnoha dalších. Samostatný dvoupísmenný kód ("en") nebo formát BCP-47 ("en-US") v seznamu povolených hodnot není. Výchozí hodnota je en_US. Jedná se o lokalizaci používanou pro formátování data a čísel v ovládacích prvcích widgetu, která se liší od role.language (jazyka konverzačního výstupu bota).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - celá čísla (odesílejte jako číselné hodnoty JSON, např. 30, nikoli "30"). Hodnota 0 zakáže limit četnosti na IP adresu. Při nenulové hodnotě widget vymáhá limit N zpráv za dobu v sekundách, než se návštěvníkovi zobrazí security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - celé číslo (v JSONu číslo, např. 1000). 0 znamená „bez limitu"; jinak musí jít o násobek 1000 (1000, 2000, 10000...). Hodnoty jako 100 nebo 1500 jsou odmítnuty s chybou 400 validation_failed. Následně se hodnota navíc tiše omezí na limit vašeho účtu.

AI textové modely (advanced.model)

Odesílejte přesnou hodnotu pro API (sloupec v levých apostrofech). Zobrazovaný název v administraci je uveden v závorce. To, jaká podmnožina je k dispozici, určují limity vašeho účtu; odeslání modelu, který váš účet nemůže používat, vrátí chybu 400 invalid_parameter. Výchozí hodnota pro nové boty je 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)

Přehled polí (úplné schéma požadavku)

Každé pole přenášené po síti včetně jeho typu, omezení a jednořádkového popisu. Sémantika PATCH: jakékoli vynechané pole (nebo pole odeslané jako null) ponechá uloženou hodnotu beze změny. Stejná struktura se používá i pro odpověď (bez binárního obsahu v rámci multipart; v každé odpovědi je navíc blok meta určený pouze pro čtení a pouze v odpovědi na vytvoření je přítomen klíč apiKey).

Nejvyšší úroveň

Pole	Typ	Omezení	Popis
name	string	max 150, povinné při vytvoření	Zobrazovaný název bota
role	object		Viz § role
conversation	object		Viz § conversation
chatMemory	object		Viz § chatMemory
appearance	object		Viz § appearance
humanSupport	object		Viz § humanSupport
leadCollection	object		Viz § leadCollection
liveChat	object		Viz § liveChat
consent	object		Viz § consent
whiteLabel	object		Viz § whiteLabel
security	object		Viz § security
advanced	object		Viz § advanced

Prvky přidané pouze do odpovědi:

• meta: { id, createdAt, updatedAt } - pouze pro čtení.
• apiKey - string, přítomný pouze v odpovědi na POST /v1/management/bots - nově vygenerovaný klíč Bot Talk pro nového bota, vrácený právě jednou.

§ role

Pole	Typ	Omezení	Popis
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Předvolba persony; vybírá šablonu promptu (viz „Role and prompt construction“)
language	string	celý anglický název jazyka (English, Polish, ...) nebo Auto Detect	Primární jazyk předávaný do šablony promptu
responseLength	string	∈ {Concise, Normal, Detailed}	Požadovaná podrobnost odpovědí AI
websiteAddress	string		Webové stránky použité jako kontext pro prompt
companyDescription	string		Popis společnosti použitý jako kontext pro prompt
rawPrompt	string		Vlastní systémový prompt - použije se doslovně pouze v případě, že role=CUSTOM

§ conversation

Pole	Typ	Omezení	Popis
welcomeMessage	string		První zpráva zobrazená návštěvníkovi po otevření
queryRefinementEnabled	boolean		Pokud je zapnuto, dotaz návštěvníka se před vyhledáním pomocí RAG upřesní
conversationContinuityEnabled	boolean		Pokud je zapnuto, vracející se návštěvníci pokračují v předchozí konverzaci
conversationRatingEnabled	boolean		Pokud je zapnuto, u zpráv bota se zobrazí hodnocení palcem nahoru/dolů
positiveRatingTooltip	string		Text v bublině (tooltip) u tlačítka pro kladné hodnocení
negativeRatingTooltip	string		Text v bublině (tooltip) u tlačítka pro záporné hodnocení
suggestedQuestions	string		Navrhované otázky / úvodní témata konverzace oddělená novým řádkem
dynamicSuggestedFollowups	boolean		Pokud je zapnuto, AI po každé odpovědi navrhne doplňující otázky
dynamicFollowupsAutoIcons	boolean		Pokud je zapnuto, AI automaticky vybírá ikony emoji pro dynamické doplňující dotazy

§ chatMemory

Pole	Typ	Omezení	Popis
enabled	boolean		Hlavní přepínač funkce paměti chatu
summaryConversationsEnabled	boolean		Ukládat souhrny jednotlivých konverzací
conversationSummaryPrompt	string		Vlastní prompt použitý k vytvoření souhrnu každé konverzace
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Určuje, zda se použije výchozí nebo vlastní prompt pro souhrn
clientSummaryPrompt	string		Vlastní prompt použitý k vytvoření profilu klienta napříč konverzacemi
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Výchozí vs. vlastní prompt pro profil klienta
summariesToKnowledgeRatio	int	10-90, krok 10	% kontextového okna chatu vyhrazených pro souhrny vs. znalosti RAG

§ appearance

Pole	Typ	Omezení	Popis
launcherColor	string (hex)		Barva pozadí spouštěče (ikony chatu)
headerColor	string (hex)		Barva pozadí záhlaví chatu
titleColor	string (hex)		Barva nadpisu v záhlaví chatu
subtitleColor	string (hex)		Barva podnadpisu v záhlaví chatu
clientMessageBubbleColor	string (hex)		Barva bubliny se zprávou od návštěvníka
clientMessageTextColor	string (hex)		Barva textu zprávy od návštěvníka
responseMessageBubbleColor	string (hex)		Barva bubliny s odpovědí bota
responseMessageTextColor	string (hex)		Barva textu odpovědi bota
chatSubheader	string		Doplňkový řádek textu zobrazený pod názvem chatu
senderPlaceholder	string		Zástupný text v poli pro zadání zprávy
resetConversationTooltip	string		Text v bublině (tooltip) u tlačítka pro resetování konverzace
chatAlignment	string (enum)	∈ {left, right}	Ke které straně obrazovky je chat ukotven
launcherBottomMargin	int	0-500	Vzdálenost spouštěče od dolního okraje (px)
launcherSideMargin	int	0-500	Vzdálenost spouštěče od bočního okraje (px)
displayShadow	boolean		Vrhání stínu pod widgetem
customCss	string		Vlastní kód CSS vložený do prvku iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Způsob otevírání odkazů uvnitř zpráv bota
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Minimalizovaný stav: ikona spouštěče nebo kompaktní lišta pro odeslání
chatDesktopWidthPx	int		Šířka widgetu na počítači
chatDesktopHeightPx	int		Výška widgetu na počítači
chatMobileSizePercent	int		Velikost widgetu na mobilu jako % zobrazovacího pole (viewport)
messageFontSize	int		Velikost písma textu zprávy (px)
showChatbotBubblesDesktop	boolean		Zobrazovat plovoucí upoutávací bubliny na počítači
showChatbotBubblesMobile	boolean		Zobrazovat plovoucí upoutávací bubliny na mobilu
chatbotBubblesDelaySeconds	int		Prodleva před zobrazením upoutávacích bublin (sekundy)
launcherIconFullSize	boolean		Vykreslit vlastní ikonu spouštěče od okraje k okraji bez odsazení
welcomeScreenEnabled	boolean		Zobrazit uvítací obrazovku (Welcome Screen) místo přímého přechodu do chatu
welcomeScreenQuestionsLabel	string		Popisek nad navrhovanými otázkami na uvítací obrazovce
welcomeScreenHideHumanContactForm	boolean		Skrýt akci formuláře pro kontaktování operátora v záhlaví po dobu zobrazení uvítací obrazovky. Znovu se objeví po první zprávě návštěvníka. U botů vytvořených před 2. 9. 2026 je výchozí hodnota true
welcomeScreenHideLiveChat	boolean		Skrýt akci Live Chat v záhlaví po dobu zobrazení uvítací obrazovky. Znovu se objeví po první zprávě návštěvníka. U botů vytvořených před 2. 9. 2026 je výchozí hodnota true
headerActionsLayout	string	DROPDOWN	Způsob nabídky chatu naživo a formuláře pro kontaktování operátora v záhlaví: ICONS (samostatná ikona pro každou možnost) nebo DROPDOWN (seskupeno v nabídce záhlaví). U botů vytvořených před 2. 9. 2026 je výchozí hodnota ICONS
stackSuggestedQuestions	boolean		Řadit navrhované otázky svisle pod sebe (namísto vedle sebe)
suggestedQuestionsFontSize	int		Velikost písma tlačítek s navrhovanými otázkami (px)
suggestedQuestionsTextColor	string (hex)		Barva textu tlačítek s navrhovanými otázkami
suggestedQuestionsBackgroundColor	string (hex)		Barva pozadí tlačítek s navrhovanými otázkami
autoOpenChat	boolean		Automaticky otevřít chat na počítači
autoOpenChatOnMobiles	boolean		Automaticky otevřít chat na mobilu
autoOpenChatDelay	boolean		Použít prodlevu před automatickým otevřením
autoOpenChatDelaySeconds	int		Prodleva automatického otevření (sekundy)
simulateHumanTyping	boolean		Rozdělit odpověď bota do bublin s animací psaní
simulateHumanTypingDelay	int	0-200	Prodleva mezi zprávami v bublinách (sekundy)
footerMarkdown	string	max 255	Vlastní kód v markdownu zobrazený v zápatí pod chatem
avatarUrl	string	pouze pro čtení	Plně kvalifikovaná veřejná adresa URL avatara; pro její změnu nahrajte soubor přes multipart část avatar

Multipart u požadavků POST/PATCH: avatar (souborová část). Těla odpovědí / požadavků GET obsah souboru vynechávají - v přenosu je přítomna pouze adresa URL.

§ humanSupport

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač toku lidské podpory
email	string	povinné (striktní při vytvoření), pokud enabled=true	Adresa, na kterou se odesílají e-maily s požadavky na lidskou podporu
dialogMessage	string		Vyzývací zpráva zobrazená nad formulářem
thankYouMessage	string		Potvrzení zobrazené po odeslání
emailMessageSubjectTemplate	string		Šablona předmětu e-mailu odesílaného operátorovi
emailMessageContentTemplate	string		Šablona těla e-mailu odesílaného operátorovi
emailPlaceholder	string		Zástupný text v poli pro e-mail
messagePlaceholder	string		Zástupný text v textovém poli pro zprávu
emailWithConversationContent	boolean		Pokud je zapnuto, zahrne se do těla e-mailu přepis konverzace
customFormId	long	ID existujícího vlastního formuláře	Nahradit vestavěný kontaktní formulář vlastním formulářem. Hodnota null ponechá vestavěný formulář
customFormMapping	string	řetězec kódovaný jako JSON	Mapuje pole vlastního formuláře na pole e-mailu lidské podpory

Hodnota requirePolicyAccept se nachází v poli consent.humanSupportRequirePolicyAccept, nikoli zde.

§ leadCollection

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač formuláře pro sběr kontaktů (leadů)
nameEnabled	boolean		Sbírat jméno
nameLabel	string		Popisek pole pro jméno
emailEnabled	boolean		Sbírat e-mail
emailLabel	string	povinné (striktní při vytvoření), pokud enabled=true A ZÁROVEŇ emailEnabled=true	Popisek pole pro e-mail
phoneEnabled	boolean		Sbírat telefon
phoneLabel	string	povinné (striktní při vytvoření), pokud enabled=true A ZÁROVEŇ phoneEnabled=true	Popisek pole pro telefon
leaveDetailsMessage	string	povinné (striktní při vytvoření), pokud enabled=true	Zpráva vyzývající návštěvníka k zanechání údajů
thankYouMessage	string	povinné (striktní při vytvoření), pokud enabled=true	Potvrzení zobrazené po odeslání
requireBeforeNewConversation	boolean		Pokud true, formulář musí být odeslán před zahájením chatu; pokud false, AI sama rozhodne, kdy formulář nabídnout
emailNotificationEnabled	boolean		Odeslat vlastníkovi e-mail při každém získání leadu
emailNotificationAddress	string		Příjemce oznámení (výchozí hodnotou je e-mail účtu)
emailWithConversationContent	boolean		Pokud je zapnuto, zahrne se přepis konverzace do oznámení

Pravidlo závislosti polí při vytváření: při enabled=true je vyžadováno alespoň jedno z polí emailEnabled nebo phoneEnabled. Hodnota requirePolicyAccept se nachází v poli consent.leadCollectionRequirePolicyAccept, nikoli zde.

| customFormId | long | ID existujícího vlastního formuláře | Nahradit vestavěný formulář pro sběr leadů vlastním formulářem. Hodnota null ponechá vestavěný formulář | | customFormMapping | string | řetězec kódovaný jako JSON | Mapuje pole vlastního formuláře na jméno / e-mail / telefon |

§ liveChat

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač funkce Live Chat
infoMessage	string		Vysvětlující zpráva před předáním na operátora
startMessage	string		Zpráva zobrazená po zahájení relace s operátorem
endMessage	string		Zpráva zobrazená po ukončení relace s operátorem
nameLabel	string		Popisek pole pro jméno ve formuláři před zahájením chatu naživo
emailLabel	string		Popisek pole pro e-mail ve formuláři před zahájením chatu naživo
schedule	string	řetězec kódovaný jako JSON (přepínače dnů v týdnu + from/to + timezone)	Provozní doba chatu naživo - přesnou strukturu naleznete v části „Structured fields and ranges“
outOfHoursMessage	string		Zpráva zobrazená v době mimo provozní hodiny
closeModalMessage	string		Nadpis modálního okna s dotazem na ukončení chatu naživo
closeModalConfirmLabel	string		Popisek potvrzovacího tlačítka v modálním okně ukončení
closeModalCancelLabel	string		Popisek tlačítka pro zrušení v modálním okně ukončení
closeModalTooltipText	string		Text v bublině (tooltip) u prvku pro zavření chatu
operatorHasJoinedLabel	string		Popisek zobrazený po připojení operátora
operatorDidNotJoinInTimeLabel	string		Popisek zobrazený v případě, že se žádný operátor nepřipojí v časovém limitu
waitingForOperatorToJoinLabel	string		Popisek zobrazený během čekání na operátora
waitingForOperatorSeconds	int		Časový limit pro přijetí konverzace operátorem (sekundy)
redirectToHumanSupportForm	boolean		Pokud je zapnuto, při nepřijetí konverzace operátorem se přejde na formulář Human Support
missedEmailEnabled	boolean	výchozí hodnota true	Odeslat vlastníkovi bota e-mail, pokud požadavek na chat naživo zůstal bez odpovědi. U starších botů nebylo nastaveno, což se vyhodnocuje jako zapnuto

Hodnota requirePolicyAccept se nachází v poli consent.liveChatRequirePolicyAccept, nikoli zde.

§ consent

Pole	Typ	Omezení	Popis
newConversationRequirePolicyAccept	boolean		Vyžadovat souhlas se zásadami ochrany osobních údajů před zahájením nové konverzace
humanSupportRequirePolicyAccept	boolean		Vyžadovat souhlas se zásadami ochrany osobních údajů před odesláním formuláře lidské podpory
leadCollectionRequirePolicyAccept	boolean		Vyžadovat souhlas se zásadami ochrany osobních údajů před odesláním formuláře pro sběr kontaktů
liveChatRequirePolicyAccept	boolean		Vyžadovat souhlas se zásadami ochrany osobních údajů před zahájením relace chatu naživo
newConversationConsentDescription	string		Úvodní text na obrazovce se souhlasem při zahájení konverzace
privacyPolicyConsentCheckboxLabel	string		Popisek vedle zaškrtávacího pole souhlasu (obvykle obsahuje odkaz na zásady ochrany osobních údajů)

§ whiteLabel

Pole	Typ	Omezení	Popis
hideRoboAssistLogo	boolean	funkce White Label; závisí na limitech účtu	Skrýt výchozí logo ChatLab v zápatí
whitelabelLogoLink	string	funkce White Label; závisí na limitech účtu	Adresa URL, na kterou odkazuje vlastní logo v zápatí
assignToCustomDomain	boolean	podmíněno funkcí CUSTOM_DOMAIN	Hostovat chat na nakonfigurované vlastní doméně
whitelabelLogoUrl	string	pouze pro čtení	Plně kvalifikovaná veřejná adresa URL loga White Label; pro změnu nahrajte soubor přes multipart část whitelabel_logo

Multipart u požadavků POST/PATCH: whitelabel_logo (souborová část). Těla odpovědí / požadavků GET obsah souboru vynechávají - v přenosu je přítomna pouze adresa URL.

§ security

Pole	Typ	Omezení	Popis
allowedDomains	string		Čárkami oddělený seznam domén s povolením vložit widget (prázdné = bez seznamu povolených domén)
spamFilterEnabled	boolean		Zapnout spamový filtr pro příchozí zprávy pro tohoto bota
countryFilterMode	string	BLACKLIST nebo WHITELIST	Způsob interpretace seznamů zemí. Samotné seznamy jsou přístupné pouze pro administrátory
talkMessagesRateLimit	int	>= 0; 0 vypíná	Maximální počet zpráv uživatele povolených v rámci časového okna limitu
talkMessagesRateLimitDurationSeconds	int	>= 0	Délka časového okna pro omezení četnosti (sekundy)
talkMessagesRateLimitHitMessage	string		Zpráva zobrazená návštěvníkovi po dosažení limitu četnosti zpráv

§ voice

Pole	Typ	Omezení	Popis
inputEnabled	boolean		Umožnit návštěvníkovi diktovat zprávy (převod řeči na text)
conversationEnabled	boolean	vyžaduje hlasovou funkci v tarifu	Povolit plnohodnotné hlasové konverzace
voiceId	string	ID hlasu podle poskytovatele (např. alloy)	Který syntetický hlas mluví
model	string	např. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Hlasový model. Účtováno za minutu, sazby se u jednotlivých modelů liší
turnDetection	string	specifické pro poskytovatele	Režim střídání mluvčích
audioPrompt	string		Dodatečný systémový prompt použitý pouze při hlasových vstupech
welcomeMessage	string		Mluvená úvodní věta
language	string	kód jazyka	Primární jazyk hlasového bota
additionalLanguages	string	čárkami oddělené kódy jazyků	Další jazyky, které hlasový agent přijímá
maxDurationSeconds	int		Pevný limit délky jedné hlasové konverzace
maxDurationMessage	string		Zpráva zobrazená po dosažení limitu délky

§ multilingual

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač vícejazyčného režimu
mode	string	AUTODETECT nebo režim s pevným seznamem	Způsob, jakým bot volí jazyk odpovědi
baseLanguage	string	kód jazyka	Jazyk, ve kterém jsou vytvořeny vlastní texty bota
languages	string	čárkami oddělené kódy jazyků	Jazyky nabízené návštěvníkovi
knowledgeLanguageMode	string		Způsob zacházení se znalostmi v jiných jazycích
knowledgeLanguageFallback	string	kód jazyka	Jazyk použitý v případě, že není nalezena žádná shoda

§ advanced

Pole	Typ	Omezení	Popis
model	string	závisí na limitech účtu; viz „AI text models“ výše	Identifikátor LLM (např. 5-MINI)
temperature	decimal	0.0-1.0	Vzorkovací teplota (odpovídá posuvníku v uživatelském rozhraní)
chatContextSize	int	∈ {8000, 16000, 32000}; tiše omezeno na limit vašeho účtu	Okno tokenů pro historii chatu
botMessagesLimit	long	0 nebo násobek 1000 (např. 1000, 2000, 10000)	Maximální počet odpovědí bota na jednu konverzaci (0 = bez omezení)
internalLocale	string	kód národního prostředí ve tvaru ll_CC	Národní prostředí pro prvky rozhraní widgetu (nezávislé na role.language)
productsViewEnabled	boolean		Pokud je zapnuto, v chatu se zpřístupní Offer Cards (karty nabídek) pro e-commerce
includeProductsInKnowledgeBase	boolean		Pokud je zapnuto, produktový katalog se zaindexuje jako součást znalostní báze

Mimo rozsah rozhraní API

Administrátorské rozhraní nabízí několik oblastí, které záměrně nejsou v této verzi Management API zpřístupněny:

• Záložka Flow - vizuální editor toků konverzace Flow Editor (fáze a přechody). Není přes Management API k dispozici.
• Záložka Actions - spravované integrace pro e-commerce / rezervace, AI Search a vlastní funkce API. Volání nástrojů nikdy nebylo součástí Management API.
• Samotný nástroj pro tvorbu vlastních formulářů - vytváření a úprava vlastních formulářů nejsou k dispozici. Můžete však k botovi připojit existující formulář pomocí polí leadCollection.customFormId a humanSupport.customFormId.
• Vlastní ikony pro otevření / zavření chatu - customLauncherIconVisible, openChatIcon, closeChatIcon. Rozhraní API vystavuje pouze hlavní multipart části avatar a whitelabel_logo.
• Seznamy IP adres a zemí - samotné záznamy jsou přístupné pouze správcům. Vystaven je pouze režim jejich interpretace prostřednictvím pole security.countryFilterMode.

Koncové body

POST /v1/management/bots

Vytvořte nového bota. Podporovány jsou dva rovnocenné typy Content-Type; zvolte ten, který vám více vyhovuje.

Režim A - čistý JSON (doporučeno, pokud v rámci stejného požadavku nepotřebujete nahrát avatar / logo):

• Content-Type: application/json
• Tělo požadavku je přímo konfigurační JSON bota (bez obálky data)
• Soubory (avatar / logo) lze nahrát později pomocí druhého požadavku PATCH v režimu B

Režim B - multipart/form-data (použijte při nahrávání souborů v rámci stejného požadavku):

• Content-Type: multipart/form-data; boundary=...
• JSON část data (povinná, Content-Type: application/json) - konfigurace bota ve vnořené struktuře popsané výše
• Souborová část avatar (volitelná) - obrázek avatara bota
• Souborová část whitelabel_logo (volitelná) - logo pro White Label (platí pouze v případě, že váš účet zahrnuje funkci White Label)

V JSONu je povinné pouze pole name; všechna ostatní pole přebírají stejné výchozí hodnoty, jaké by nastavil průvodce v administračním rozhraní.

Kompletní tělo požadavku

Toto je maximální JSON pro část data - se všemi vyplněnými sekcemi. Odesílejte pouze ty sekce, které potřebujete; vše ostatní použije výchozí hodnoty.

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

Validační pravidla s vlastními chybovými zprávami:

• name - povinné, maximálně 150 znaků
• advanced.temperature - mezi 0.0 a 1.0
• chatMemory.summariesToKnowledgeRatio - celé číslo mezi 10 a 90 (procenta, krok 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - mezi 0 a 500
• appearance.footerMarkdown - maximálně 255 znaků
• humanSupport.enabled=true vyžaduje nastavení humanSupport.email
• leadCollection.enabled=true vyžaduje, aby alespoň jedna z hodnot leadCollection.emailEnabled nebo leadCollection.phoneEnabled byla nastavena na true; u zapnutého kanálu je rovněž vyžadován příslušný popisek a pole leaveDetailsMessage i thankYouMessage
• Omezená pole (advanced.chatContextSize, advanced.botMessagesLimit atd.) jsou automaticky a bez varování omezena podle limitů vašeho účtu

Pole, jejichž hodnota je na serveru null, jsou v těle JSONu vynechána - po síti se přenášejí pouze pole s nenulovými hodnotami.

Kompletní tělo odpovědi (201)

Stejná struktura jako u požadavku, navíc s blokem meta určeným pouze pro čtení a jednorázovým klíčem apiKey na nejvyšší úrovni. Adresy URL souborů určené pouze pro čtení (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) jsou serverem vyplněny tehdy, pokud byly nahrány odpovídající multipart části.

{
  "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 se zobrazuje pouze při vytvoření - jedná se o nově vygenerovaný klíč k Bot Talk API svázaný s novým botem. Čistý text klíče se zobrazí pouze jednou a později jej již nelze z API získat; bezodkladně si jej uložte na své straně.

Hlavička odpovědi Location obsahuje URL nového bota (/v1/management/bots/{id}).

Příklady pro curl

Režim A - čistý JSON (nejjednodušší):

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!"}}'

Režim B - multipart s avatarem:

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}

Vrátí aktuální konfiguraci bota, kterého vlastníte.

Příklad pro curl

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

Kompletní tělo odpovědi (200)

Stejná struktura jako u odpovědi na POST, bez jednorázového pole apiKey. Blok meta je zahrnut. Pokud bot neexistuje nebo nepatří k vašemu účtu, vrátí kód 404 not_found_error.

Aktuální avatar a logo pro White Label jsou k dispozici jako plně kvalifikované adresy URL určené pouze pro čtení (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - odvozené od stejného schématu + hostitele + kontextové cesty, které obsloužily tento požadavek. Samotná data získáte odesláním požadavku GET přímo na tyto adresy URL; pro nahrazení kteréhokoli souboru nahrajte nový soubor prostřednictvím multipart části avatar / whitelabel_logo v požadavku PATCH. Pokud jsou tato pole s adresami URL odeslána v těle požadavku, jsou ignorována.

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

Klonování bota

Tělo požadavku POST /v1/management/bots a tělo odpovědi GET /v1/management/bots/{bot_id} mají stejnou strukturu, takže klonování probíhá ve třech krocích: načtěte zdrojový bot pomocí GET, odstraňte identifikační pole spravovaná serverem a výsledek odešlete pomocí POST.

1. Získejte zdrojového bota pomocí GET.

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

2. Odstraňte blok meta na nejvyšší úrovni. Objekt meta (id, createdAt, updatedAt) spravuje server a je určen pouze pro čtení - jeho ponechání v těle požadavku POST ničemu nevadí (server ho ignoruje), ale jeho odstraněním jasně vyjádříte svůj záměr a udržíte payload čistý. Volitelně můžete upravit pole name, aby byl klon snadno k rozeznání od předlohy.

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

3. Odešlete upravené tělo pomocí POST pro vytvoření klonu. Úplnou strukturu těla a pravidla pro ověřování naleznete výše v referenční příručce k POST /v1/management/bots.

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

Odpověď obsahuje meta.id nového bota a nově vygenerovaný klíč apiKey (klíč Bot Talk pro daný klon). Klíč apiKey v prostém textu se vrací pouze v této odpovědi na vytvoření - před zahozením těla odpovědi si jej zkopírujte; později jej již nelze znovu získat.

Dvě důležitá upozornění:

• Soubory se neklonují. Pole appearance.avatarUrl a whiteLabel.whitelabelLogoUrl jsou určena pouze pro čtení a odkazují na soubory zdrojového bota. Pokud u klonu potřebujete stejného avatara nebo logo White Label, stáhněte si data ze zdrojových URL adres a nahrajte je jako části multipart požadavku avatar / whitelabel_logo - buď přímo při volání POST při vytváření (Režim B), nebo v následném požadavku PATCH.
• Klíče Bot Talk se neklonují. Každý bot má svůj vlastní fond klíčů Bot Talk. Jediný klíč apiKey vrácený v odpovědi na požadavek POST při vytvoření je ten, který se vygeneruje automaticky; další klíče můžete v případě potřeby vytvořit na kartě API daného bota.

PATCH /v1/management/bots/{bot_id}

Aktualizujte jedno nebo více polí u bota, kterého vlastníte. Upravují se pouze sekce a pole obsažená v JSONu; vše vynechané (nebo odeslané jako null) zůstává beze změny. V rámci odeslané sekce platí pravidla pro částečnou aktualizaci jednotlivých polí.

Podporovány jsou dva rovnocenné typy Content-Type (stejně jako u POST):

Režim A - prostý JSON (doporučeno, pokud aktualizujete pouze nastavení):

• Content-Type: application/json
• Tělo požadavku je přímo upravující JSON (bez obalovacího pole data)

Režim B - multipart/form-data (použijte při nahrávání souborů):

• JSON část data (volitelná) - samotné úpravy. Odesílejte pouze v případě, že chcete měnit pole. Zcela vynechte, pokud chcete nahrát pouze avatara nebo logo.
• Souborová část avatar (volitelná) - nahrazení avatara
• Souborová část whitelabel_logo (volitelná) - nahrazení loga White Label (platí pouze v případě, že váš účet zahrnuje funkci White Label)

Všechny tři části jsou u metody PATCH volitelné, pro smysluplné volání však musí být přítomna alespoň jedna.

Úplné tělo požadavku (maximální rozsah)

V tomto požadavku lze odeslat jakékoli pole, které přijímá metoda POST /v1/management/bots. Níže uvedený příklad představuje úplný rozsah; v praxi odesíláte pouze klíče, které chcete změnit (viz „Minimální částečná aktualizace“ níže) - každý vynechaný klíč (nebo klíč odeslaný jako null) ponechá uloženou hodnotu beze změny.

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

Minimální částečná aktualizace

Jednotlivé pole upravíte pomocí PATCH tak, že odešlete přesně ty klíče, které chcete změnit - vše ostatní zůstane zachováno.

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

Příklady curl

Režim A - prostý JSON (nejjednodušší):

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"}}'

Režim B - multipart (při nahrazování avatara / loga):

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'

Režim B - nahrazení pouze avatara (beze změn polí):

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

Tělo odpovědi (200)

Stejná struktura jako u GET /v1/management/bots/{bot_id} - úplná konfigurace bota po aplikování změn, včetně bloku meta. Bez pole apiKey. Pokud bot neexistuje nebo nepatří k vašemu účtu, vrátí chybu 404 not_found_error.

Níže uvedený příklad znázorňuje odpověď po aplikování výše zmíněného požadavku Úplné tělo požadavku (maximální rozsah) na bota z příkladu GET - změněná pole odrážejí nové hodnoty, nedotčená pole jsou zachována a hodnota meta.updatedAt se aktualizuje.

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

Zjištění aktuálního využití předplatného pro účet, který vlastní klíč Management.

Tělo odpovědi (200)

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

• subscriptionType je malými písmeny zapsaný identifikátor aktuálního plánu účtu (např. standard v tomto příkladu). Plány pocházejí z dynamického katalogu, takže přesná sada identifikátorů se může v průběhu času měnit s tím, jak jsou plány přejmenovávány nebo přidávány - pracujte s touto hodnotou jako s obecným řetězcem, nikoli jako s pevným výčtem enum.
• messages.used / limit / remaining představují kredity zpráv pro aktuální zúčtovací období.
• bots.used / limit / remaining započítávají aktivní boty do limitu počtu botů vašeho účtu.

Hlavičky rate limitu

Odpovědi, které dosáhnou fáze rate limitu (tj. prošly autentizací a IP whitelistem), obsahují:

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

• X-RateLimit-Limit - limit na klíč skutečně použitý pro toto volání (ve výchozím nastavení 10, nebo vaše nakonfigurovaná hodnota rateLimitPerMinute, pokud je nižší).
• X-RateLimit-Remaining - zbývající tokeny v zásobníku bezprostředně po tomto volání.
• X-RateLimit-Reset - čas v sekundách Unix epochy, kdy bude k dispozici další token (nejedná se o úplné obnovení zásobníku; zásobník se doplňuje průběžně). Když je zásobník plný, odpovídá tato hodnota aktuálnímu času.

U odpovědí 429 rate_limit_exceeded je nastavena také hlavička Retry-After, vyjádřená v celých sekundách do uvolnění alespoň jednoho tokenu.

Chyby před autentizací (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) a 403 ip_not_whitelisted neobsahují hlavičky X-RateLimit-* - limiter se uplatňuje až po úspěšném ověření autentizace a IP adresy.

Formát chyb

Stejný formát obálky jako u Bot Talk API:

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

Validační chyby používají code: "invalid_parameter" a před zprávu připojují cestu k chybnému poli, takže problematickou část snadno identifikujete:

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

Neplatné hodnoty pro pole typu enum / uzavřenou množinu hodnot (např. chatMemory.clientSummaryPromptType = "BOGUS") obsahují cestu k poli, odmítnutou hodnotu a seznam povolených hodnot:

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

Související

Informace o konverzačních endpointech a SSE streamování najdete v dokumentaci Bot Talk API.