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 požadavků a poté formulář odešlete.
3. Vyberte pouze ta oprávnění, která vaše integrace potřebuje, a zkopírujte celý klíč z potvrzovacího okna. Text v nezašifrované podobě se zobrazí pouze jednou.
4. Uložte jej na svůj server, nikoli do kódu prohlížeče nebo veřejného repozitáře. Pro ověření přístupu proveďte požadavek pouze pro čtení, například GET /v1/usage s oprávněním usage.
5. Nepoužívané nebo kompromitované klíče zneplatněte na stránce Management API.

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: vnořené sekce odpovídající záložkám v administraci

POST a PATCH přijímají tělo JSON rozdělené do 13 sekcí. Každá sekce odpovídá podzáložce v postranním panelu Bot Settings v administrátorské aplikaci, takže klíče JSON a viditelné záložky si přímo odpovídají: pokud změníte consent.humanSupportRequirePolicyAccept přes API, uvidíte stejný přepínač změněný na záložce Consent & Privacy v administraci.

• role - persona bota, nezpracovaný 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í + tooltipy, 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í, alokace 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 lidský kontakt (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í doba trvání (záložka Voice Conversation)
• multilingual - vícejazyčný režim, výchozí jazyk, nabízené jazyky, práce se znalostmi v různých jazycích (záložka Languages)
• advanced - model LLM, teplota, velikost kontextu, limit zpráv bota, interní národní prostředí, Offer Cards (záložka Model & Advanced)

Ze zapisovatelných nastavení se pouze name nachází na nejvyšší úrovni, protože bota identifikuje, místo aby patřilo pod konkrétní záložku.

Postranní panel Bot Settings má v současnosti 16 podzáložek a 13 z nich odpovídá výše uvedeným sekcím. Tři podzáložky bez odpovídající sekce jsou Flow, Actions a Forms - všechny tři jsou popsány níže v sekci „Mimo rozsah API“. Těch 13 odpovídajících tvoří 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 mají stejnou strukturu. Odpověď obsahuje dva prvky navíc:

• meta - pouze pro čtení: ID bota a časová razítka. Odstraňte je, 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 ve sdílené struktuře jsou pouze pro čtení - vrací se v odpovědi, ale při odeslání v požadavku 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). Pomocí GET z ní přímo stáhnete 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ý princip jako u avatarUrl. Chcete-li logo změnit, nahrajte nový soubor přes multipart část whitelabel_logo (viz PATCH).

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

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

Sestavení role a promptu

Systémový prompt, který LLM skutečně obdrží, se sestavuje jedním ze dvou způsobů v závislosti na role.role. Když víte, v jaké větvi se nacházíte, snadno zjistíte, která pole mají vliv a která se sice uloží, 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 pole role.rawPrompt zcela ignoruje (hodnota zůstává u bota uložena, jen se nepoužije). Šablona zahrnuje:

• role.role - označení role (např. „Customer Support“) a automaticky připojené instrukce specifické pro danou roli
• name - jméno bota vložené do úvodní věty
• role.language - hodnota "Auto Detect" přepne bota tak, aby odpovídal v jazyce uživatele; jakákoli jiná hodnota (např. "English", "Polish") se převede na instrukci „Output in {language}, unless user uses another language“
• role.responseLength - mapováno 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 instrukce 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 přímo v základu.

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

Backend použije role.rawPrompt jako prompt role a připojí fixní pokyny platformy ohledně délky odpovědi. To funguje odděleně od role.responseLength: volitelné nastavení Concise/Normal/Detailed se pro roli CUSTOM nevkládá. Stejně tak pole language, websiteAddress a companyDescription se sice uloží, ale do tohoto promptu role se nevkládají. Požadovaný jazyk, cílovou délku odpovědi i kontext společnosti zahrňte přímo do pole rawPrompt sami. Během zpracování dotazu mohou být předány také další runtime instrukce a dohledaný kontext, takže rawPrompt netvoří celý vstup modelu. Instrukce k tónu z předdefinované role se nepřidávají, volba CUSTOM však neodstraňuje veškeré instrukce platformy.

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

Výčtová pole / pole s pevně stanovenou sadou hodnot

Výčtová a omezená pole neplatné hodnoty odmítají s chybou 400 invalid_parameter. Ostatní pole jsou běžné textové řetězce, i když uživatelské rozhraní nabízí pevný seznam. Používejte zdokumentovanou podobu zápisu a ověřujte odesílaná data, místo abyste předpokládali, že každý nepodporovaný řetězec bude automaticky odmítnut.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - celý anglický název jazyka z rozbalovací nabídky v administraci, např. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi a zhruba 80 dalších. Hodnota se ukládá přesně tak, jak byla zadána, a dosazuje se do šablony promptu. Dvoupísmenné kódy ISO (en, pl) ani jiné hodnoty mimo seznam sice API neodmítne, vytvoří se však zkomolená instrukce typu „Output in en, unless...“. Pokud hodnotu při vytvoření vynecháte, použije se výchozí Auto Detect.
• advanced.model - viz sekce „Textové modely AI“ níže. Jde o řetězec, nikoli o validovaný výčet ve schématu požadavku; použijte podporovanou hodnotu, nikoli libovolný název modelu.
• advanced.chatContextSize - použijte 8000, 16000 nebo 32000 podle rozhraní. Hodnoty přesahující maximum účtu se tiše oříznou; DTO tuto sadu tří hodnot nevynucuje.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - booleovský přepínač. Hodnota true donutí uživatele vyplnit formulář pro leady před zahájením konverzace; hodnota false nechá rozhodnutí, kdy formulář zobrazit, na umělé inteligenci (výchozí nastavení).

Strukturovaná pole a číselné rozsahy

Pole, která na první pohled vypadají jako jednoduché textové řetězce nebo čísla, ale ve skutečnosti mají specifickou strukturu, rozsah 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 administraci. Hodnoty mimo tento rozsah jsou odmítnuty s chybou 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - celé číslo vyjadřující procenta, 10-90; uživatelské rozhraní nabízí kroky po 10, ale API přijímá libovolná celá čísla v daném rozsahu. Výchozí hodnota je 50. Při zapnuté paměti a kontextu větším než 8k rozděluje rozpočet na znalosti a paměť až po odečtení rezervy pro prompt a nedávnou konverzaci, nikoli z celého kontextu modelu. Při 8k se tímto nastavením žádný rozpočet pro shrnutí nepřiděluje.

• liveChat.schedule - JSON kódovaný jako řetězec, nikoli jako vnořený objekt JSON v odesílaných datech. Server ukládá nezpracovaný řetězec přesně tak, jak přišel; administrátorské rozhraní jej parsuje na straně klienta při vykreslování editoru provozní doby. Po naparsování má řetězec strukturu jedné položky pro každý den v týdnu plus klíč timezone:

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

  Příklad hodnoty (všimněte si vnějších uvozovek a escapovaných vnitřních uvozovek - jedná se 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ředání na live chat je potlačeno. Validace vnitřní struktury probíhá pouze na straně klienta v administrátorském rozhraní - neplatný JSON nebo neznámé klíče API přijme jednoduše jako řetězec a projeví se chybou vykreslování až ve chvíli, kdy bota v administraci otevře člověk. Před odesláním si strukturu na své straně ověřte.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krátké texty zobrazené u prvků hodnocení konverzace 👍 / 👎, pokud je nastaveno conversation.conversationRatingEnabled=true. Výchozí texty jsou „I like the response“ / „I don't like the response“. Viditelné pro koncové uživatele.

• whiteLabel.hideRoboAssistLogo - funkce White Label závislá na limitech vašeho účtu. Skryje řádek „Powered by ChatLab“ v zápatí. Pokud váš účet funkci White Label nezahrnuje, hodnota se sice uloží, ale ignoruje se a zápatí se vždy vykreslí.

• whiteLabel.whitelabelLogoLink - funkce White Label závislá na limitech vašeho účtu. Cílová URL adresa pro kliknutí na vlastní logo, pokud je nastaveno hideRoboAssistLogo=true a soubor vlastního loga byl nahrán přes multipart část whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nikoli milisekundy), celé číslo 0-200. Pauza mezi jednotlivými po sobě jdoucími bublinami bota, pokud platí simulateHumanTyping=true. Výchozí hodnota je 5.

• appearance.autoOpenChatDelaySeconds - sekundy, celé číslo. Prodleva před automatickým otevřením widgetu, pokud je nastaveno autoOpenChat=true a autoOpenChatDelay=true.

• advanced.internalLocale - kód národního prostředí a regionu dle IETF ve tvaru ll_CC (s podtržítkem, NIKOLI ll-CC se spojovníkem). Přijímané hodnoty vycházejí z pevného seznamu zhruba 95 národních prostředí: 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. Odeslání samotného dvoupísmenného kódu ("en") nebo formátu BCP-47 ("en-US") není na seznamu povolených hodnot. Výchozí hodnota je en_US. Toto národní prostředí se používá pro formátování kalendářních dat a čísel v ovládacích prvcích widgetu, na rozdíl od role.language (jazyk konverzačního výstupu bota).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - celá čísla (odesílejte jako čísla v JSON, např. 30, nikoli "30"). Chcete-li tento limit založený na relaci vypnout, nastavte limit zpráv na 0. Při zapnutí uveďte kladnou dobu trvání. Backend vymáhá N zpráv na relaci za danou dobu v sekundách, než návštěvníkovi zobrazí security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - celé číslo (v JSON jako číslo, např. 1000). Hodnota 0 znamená, že pro bota neplatí žádný dodatečný limit a řídí se pouze kreditním rozpočtem účtu; jinak musí jít o násobek 1 000 (1000, 2000, 10000, ...). Hodnoty jako 100 nebo 1500 jsou odmítnuty s chybou 400 invalid_parameter. Jedná se o měsíční limit kreditů pro bota, nikoli o počet zpráv v rámci konverzace. Mapovač tuto hodnotu neomezuje podle rozpočtu účtu; skutečné využití je i nadále limitováno rozpočtem účtu.

Textové modely AI (advanced.model)

Při čtení bota nakonfigurovaného s požadovaným modelem v nabídce Settings > Model & Advanced (Nastavení > Model a pokročilé) použijte přesný identifikátor modelu vrácený v poli advanced.model. Aktuální výchozí hodnota při vytvoření je 5.6-LUNA. V identifikátorech záleží na velikosti písmen a liší se od zobrazovaných názvů; například 5.6-LUNA se zobrazuje jako GPT 5.6-luna.

Katalog modelů se v průběhu času mění. Z pouhého faktu, že schéma požadavku přijímá řetězec, nevyvozujte, že je podporován jakýkoli libovolný text nebo veřejné ID modelu od poskytovatele. Než chatbota nasadíte, načtěte si uloženou konfiguraci a otestujte ho.

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

Podporované sekce a pole včetně jejich typů a důležitých omezení. Sémantika PATCH: jakékoli vynechané pole (nebo odeslané jako null) ponechá uloženou hodnotu beze změny. Stejná struktura se používá i pro odpověď (bez binárního obsahu multipart; plus blok meta určený pouze pro čtení u každé odpovědi a apiKey pouze u odpovědi na vytvoření).

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řítomné pouze v odpovědi:

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

§ role

Pole	Typ	Omezení	Popis
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Předvolba persony; vybírá šablonu promptu (viz „Sestavení role a promptu“)
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á výřečnost odpovědí AI
websiteAddress	string		Web použitý pro kontext promptu
companyDescription	string		Popis společnosti použitý pro kontext promptu
rawPrompt	string		Vlastní systémový prompt - použit doslovně pouze v případě 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 true, zpřesní otázku návštěvníka před vyhledáváním RAG
conversationContinuityEnabled	boolean		Pokud je true, vracející se návštěvníci pokračují ve své poslední konverzaci
conversationRatingEnabled	boolean		Pokud je true, zobrazí ovládací prvky pro hodnocení konverzace palcem nahoru/dolů
positiveRatingTooltip	string		Popisek u tlačítka kladného hodnocení
negativeRatingTooltip	string		Popisek u tlačítka záporného hodnocení
suggestedQuestions	string		Navrhované otázky / podněty ke konverzaci oddělené novým řádkem
dynamicSuggestedFollowups	boolean		Pokud je true, AI po každé odpovědi navrhne doplňující otázky
positiveRatingMessage	string		Zpráva zobrazená po kladném hodnocení
negativeRatingMessage	string		Zpráva zobrazená po záporném hodnocení
hideSuggestedQuestionsAfterFirstUse	boolean		Po použití skrýt statické návrhy
dynamicFollowupsAutoIcons	boolean		Pokud je true, AI automaticky vybere ikony emoji pro dynamické doplňující návrhy

§ chatMemory

Pole	Typ	Omezení	Popis
enabled	boolean		Hlavní přepínač funkce paměti chatu
summaryConversationsEnabled	boolean		Ukládat shrnutí jednotlivých konverzací
conversationSummaryPrompt	string		Vlastní prompt použitý ke shrnutí každé konverzace
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Určuje, zda se má použít výchozí nebo vlastní prompt pro shrnutí
clientSummaryPrompt	string		Vlastní prompt použitý ke shrnutí informací o klientovi napříč konverzacemi
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Výchozí vs. vlastní prompt pro profil klienta
summariesToKnowledgeRatio	int	10-90 (krok v UI 10)	% dostupného rozpočtu znalostí/paměti přiděleného shrnutím při kontextech nad 8k

§ appearance

Pole	Typ	Omezení	Popis
launcherLabelLine1	string	max 60	První řádek textu spouštěče
launcherLabelLine2	string	max 60	Druhý řádek textu spouštěče
launcherTextColor	string		Barva textu spouštěče
launcherDismissEnabled	boolean		Povolit zavření spouštěče
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Rodina písma widgetu
chatDrawerEnabled	boolean		Povolit zobrazení ve formě bočního panelu (drawer)
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 zprávy návštěvníka
clientMessageTextColor	string (hex)		Barva textu zprávy návštěvníka
responseMessageBubbleColor	string (hex)		Barva bubliny odpovědi bota
responseMessageTextColor	string (hex)		Barva textu odpovědi bota
chatSubheader	string		Podtitul zobrazený pod názvem chatu
senderPlaceholder	string		Zástupný text v poli pro zadání zprávy
resetConversationTooltip	string		Popisek 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 spodního okraje (px)
launcherSideMargin	int	0-500	Vzdálenost spouštěče od bočního okraje (px)
displayShadow	boolean		Vržený stín pod widgetem
customCss	string		Přímý kód CSS vložený do prvku iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Způsob otevírání odkazů ve zprávách bota
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Minimalizovaný stav: ikona spouštěče, kompaktní lišta odesílatele nebo pilulka
chatDesktopWidthPx	int		Šířka widgetu na počítači
chatDesktopHeightPx	int		Výška widgetu na počítači
chatMobileSizePercent	int		Velikost widgetu na mobilu v % výřezu obrazovky
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 místo odsazení
welcomeScreenEnabled	boolean		Zobrazit uvítací obrazovku místo přímého přechodu do chatu
welcomeScreenQuestionsLabel	string		Text nad navrhovanými otázkami na uvítací obrazovce
welcomeScreenHideHumanContactForm	boolean		Skrýt akci formuláře lidské podpory 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 2026-09-02 je výchozí hodnota true
welcomeScreenHideLiveChat	boolean		Skrýt akci živého chatu 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 2026-09-02 je výchozí hodnota true
headerActionsLayout	string	ICONS nebo DROPDOWN	Způsob nabídky živého chatu a formuláře lidské podpory v záhlaví chatu: ICONS (samostatná ikona pro každý) nebo DROPDOWN (seskupeno v nabídce záhlaví). U botů vytvořených před 2026-09-02 je výchozí hodnota ICONS
stackSuggestedQuestions	boolean		Řadit navrhované otázky svisle (oproti zobrazení vedle sebe)
suggestedQuestionsFontSize	int		Velikost písma štítků s navrhovanými otázkami (px)
suggestedQuestionsTextColor	string (hex)		Barva textu štítku s navrhovanou otázkou
suggestedQuestionsBackgroundColor	string (hex)		Barva pozadí štítku s navrhovanou otázkou
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 jednotlivými bublinami zpráv (sekundy)
footerMarkdown	string	max 255	Vlastní zápatí ve formátu markdown zobrazené pod chatem
avatarUrl	string	pouze pro čtení	Plně kvalifikovaná veřejná URL adresa avatara; pro změnu nahrajte soubor prostřednictvím multipart části avatar

Multipart při POST/PATCH: avatar (část se souborem). Těla odpovědí u požadavků GET obsah souboru vynechávají - přenáší se pouze URL adresa.

§ humanSupport

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač toku lidské podpory
email	string	povinné (striktní při vytvoření), když enabled=true	Adresa, která přijímá e-maily lidské podpory
dialogMessage	string		Motivační 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 poli pro zprávu
emailWithConversationContent	boolean		Pokud je true, zahrne přepis konverzace do těla e-mailu
customFormId	long	ID existujícího vlastního formuláře	Nahradí vestavěný kontaktní formulář vlastním formulářem. Při vytvoření se při vynechání použije vestavěný formulář; u PATCH ponechá null aktuální výběr beze změny
customFormMapping	string	řetězec kódovaný jako JSON	Mapuje pole vlastního formuláře na pole e-mailu lidské podpory

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

§ leadCollection

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač formuláře pro sběr kontaktů
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í), když 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í), když enabled=true A ZÁROVEŇ phoneEnabled=true	Popisek pole pro telefon
leaveDetailsMessage	string	povinné (striktní při vytvoření), když enabled=true	Zpráva vyzývající návštěvníka k zanechání údajů
thankYouMessage	string	povinné (striktní při vytvoření), když enabled=true	Potvrzení zobrazené po odeslání
requireBeforeNewConversation	boolean		Pokud je true, formulář musí být odeslán před zahájením chatu; pokud je false, AI rozhodne, kdy formulář nabídnout
emailNotificationEnabled	boolean		Odeslat e-mail majiteli při každém získání kontaktu
emailNotificationAddress	string		Příjemce oznámení (ve výchozím nastavení e-mail účtu)
emailWithConversationContent	boolean		Pokud je true, zahrne přepis konverzace do oznámení

| customFormId | long | ID existujícího vlastního formuláře | Nahradí vestavěný formulář pro kontakty vlastním formulářem. Při vytvoření se při vynechání použije vestavěný formulář; u PATCH ponechá null aktuální výběr beze změny | | customFormMapping | string | řetězec kódovaný jako JSON | Mapuje pole vlastního formuláře na jméno / e-mail / telefon |

Pravidlo mezi poli (striktní při vytvoření): enabled=true vyžaduje alespoň jedno z polí emailEnabled nebo phoneEnabled. requirePolicyAccept se nachází v consent.leadCollectionRequirePolicyAccept, nikoli zde.

§ 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
startMessage	string		Zpráva zobrazená při zahájení relace živého chatu
endMessage	string		Zpráva zobrazená při ukončení relace živého chatu
nameLabel	string		Popisek pole pro jméno v předformuláři pro Live Chat
emailLabel	string		Popisek pole pro e-mail v předformuláři pro Live Chat
schedule	string	řetězec kódovaný jako JSON (přepínače dnů v týdnu + from/to + timezone)	Provozní doba živého chatu - přesný formát najdete v části „Strukturovaná pole a číselné rozsahy“
outOfHoursMessage	string		Zpráva zobrazená mimo provozní dobu
closeModalMessage	string		Název modálního okna „ukončit živý chat?“
closeModalConfirmLabel	string		Popisek potvrzovacího tlačítka v modálním okně ukončení
closeModalCancelLabel	string		Popisek tlačítka zrušení v modálním okně ukončení
closeModalTooltipText	string		Popisek u prvku pro ukončení chatu
operatorHasJoinedLabel	string		Oznámení zobrazené po připojení operátora
operatorDidNotJoinInTimeLabel	string		Oznámení zobrazené v případě, že se žádný operátor nepřipojí v časovém limitu
waitingForOperatorToJoinLabel	string		Oznámení zobrazené během čekání na operátora
waitingForOperatorSeconds	int		Časový limit pro přijetí konverzace operátorem (sekundy)
redirectToHumanSupportForm	boolean		Pokud je true, při nepřijetí konverzace operátorem přejde na formulář lidské podpory
requireAdminOnline	boolean		Vyžadovat dostupného operátora podle nastavení přítomnosti
presenceMode	string		Režim přítomnosti; použijte hodnotu z bota nakonfigurovaného v UI
hideHumanSupportWhenLiveChatAvailable	boolean		Skrýt kontaktní formulář, pokud je živý chat dostupný
missedEmailEnabled	boolean	výchozí true	Odeslat majiteli bota e-mail, pokud žádost o živý chat zůstala bez odpovědi. U starších botů není nastaveno, což se interpretuje jako povoleno

requirePolicyAccept se nachází v 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 živého chatu
newConversationConsentDescription	string		Úvodní text obrazovky se souhlasem při zahájení konverzace
privacyPolicyConsentCheckboxLabel	string		Text vedle zaškrtávacího políčka 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	URL adresa, 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á URL adresa loga white-label; pro změnu nahrajte soubor prostřednictvím multipart části whitelabel_logo

Multipart při POST/PATCH: whitelabel_logo (část se souborem). Těla odpovědí u požadavků GET obsah souboru vynechávají - přenáší se pouze URL adresa.

§ security

Pole	Typ	Omezení	Popis
allowedDomains	string		Čárkami oddělený seznam domén s povolením vkládat widget (prázdné = bez omezení seznamem povolených domén)
spamFilterEnabled	boolean		Povolit antispamový filtr pro příchozí zprávy daného bota
countryFilterMode	string	BLACKLIST nebo WHITELIST	Způsob interpretace seznamů zemí. Samotné seznamy zůstávají přístupné pouze správcům
talkMessagesRateLimit	int	>= 0; hodnota 0 vypíná	Maximální povolený počet zpráv od uživatele v okně limitu rychlosti
talkMessagesRateLimitDurationSeconds	int	>= 0	Délka okna limitu rychlosti (sekundy)
talkMessagesRateLimitHitMessage	string		Zpráva zobrazená návštěvníkovi při dosažení limitu rychlosti

§ voice

Pole	Typ	Omezení	Popis
inputEnabled	boolean		Povolit 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	identifikátor hlasu specifický pro poskytovatele (např. alloy)	Který syntetický hlas mluví
model	string	např. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Hlasový model. Účtováno po minutách, sazby se liší podle modelu
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í hlasový jazyk
additionalLanguages	string	čárkami oddělené kódy jazyků	Další jazyky, které hlasový agent přijímá
maxDurationSeconds	int		Pevný limit pro jednu hlasovou konverzaci
maxDurationMessage	string		Zpráva zobrazená při dosažení limitu

§ multilingual

Pole	Typ	Omezení	Popis
enabled	boolean		Přepínač vícejazyčného režimu
mode	string	AUTODETECT nebo FIXED_LIST	Způsob, jakým bot vybírá 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	NONE, MAIN nebo DYNAMIC	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 „Textové modely AI“ výše	Identifikátor LLM (např. 5.6-LUNA)
temperature	decimal	0.0-1.0	Vzorkovací teplota (odpovídá posuvníku v UI)
chatContextSize	int	∈ {8000, 16000, 32000}; automaticky omezeno na limit vašeho účtu	Nakonfigurovaný rozpočet kontextu, včetně instrukcí, historie a znalostí
botMessagesLimit	long	0 nebo násobek 1000 (např. 1000, 2000, 10000)	Měsíční limit kreditů na zprávy bota (0 = bez dodatečného limitu bota; limit účtu stále platí)
internalLocale	string	kód národního prostředí ve formátu ll_CC	Národní prostředí pro popisky rozhraní widgetu (odlišné od role.language)
productsViewEnabled	boolean		Pokud je true, zpřístupní karty nabídek Offer Cards pro e-commerce v chatu
includeProductsInKnowledgeBase	boolean		Pokud je true, zaindexuje katalog produktů jako součást znalostní báze

Mimo rozsah API

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

• Trénování a mazání - tyto koncové body neumožňují výpis všech botů, správu trénovacích datových sad ani mazání botů. Pro tyto postupy použijte aplikaci.
• Karta Flow - vizuální editor toku konverzace (Flow Editor - fáze a přechody). Není zpřístupněno přes Management API.
• Karta 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 zpřístupněny. Můžete však existující formulář k botovi připojit pomocí leadCollection.customFormId a humanSupport.customFormId.
• Vlastní ikony pro otevření / zavření chatu - customLauncherIconVisible, openChatIcon, closeChatIcon. API zpřístupňuje pouze hlavní multipart části avatar a whitelabel_logo.
• Seznamy IP adres a zemí - samotné záznamy jsou přístupné pouze správcům. Zpřístupněn je pouze režim interpretace prostřednictvím security.countryFilterMode.

Koncové body

POST /v1/management/bots

Vytvoří nového bota. Jsou podporovány dva ekvivalentní typy Content-Type; vyberte si 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 nebo logo):

• Content-Type: application/json
• Tělo požadavku je přímo konfigurační JSON bota (bez obalového prvku data)
• Soubory (avatar / logo) lze nahrát později prostřednictvím druhého 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=...
• Část data ve formátu JSON (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á) - white-label logo (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í.

Příklad těla požadavku

Toto je maximální JSON typu data - se všemi vyplněnými sekcemi. Odesílejte pouze ty sekce, které potřebujete; vše ostatní převezme 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

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

• name - povinné, max. 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 - max. 255 znaků
• humanSupport.enabled=true vyžaduje nastavení humanSupport.email
• leadCollection.enabled=true vyžaduje, aby alespoň jeden z parametrů leadCollection.emailEnabled nebo leadCollection.phoneEnabled byl nastaven na true; aktivovaný kanál zároveň vyžaduje zadání svého popisku a parametrů leaveDetailsMessage a thankYouMessage
• advanced.chatContextSize je automaticky omezeno na maximální podporovanou velikost kontextu daného účtu. Nepočítejte s tím, že by se ostatní číselná pole omezovala automaticky.

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

Příklad těla odpovědi (201)

Stejná struktura jako u požadavku, navíc s blokem meta (pouze pro čtení) a jednorázovým polem apiKey na nejvyšší úrovni. Adresy URL souborů určené pouze pro čtení (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) server vyplní, 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T10:11:02Z"
  },
  "apiKey": "ck_freshly_minted_bot_talk_key_here"
}

Pole apiKey se zobrazuje pouze při vytvoření - jde o nově vygenerovaný klíč k Bot Talk API svázaný s novým botem. Čistý text klíče se zobrazí pouze jednou a nelze jej z API později znovu získat; okamžitě 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ý patří k vašemu účtu.

Příklad pro cURL

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

Příklad těla odpovědi (200)

Stejná struktura jako u odpovědi 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 white-label logo jsou vráceny jako plně kvalifikované adresy URL pouze pro čtení (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - se stejným schématem, hostitelem a kontextovou cestou, které obsloužily tento požadavek. Samotná data stáhnete přímo metodou GET na tyto adresy URL. Chcete-li některý ze souborů nahradit, nahrajte nový soubor prostřednictvím multipart části avatar / whitelabel_logo v požadavku PATCH. Pokud tato pole s URL odešlete v těle požadavku, budou 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  },
  "meta": {
    "id": 4287,
    "createdAt": "2026-06-01T10:11:02Z",
    "updatedAt": "2026-06-01T11:02:19Z"
  }
}

Klonování bota

Tělo požadavku POST /v1/management/bots a tělo odpovědi GET /v1/management/bots/{bot_id} sdílejí stejnou strukturu, takže klonování probíhá ve třech krocích: načtení zdroje pomocí GET, odstranění polí identity spravovaných serverem a odeslání výsledku pomocí POST.

1. Načtěte 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) je spravován serverem a je pouze pro čtení - jeho ponechání v těle POST nezpůsobí žádnou škodu (server ho ignoruje), ale jeho odstranění jasně vyjadřuje záměr a udržuje payload čistý. Volitelně upravte name, aby byl klon odlišitelný od zdroje.

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 validace naleznete v referenci POST /v1/management/bots výše.

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ý apiKey (klíč Bot Talk pro daný klon). Nešifrovaná hodnota apiKey se vrací pouze v této odpovědi při vytvoření - zkopírujte si ji dříve, než tělo odpovědi zahodíte; později ji již nelze získat.

Tento postup zkopíruje podporovaná nastavení, nikoli plně natrénovaného chatbota. Trénovací obsah, historie konverzací, integrace/akce, Flow a definice formulářů se těmito koncovými body neklonují. Tato nastavení nakonfigurujte samostatně v aplikaci.

Další důležitá upozornění:

• Soubory se neklonují. appearance.avatarUrl a whiteLabel.whitelabelLogoUrl jsou pouze pro čtení a odkazují na soubory zdrojového bota. Pokud u klonu potřebujete stejného avatara nebo white-label logo, stáhněte si bajty ze zdrojových URL adres a nahrajte je jako části multipart avatar / whitelabel_logo - buď při vytváření pomocí POST (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ý apiKey vrácený požadavkem POST při vytvoření je ten, který se vygeneruje automaticky; další klíče vytvořte v případě potřeby na kartě API daného bota.

PATCH /v1/management/bots/{bot_id}

Aktualizujte jedno nebo více polí u bota, kterého vlastníte. Upraví se pouze sekce / pole přítomná v JSON; vše vynechané (nebo odeslané jako null) zůstane beze změny. V rámci odeslané sekce platí sémantika částečné aktualizace pro každé pole.

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

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

• Content-Type: application/json
• Tělo požadavku je přímo JSON pro patch (bez obalového prvku data)

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

• Část JSON data (volitelná) - samotný patch. Odešlete pouze tehdy, když chcete změnit pole. Zcela vynechte, pokud chcete nahrát pouze avatara nebo logo.
• Souborová část avatar (volitelná) - nahrazení avatara
• Souborová část whitelabel_logo (volitelná) - nahrazení white-label loga (platí pouze v případě, že váš účet zahrnuje funkci White Label)

Všechny tři části jsou u požadavku PATCH volitelné, ale alespoň jedna musí být přítomna, aby volání mělo smysl.

Příklad těla požadavku (více sekcí)

Lze zde odeslat jakékoli pole, které přijímá POST /v1/management/bots. Níže uvedený příklad znázorňuje několik sekcí, nikoli všechna podporovaná pole; v praxi posíláte pouze klíče, které chcete změnit (viz „Minimální částečná aktualizace“ níže) - každý vynechaný klíč (nebo 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

Aktualizujte jedno pole pomocí PATCH odesláním přesně těch klíčů, které chcete změnit - vše ostatní zůstane zachováno.

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

Příklady pro Curl

Režim A - čistý 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 GET /v1/management/bots/{bot_id} - úplná konfigurace bota po aplikaci patche, včetně bloku meta. Žádné pole apiKey. Pokud bot neexistuje nebo nepatří k vašemu účtu, vrátí se 404 not_found_error.

Níže uvedený příklad ukazuje odpověď po aplikaci výše uvedeného patche Úplné tělo požadavku (více sekcí) 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 posune dopředu.

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

Načtení aktuálního využití předplatného pro účet, který vlastní klíč Management.

Tělo odpovědi (200)

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

• subscriptionType je identifikátor aktuálního plánu účtu psaný malými písmeny (your-plan-id je ilustrativní zástupný symbol). Plány pocházejí z dynamického katalogu, takže přesná sada identifikátorů se může v čase měnit podle toho, jak jsou plány přejmenovávány nebo přidávány - přistupujte k tomu jako k neprůhlednému řetězci, nikoli jako k pevnému výčtu (enum).
• messages.used / limit / remaining představují kredity na zprávy za aktuální kalendářní měsíc, které se resetují první den v měsíci, nikoli v den obnovení předplatného. Jsou váženy kredity, nejedná se o prostý počet odpovědí.
• bots.used / limit / remaining počítají vlastněné boty, včetně pozastavených botů, oproti celkovému limitu 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.