Management API

Prehľad Management API

Rozhranie Management API slúži na administratívne činnosti (back-office), ktoré nezahŕňajú odosielanie chatových správ:

• programové vytvorenie bota pomocou POST /v1/management/bots
• načítanie konkrétneho bota, ktorého vlastníte, pomocou GET /v1/management/bots/{bot_id}
• aktualizácia konkrétneho bota pomocou PATCH /v1/management/bots/{bot_id}
• zobrazenie využitia predplatného pomocou GET /v1/usage

Kľúče Management API sú viazané na váš účet, nie na konkrétneho bota. Sú zámerne oddelené od kľúčov Bot Talk API, aby kompromitovaný chatovací kľúč nemohol upravovať vašich botov ani čítať fakturačné údaje.

Základná URL adresa (Base URL)

https://api.chatlab.com/aichat

Všetky koncové body (endpoints) v tomto článku sú relatívne k tejto základnej URL adrese.

Začíname

1. Otvorte administrátorskú aplikáciu a prejdite do Account Settings > Management API (Nastavenia účtu > Management API).
2. Kliknite na Create Management Key (Vytvoriť kľúč Management API), pomenujte ho, voliteľne nastavte zoznam povolených IP adries (whitelist) a obmedzenie rýchlosti požiadaviek (rate limit) a uložte.
3. Skopírujte celý kľúč z potvrdzovacieho modálneho okna. V nezašifrovanej podobe (plaintext) sa zobrazí iba raz.

Kľúč vyzerá ako mk_abcdefghijklmnopqrstuvwxyz012345. Predpona mk_ ho odlišuje od kľúčov Bot Talk (ck_).

Autentifikácia

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Odoslanie kľúča mk_ na koncový bod /v1/chat (alebo akýkoľvek iný koncový bod Bot Talk) vráti chybu 403 key_type_not_allowed. Odoslanie kľúča ck_ na /v1/management/* vráti rovnakú chybu.

Limity

• Maximálne 5 aktívnych kľúčov Management API na používateľa
• Maximálne 10 požiadaviek za minútu na jeden kľúč (algoritmus token bucket, kapacita 10, plynulé dopĺňanie rýchlosťou približne 1 token každých 6 sekúnd). Pri vytváraní je možné nastaviť nižšiu hodnotu - nastavte nižší rateLimitPerMinute, čím sa zníži strop a adekvátne sa upraví rýchlosť dopĺňania.

Oprávnenia

Každý kľúč Management API nesie ľubovoľnú podmnožinu troch nižšie uvedených oprávnení. Pri vytváraní musíte vybrať aspoň jedno z nich, inak bude požiadavka zamietnutá s chybou 400 invalid_request_error. Volanie koncového bodu s kľúčom, ktorému chýba požadované oprávnenie, vráti chybu 403 insufficient_permissions.

• bot_read - vyžaduje sa pre GET /v1/management/bots/{bot_id}
• bot_management - vyžaduje sa pre POST /v1/management/bots a PATCH /v1/management/bots/{bot_id}
• usage - vyžaduje sa pre GET /v1/usage

Štruktúra tela požiadavky: vnorené sekcie kopírujúce záložky v administrácii

Metódy POST a PATCH prijímajú telo vo formáte JSON rozdelené do 13 sekcií. Každá sekcia zodpovedá podzáložke v bočnom paneli Bot Settings (Nastavenia bota) v administrátorskej aplikácii, takže kľúče JSON presne zodpovedajú viditeľným záložkám: ak cez API zmeníte hodnotu consent.humanSupportRequirePolicyAccept, uvidíte rovnaké prepnutie voľby na záložke Consent & Privacy (Súhlas a ochrana osobných údajov) v aplikácii.

• role - rola bota, čistý prompt (raw prompt), dĺžka odpovedí, jazyk, kontext webu / spoločnosti (záložka Role & Behavior)
• conversation - uvítacia správa, spresňovanie otázok, kontinuita konverzácie, prepínač hodnotenia + popisy (tooltips), obsah navrhovaných otázok + dynamické nadväzujúce otázky (záložka Chat Conversation)
• chatMemory - prepínač pamäte chatu, prompty pre zhrnutia, alokácia kontextu (záložka Summaries & Memory)
• appearance - farby, texty, rozmery, vlastné CSS, uvítacia obrazovka, štýlovanie navrhovaných otázok, správanie automatického otvorenia, simulácia písania človekom, pätička v markdown (záložka Appearance)
• humanSupport - kontaktný formulár pre spojenie s človekom (záložka Human Contact Form)
• leadCollection - formulár na zber kontaktov / leadov (záložka Lead Collection)
• liveChat - odovzdanie na živý chat (záložka Live Chat)
• consent - všetky štyri prepínače súhlasu so zásadami ochrany osobných údajov a text obrazovky súhlasu (záložka Consent & Privacy)
• whiteLabel - skrytie loga, odkaz na vlastné logo, hosting na vlastnej doméne (záložka Whitelabel)
• security - povolené domény, spamový filter, limity rýchlosti odosielania správ (záložka Security)
• voice - hlasový vstup a hlasové konverzácie: model, hlas, jazyky, prompt, maximálne trvanie (záložka Voice Conversation)
• multilingual - viacjazyčný režim, predvolený jazyk, ponúkané jazyky, spracovanie jazykov bázy znalostí (záložka Languages)
• advanced - LLM model, teplota (temperature), veľkosť kontextu, limit správ bota, interná lokalizácia (locale), Offer Cards (záložka Model & Advanced)

Iba parameter name sa nachádza na najvyššej úrovni (top level), pretože identifikuje bota a nepatrí pod žiadnu konkrétnu záložku.

Bočný panel Bot Settings má v súčasnosti 15 podzáložiek, z ktorých 13 zodpovedá vyššie uvedeným sekciám. Dve podzáložky, ktoré nemajú zodpovedajúcu sekciu, sú Flow a Actions - obe sú popísané nižšie v časti "Mimo rozsahu API". Tých 13, ktoré mapovanie majú, sú Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation a Languages.

Telo požiadavky a telo odpovede majú rovnakú štruktúru. Odpoveď navyše obsahuje dve položky:

• meta - iba na čítanie (read-only): ID bota a časové pečiatky. Ich odstránením premeníte odpoveď z GET na platné telo požiadavky pre POST.
• apiKey - nachádza sa iba pri vytvorení - nanovo vygenerovaný kľúč Bot Talk API pre nového bota.

Dve polia v rámci spoločnej štruktúry sú iba na čítanie (read-only) - vracajú sa v odpovedi a ignorujú sa, ak sa ich pokúsite odoslať v POST/PATCH:

• appearance.avatarUrl - plne kvalifikovaná verejná URL adresa obrázka avatara bota (napr. https://api.chatlab.com/aichat/content/avatar_xyz.png). Priamym volaním GET stiahnete dáta obrázka. Ak ho chcete zmeniť, nahrajte nový súbor cez multipart časť avatar (pozrite sekciu PATCH).
• whiteLabel.whitelabelLogoUrl - plne kvalifikovaná verejná URL adresa loga v hlavičke pre White Label. Rovnaký princíp ako pri avatarUrl. Ak ho chcete zmeniť, nahrajte nový súbor cez multipart časť whitelabel_logo (pozrite sekciu PATCH).

Obe URL adresy využívajú schému + hostiteľa + kontextovú cestu aktuálnej požiadavky, takže pri vlastnej doméne funkcie White Label sa vrátia s adresou tejto domény (napr. https://api.acme.com/aichat/content/...).

Ak chcete pri požiadavke PATCH preskočiť celú sekciu, odošlite null. Ak chcete v rámci sekcie preskočiť jedno konkrétne pole, odošlite preň null. Hodnota null na úrovni poľa nikdy nevymaže uloženú hodnotu - znamená iba "nemení sa".

Konštrukcia roly a promptu

Systémový prompt, ktorý LLM v skutočnosti dostane, sa zostavuje jedným z dvoch spôsobov v závislosti od role.role. Znalosť vetvy vám napovie, na ktorých poliach záleží a ktoré sú iba uložené, ale ignorované.

Vetva A - role.role je CUSTOMER_SUPPORT, SALES alebo LEAD_COLLECTION_AGENT (riadené šablónou)

Backend zostaví prompt zo vstavanej šablóny a úplne ignoruje role.rawPrompt (hodnota zostáva uložená pri botovi, len sa nepoužije). Šablóna zahŕňa:

• role.role - označenie roly (napr. "Customer Support") a pokyny špecifické pre rolu pridané automaticky
• name - názov bota, vložený do úvodnej vety
• role.language - hodnota "Auto Detect" nastaví bota tak, aby reagoval v jazyku používateľa; akákoľvek iná hodnota (napr. "English", "Polish") sa zmení na "Output in {language}, unless user uses another language"
• role.responseLength - mapuje sa na cieľový počet slov: Concise ≈ 50 slov, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - voliteľné; ak nie je prázdne, pripojí sa ako "for the users of the website {url}"
• role.companyDescription - voliteľné; ak nie je prázdne, pridá sa ako ďalší odsek pred pokyny k role

Toto je odporúčaná vetva pre väčšinu botov - získate správanie prispôsobené konkrétnej role a bezpečnostné mantinely bez práce navyše.

Vetva B - role.role je CUSTOM (vlastný prompt dodaný volajúcim)

Backend použije role.rawPrompt doslovne ako celý systémový prompt. Polia responseLength, language, websiteAddress, companyDescription sa síce uložia, ale nevkladajú sa do promptu - ak chcete čokoľvek z toho premietnuť do správania bota, musíte to sami uviesť v texte rawPrompt. Nepridávajú sa ani bezpečnostné pravidlá špecifické pre rolu či pokyny k tónu komunikácie; celý prompt máte plne vo svojich rukách.

Hodnotu CUSTOM použite iba vtedy, ak prompt riadený šablónou nevyhovuje vášmu prípadu použitia (napr. potrebujete vysoko špecifickú persónu pre dané odvetvie, vlastné bezpečnostné obmedzenia alebo neštandardný formát výstupu).

Výčtové polia s pevnou množinou hodnôt (Enum)

Niekoľko polí prijíma iba pevne stanovenú množinu reťazcových hodnôt. Odoslanie akejkoľvek hodnoty mimo tohto zoznamu bude zamietnuté s chybou 400 validation_failed a cestou k poľu v error.param. V hodnotách záleží na veľkosti písmen (case-sensitive).

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - celý anglický názov jazyka z rozbaľovacieho zoznamu v administrácii, napr. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi a približne 80 ďalších. Hodnota sa ukladá doslovne a dopĺňa do šablóny promptu, takže dvojpísmenové kódy ISO (en, pl) a iné hodnoty mimo zoznamu API neodmietne, no vytvoria skomolený pokyn ako "Output in en, unless...". Ak sa vynechá pri vytváraní, predvolená hodnota je Auto Detect.
• advanced.model - pozrite časť "AI textové modely" nižšie; ponuka dostupných modelov závisí od limitov vášho účtu a akákoľvek hodnota, ktorú váš účet nemôže použiť, vráti chybu 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Podlieha limitom vášho účtu; vyššie hodnoty sa automaticky znížia 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). Hodnota true vyžaduje vyplnenie formulára pred začatím konverzácie; false necháva rozhodnutie o zobrazení formulára na AI (predvolené).

Štruktúrované polia a rozsahy

Polia, ktoré vyzerajú ako jednoduché reťazce alebo čísla, no v skutočnosti majú špecifickú štruktúru, rozsahy alebo osobitosti v administrátorskom rozhraní, o ktorých je dobré vedieť.

• advanced.temperature - povolený rozsah je 0.0 až 1.0, čo zodpovedá posuvníku v administrátorskom rozhraní. Hodnoty mimo tohto rozsahu sú odmietnuté s chybou 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - celé číslo v percentách, 10-90 s krokom 10. Určuje, aká časť kontextu chatu je vyhradená pre historické zhrnutia klienta v porovnaní so zvyškom (báza znalostí, aktuálna konverzácia, pokyny). Predvolená hodnota je 50. Hodnoty mimo rozsahu 10-90 sú odmietnuté s chybou 400 validation_failed. Uplatňuje sa iba vtedy, ak platí chatMemory.enabled=true A ZÁROVEŇ chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - reťazec vo formáte JSON (JSON encoded as a string), nie priamo vnorený objekt JSON v dátovom prenose. Server ukladá pôvodný reťazec presne v odoslanej podobe; administrátorské rozhranie ho analyzuje (parsuje) na strane klienta pri vykresľovaní editora rozvrhu. Po spracovaní má reťazec štruktúru s jednou položkou pre každý deň v týždni a kľúčom timezone:

  • každý kľúč dňa v týždni (monday-sunday) sa mapuje na {enabled: boolean, from: "H:MM", to: "H:MM"} v 24-hodinovom formáte
  • timezone predstavuje názov časového pásma podľa databázy IANA (napr. "Europe/Warsaw", "America/New_York")

  Príklad hodnoty (všimnite si vonkajšie úvodzovky a escapované vnútorné úvodzovky - ide o jedno reťazcové pole, nie o vnorený 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ých hodín sa návštevníkovi zobrazí správa z liveChat.outOfHoursMessage a možnosť prepnutia na live chat je potlačená. Validácia vnútornej štruktúry prebieha iba na strane klienta v administrátorskom rozhraní - neplatný JSON alebo neznáme kľúče API príjme jednoducho ako textový reťazec a prejavia sa ako chyba vykresľovania, až keď človek neskôr otvorí nastavenia bota v administrácii. Pred odoslaním si štruktúru skontrolujte na svojej strane.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krátke texty zobrazené na tlačidlách 👍 / 👎 vedľa každej odpovede umelej inteligencie, ak je nastavené conversation.conversationRatingEnabled=true. Predvolený text je "I like the response" / "I don't like the response". Viditeľné pre koncových používateľov.

• whiteLabel.hideRoboAssistLogo - funkcia White Label podliehajúca limitom vášho účtu. Skryje text "Powered by ChatLab" v pätičke. Ak váš účet nezahŕňa možnosť White Label, hodnota sa síce uloží, no ignoruje sa a pätička sa vždy zobrazí.

• whiteLabel.whitelabelLogoLink - funkcia White Label podliehajúca limitom vášho účtu. Cieľová URL adresa po kliknutí na vlastné logo, ak je hideRoboAssistLogo=true a súbor s vlastným logom bol nahraný cez multipart časť whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nie milisekundy), celé číslo 0-200. Pauza medzi jednotlivými bublinami správ bota, ak je aktívne simulateHumanTyping=true. Predvolená hodnota je 5.

• appearance.autoOpenChatDelaySeconds - sekundy, celé číslo. Oneskorenie pred automatickým otvorením widgetu, ak je autoOpenChat=true a autoOpenChatDelay=true.

• advanced.internalLocale - kód regiónu a jazyka podľa IETF vo formáte ll_CC (s podčiarkovníkom, NIE ll-CC so spojovníkom). Prijímané hodnoty vychádzajú z pevného zoznamu približne 95 lokalizácií: 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 mnohých ďalších. Samotný dvojpísmenový kód ("en") alebo formát BCP-47 ("en-US") v zozname povolených nie je. Predvolená hodnota je en_US. Táto lokalizácia sa používa na formátovanie dátumov a čísel v používateľskom rozhraní widgetu, na rozdiel od role.language (jazyk konverzačného výstupu bota).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - celé čísla (odosielajte ako čísla v JSON, napr. 30, nie "30"). Hodnota 0 deaktivuje limit na úrovni IP adresy. Pri nenulovej hodnote widget uplatňuje limit N správ za daný počet sekúnd pred tým, než sa návštevníkovi zobrazí správa security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - celé číslo (v JSON ako číslo, napr. 1000). Hodnota 0 znamená "bez limitu"; inak musí ísť o násobok čísla 1000 (1000, 2000, 10000, ...). Hodnoty ako 100 alebo 1500 sú odmietnuté s chybou 400 validation_failed. Následne sa hodnota automaticky obmedzí podľa limitu vášho účtu.

AI textové modely (advanced.model)

Odošlite presnú hodnotu pre API (stĺpec v spätných úvodzovkách vľavo). Zobrazovaný názov v administrácii je v zátvorke. To, ktoré modely si môžete vybrať, závisí od limitov vášho účtu; odoslanie modelu, ktorý váš účet nemôže používať, vráti chybu 400 invalid_parameter. Predvolená hodnota pre nových botov 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)

Prehľad polí (kompletná schéma požiadavky)

Každé pole prenášané v požiadavke spolu s jeho typom, obmedzením a jednoriadkovým popisom. Sémantika PATCH: akékoľvek vynechané pole (alebo odoslané ako null) ponecháva pôvodnú uloženú hodnotu nezmenenú. Rovnaká štruktúra sa používa aj pre odpoveď (okrem binárneho obsahu typu multipart; navyše s blokom meta určeným len na čítanie pri každej odpovedi a poľom apiKey, ktoré je prítomné iba pri odpovedi na vytvorenie).

Najvyššia úroveň

Pole	Typ	Obmedzenie	Popis
name	string	max 150, povinné pri vytvorení	Zobrazovaný názov bota
role	object		Pozrite § role
conversation	object		Pozrite § conversation
chatMemory	object		Pozrite § chatMemory
appearance	object		Pozrite § appearance
humanSupport	object		Pozrite § humanSupport
leadCollection	object		Pozrite § leadCollection
liveChat	object		Pozrite § liveChat
consent	object		Pozrite § consent
whiteLabel	object		Pozrite § whiteLabel
security	object		Pozrite § security
advanced	object		Pozrite § advanced

Prvky navyše prítomné iba v odpovedi:

• meta: { id, createdAt, updatedAt } - iba na čítanie.
• apiKey - string, prítomný iba v odpovedi na POST /v1/management/bots - novo vygenerovaný kľúč Bot Talk API pre nového bota, vrátený presne raz.

§ role

Pole	Typ	Obmedzenie	Popis
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Predvoľba osobnosti; vyberá šablónu promptu (pozrite „Vytváranie rolí a promptov“)
language	string	celý anglický názov jazyka (English, Polish, ...) alebo Auto Detect	Hlavný jazyk odovzdávaný do šablóny promptu
responseLength	string	∈ {Concise, Normal, Detailed}	Požadovaná podrobnosť odpovedí AI
websiteAddress	string		Webová stránka použitá ako kontext promptu
companyDescription	string		Popis spoločnosti použitý ako kontext promptu
rawPrompt	string		Vlastný systémový prompt - použije sa doslovne iba vtedy, keď role=CUSTOM

§ conversation

Pole	Typ	Obmedzenie	Popis
welcomeMessage	string		Prvá správa zobrazená návštevníkovi po otvorení
queryRefinementEnabled	boolean		Ak má hodnotu true, spresní otázku návštevníka pred vyhľadávaním v RAG
conversationContinuityEnabled	boolean		Ak má hodnotu true, vracajúci sa návštevníci pokračujú vo svojej poslednej konverzácii
conversationRatingEnabled	boolean		Ak má hodnotu true, zobrazí hodnotenie palcom hore/dole pri správach bota
positiveRatingTooltip	string		Text pomocného popisu na tlačidle pozitívneho hodnotenia
negativeRatingTooltip	string		Text pomocného popisu na tlačidle negatívneho hodnotenia
suggestedQuestions	string		Navrhované otázky / úvody do konverzácie oddelené novým riadkom
dynamicSuggestedFollowups	boolean		Ak má hodnotu true, AI po každej odpovedi navrhne doplňujúce otázky
dynamicFollowupsAutoIcons	boolean		Ak má hodnotu true, AI automaticky vyberie ikony emoji pre dynamické návrhy

§ chatMemory

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Hlavný prepínač pre funkciu pamäte chatu
summaryConversationsEnabled	boolean		Ukladať zhrnutia jednotlivých konverzácií
conversationSummaryPrompt	string		Vlastný prompt použitý na zhrnutie každej konverzácie
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Určuje, či sa použije predvolený alebo vlastný prompt na zhrnutie
clientSummaryPrompt	string		Vlastný prompt použitý na vytvorenie profilu klienta naprieč konverzáciami
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Predvolený verzus vlastný prompt profilu klienta
summariesToKnowledgeRatio	int	10-90, krok 10	% kontextového okna chatu pridelených zhrnutiam verzus znalostiam z RAG

§ appearance

Pole	Typ	Obmedzenie	Popis
launcherColor	string (hex)		Farba pozadia spúšťača (ikony chatu)
headerColor	string (hex)		Farba pozadia hlavičky chatu
titleColor	string (hex)		Farba nadpisu v hlavičke chatu
subtitleColor	string (hex)		Farba podnadpisu v hlavičke chatu
clientMessageBubbleColor	string (hex)		Farba bubliny správy návštevníka
clientMessageTextColor	string (hex)		Farba textu správy návštevníka
responseMessageBubbleColor	string (hex)		Farba bubliny odpovede bota
responseMessageTextColor	string (hex)		Farba textu odpovede bota
chatSubheader	string		Podtitulok zobrazený pod názvom chatu
senderPlaceholder	string		Zástupný text vo vstupe pre správu
resetConversationTooltip	string		Text pomocného popisu na tlačidle „resetovať konverzáciu“
chatAlignment	string (enum)	∈ {left, right}	Ku ktorej strane obrazovky je chat ukotvený
launcherBottomMargin	int	0-500	Vzdialenosť spúšťača od spodného okraja (px)
launcherSideMargin	int	0-500	Vzdialenosť spúšťača od bočného okraja (px)
displayShadow	boolean		Vrhaný tieň pod widgetom
customCss	string		Vlastný CSS kód vložený do rámca iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Spôsob otvárania odkazov vo vnútri správ bota
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Minimalizovaný stav: ikona spúšťača alebo kompaktná lišta odosielateľa
chatDesktopWidthPx	int		Šírka widgetu na desktope
chatDesktopHeightPx	int		Výška widgetu na desktope
chatMobileSizePercent	int		Veľkosť widgetu na mobile ako % zobrazenia
messageFontSize	int		Veľkosť písma textu správy (px)
showChatbotBubblesDesktop	boolean		Zobrazovať plávajúce pútavé bubliny na desktope
showChatbotBubblesMobile	boolean		Zobrazovať plávajúce pútavé bubliny na mobile
chatbotBubblesDelaySeconds	int		Oneskorenie pred zobrazením pútavých bublín (sekundy)
launcherIconFullSize	boolean		Vykresliť vlastnú ikonu spúšťača od okraja po okraj namiesto odsadenia
welcomeScreenEnabled	boolean		Zobraziť Welcome Screen (uvítaciu obrazovku) namiesto priameho prechodu do chatu
welcomeScreenQuestionsLabel	string		Štítok nad navrhovanými otázkami na uvítacej obrazovke
welcomeScreenHideHumanContactForm	boolean		Skryť možnosť kontaktného formulára na človeka v hlavičke počas zobrazenia Welcome Screen. Znova sa objaví po prvej správe návštevníka. Pre botov vytvorených pred 2026-09-02 je predvolená hodnota true
welcomeScreenHideLiveChat	boolean		Skryť akciu pre Live Chat v hlavičke počas zobrazenia Welcome Screen. Znova sa objaví po prvej správe návštevníka. Pre botov vytvorených pred 2026-09-02 je predvolená hodnota true
headerActionsLayout	string	DROPDOWN	Spôsob ponuky chatu naživo a kontaktného formulára v hlavičke chatu: ICONS (samostatná ikona pre každú) alebo DROPDOWN (zoskupené v menu hlavičky). Pre botov vytvorených pred 2026-09-02 je predvolená hodnota ICONS
stackSuggestedQuestions	boolean		Usporiadať navrhované otázky zvisle (oproti zobrazeniu vedľa seba)
suggestedQuestionsFontSize	int		Veľkosť písma tlačidiel s navrhovanými otázkami (px)
suggestedQuestionsTextColor	string (hex)		Farba textu tlačidiel s navrhovanými otázkami
suggestedQuestionsBackgroundColor	string (hex)		Farba pozadia tlačidiel s navrhovanými otázkami
autoOpenChat	boolean		Automaticky otvoriť chat na desktope
autoOpenChatOnMobiles	boolean		Automaticky otvoriť chat na mobile
autoOpenChatDelay	boolean		Použiť oneskorenie pred automatickým otvorením
autoOpenChatDelaySeconds	int		Oneskorenie automatického otvorenia (sekundy)
simulateHumanTyping	boolean		Rozdeliť odpoveď bota do bublín s animáciou písania
simulateHumanTypingDelay	int	0-200	Oneskorenie medzi jednotlivými bublinami správ (sekundy)
footerMarkdown	string	max 255	Vlastný markdown pätičky zobrazený pod chatom
avatarUrl	string	iba na čítanie	Plne kvalifikovaná verejná adresa URL avatara; ak ju chcete zmeniť, nahrajte súbor cez časť multipart avatar

Multipart pri POST/PATCH: avatar (súborová časť). Telá požiadaviek GET / odpovedí vynechávajú obsah súboru - prenáša sa iba adresa URL.

§ humanSupport

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač postupu zákazníckej podpory človekom
email	string	povinné (striktné pri vytvorení), keď enabled=true	Adresa, na ktorú chodia e-maily pre ľudskú podporu
dialogMessage	string		Povzbudzujúca správa zobrazená nad formulárom
thankYouMessage	string		Potvrdenie zobrazené po odoslaní
emailMessageSubjectTemplate	string		Šablóna predmetu e-mailu odoslaného agentovi
emailMessageContentTemplate	string		Šablóna tela e-mailu odoslaného agentovi
emailPlaceholder	string		Zástupný text vo vstupe pre e-mail
messagePlaceholder	string		Zástupný text v textovom poli pre správu
emailWithConversationContent	boolean		Ak má hodnotu true, zahrnie prepis konverzácie do tela e-mailu
customFormId	long	ID existujúceho vlastného formulára	Nahradí vstavaný kontaktný formulár vlastným formulárom. Hodnota null ponechá vstavaný formulár
customFormMapping	string	reťazec vo formáte JSON	Mapuje polia vlastného formulára na polia e-mailu pre ľudskú podporu

Nastavenie requirePolicyAccept sa nachádza v consent.humanSupportRequirePolicyAccept, nie tu.

§ leadCollection

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač formulára na zber kontaktov
nameEnabled	boolean		Zbierať meno
nameLabel	string		Štítok na vstupe pre meno
emailEnabled	boolean		Zbierať e-mail
emailLabel	string	povinné (striktné pri vytvorení), keď enabled=true A ZÁROVEŇ emailEnabled=true	Štítok na vstupe pre e-mail
phoneEnabled	boolean		Zbierať telefón
phoneLabel	string	povinné (striktné pri vytvorení), keď enabled=true A ZÁROVEŇ phoneEnabled=true	Štítok na vstupe pre telefónne číslo
leaveDetailsMessage	string	povinné (striktné pri vytvorení), keď enabled=true	Správa vyzývajúca návštevníka, aby zanechal svoje kontaktné údaje
thankYouMessage	string	povinné (striktné pri vytvorení), keď enabled=true	Potvrdenie zobrazené po odoslaní
requireBeforeNewConversation	boolean		Ak je true, formulár musí byť odoslaný pred začiatkom chatu; ak je false, AI rozhodne, kedy formulár zobraziť
emailNotificationEnabled	boolean		Poslať e-mail majiteľovi pri každom získaní nového leadu
emailNotificationAddress	string		Príjemca upozornení (predvolene e-mail účtu)
emailWithConversationContent	boolean		Ak má hodnotu true, zahrnie prepis konverzácie do upozornenia

Pravidlo vzájomnej závislosti pri vytváraní: enabled=true vyžaduje aspoň jedno z polí emailEnabled alebo phoneEnabled. Nastavenie requirePolicyAccept sa nachádza v consent.leadCollectionRequirePolicyAccept, nie tu.

| customFormId | long | ID existujúceho vlastného formulára | Nahradí vstavaný formulár na leady vlastným formulárom. Hodnota null ponechá vstavaný formulár | | customFormMapping | string | reťazec vo formáte JSON | Mapuje polia vlastného formulára na meno / e-mail / telefón |

§ liveChat

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač funkcie Live Chat
infoMessage	string		Vysvetľujúca správa pred odovzdaním operátorovi
startMessage	string		Správa zobrazená pri začatí živej relácie
endMessage	string		Správa zobrazená pri ukončení živej relácie
nameLabel	string		Štítok poľa pre meno v úvodnom formulári pred chatom naživo
emailLabel	string		Štítok poľa pre e-mail v úvodnom formulári pred chatom naživo
schedule	string	reťazec vo formáte JSON (prepínače dní v týždni + from/to + timezone)	Prevádzkový harmonogram pre Live Chat - presnú štruktúru nájdete v časti „Štruktúrované polia a rozsahy“
outOfHoursMessage	string		Správa zobrazená vtedy, keď je podľa harmonogramu mimo prevádzkových hodín
closeModalMessage	string		Názov modálneho okna „ukončiť chat naživo?“
closeModalConfirmLabel	string		Štítok potvrdzovacieho tlačidla v zatváracom okne
closeModalCancelLabel	string		Štítok tlačidla zrušenia v zatváracom okne
closeModalTooltipText	string		Text pomocného popisu prvku na zatvorenie chatu
operatorHasJoinedLabel	string		Štítok zobrazený po pripojení operátora
operatorDidNotJoinInTimeLabel	string		Štítok zobrazený v prípade, že sa žiadny operátor nepripojí v stanovenom časovom limite
waitingForOperatorToJoinLabel	string		Štítok zobrazený počas čakania na pripojenie operátora
waitingForOperatorSeconds	int		Časový limit na prevzatie konverzácie operátorom (sekundy)
redirectToHumanSupportForm	boolean		Ak má hodnotu true, presmeruje na formulár ľudskej podpory, ak žiadny operátor neodpovie
missedEmailEnabled	boolean	predvolene true	Poslať e-mail majiteľovi bota, keď požiadavka na chat naživo zostala bez odpovede. Pri starších botoch nie je nastavené, čo sa interpretuje ako povolené

Nastavenie requirePolicyAccept sa nachádza v consent.liveChatRequirePolicyAccept, nie tu.

§ consent

Pole	Typ	Obmedzenie	Popis
newConversationRequirePolicyAccept	boolean		Vyžadovať súhlas so zásadami ochrany osobných údajov pred začatím novej konverzácie
humanSupportRequirePolicyAccept	boolean		Vyžadovať súhlas so zásadami ochrany osobných údajov pred odoslaním formulára zákazníckej podpory
leadCollectionRequirePolicyAccept	boolean		Vyžadovať súhlas so zásadami ochrany osobných údajov pred odoslaním formulára na zber kontaktov
liveChatRequirePolicyAccept	boolean		Vyžadovať súhlas so zásadami ochrany osobných údajov pred začatím relácie Live Chat
newConversationConsentDescription	string		Úvodný text obrazovky so súhlasom pri spustení konverzácie
privacyPolicyConsentCheckboxLabel	string		Štítok vedľa začiarkavacieho políčka súhlasu (zvyčajne obsahuje odkaz na zásady ochrany osobných údajov)

§ whiteLabel

Pole	Typ	Obmedzenie	Popis
hideRoboAssistLogo	boolean	funkcia White Label; podlieha limitom účtu	Skryť predvolené logo ChatLab v pätičke
whitelabelLogoLink	string	funkcia White Label; podlieha limitom účtu	URL adresa, na ktorú odkazuje vlastné logo v pätičke
assignToCustomDomain	boolean	podmienené funkciou CUSTOM_DOMAIN	Prevádzkovať chat na nakonfigurovanej vlastnej doméne
whitelabelLogoUrl	string	iba na čítanie	Plne kvalifikovaná verejná adresa URL loga White Label; ak ju chcete zmeniť, nahrajte súbor cez časť multipart whitelabel_logo

Multipart pri POST/PATCH: whitelabel_logo (súborová časť). Telá požiadaviek GET / odpovedí vynechávajú obsah súboru - prenáša sa iba adresa URL.

§ security

Pole	Typ	Obmedzenie	Popis
allowedDomains	string		Čiarkami oddelený zoznam domén s povolením vložiť widget (prázdne = bez zoznamu povolených)
spamFilterEnabled	boolean		Zapnúť spamový filter pre prichádzajúce správy daného bota
countryFilterMode	string	BLACKLIST alebo WHITELIST	Spôsob interpretácie zoznamov krajín. Samotné zoznamy sú prístupné iba správcovi
talkMessagesRateLimit	int	>= 0; 0 vypína	Maximálny počet správ používateľa povolený v rámci časového okna limitu
talkMessagesRateLimitDurationSeconds	int	>= 0	Dĺžka časového okna limitu správ (sekundy)
talkMessagesRateLimitHitMessage	string		Správa zobrazená návštevníkovi pri dosiahnutí limitu počtu správ

§ voice

Pole	Typ	Obmedzenie	Popis
inputEnabled	boolean		Povoliť návštevníkovi diktovať správy (prevod reči na text)
conversationEnabled	boolean	vyžaduje hlasovú funkciu v predplatnom	Zapnúť plnohodnotné hlasové konverzácie
voiceId	string	ID hlasu špecifické pre poskytovateľa (napr. alloy)	Ktorý syntetický hlas rozpráva
model	string	napr. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Hlasový model. Účtované za minútu, sadzby sa líšia podľa modelu
turnDetection	string	špecifické pre poskytovateľa	Režim striedania replík
audioPrompt	string		Dodatočný systémový prompt použitý iba pre hlasové repliky
welcomeMessage	string		Hlasová uvítacia správa
language	string	kód jazyka	Hlavný jazyk hlasu
additionalLanguages	string	čiarkami oddelené kódy jazykov	Ďalšie jazyky, ktoré hlasový agent prijíma
maxDurationSeconds	int		Pevný limit dĺžky jednej hlasovej konverzácie
maxDurationMessage	string		Správa zobrazená pri dosiahnutí limitu

§ multilingual

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač viacjazyčného režimu
mode	string	AUTODETECT alebo režim pevného zoznamu	Spôsob, akým bot vyberá jazyk odpovede
baseLanguage	string	kód jazyka	Jazyk, v ktorom sú napísané pôvodné texty bota
languages	string	čiarkami oddelené kódy jazykov	Jazyky ponúkané návštevníkovi
knowledgeLanguageMode	string		Spôsob zaobchádzania so znalosťami v iných jazykoch
knowledgeLanguageFallback	string	kód jazyka	Záložný jazyk použitý v prípade, že sa nenájde žiadna zhoda

§ advanced

Pole	Typ	Obmedzenie	Popis
model	string	podlieha limitom účtu; pozrite „Textové modely AI“ vyššie	Identifikátor LLM (napr. 5-MINI)
temperature	decimal	0.0-1.0	Teplota vzorkovania (zodpovedá posuvníku v používateľskom rozhraní)
chatContextSize	int	∈ {8000, 16000, 32000}; automaticky prispôsobené limitu vášho účtu	Tokenové okno pre históriu chatu
botMessagesLimit	long	0 alebo násobok 1000 (napr. 1000, 2000, 10000)	Maximálny počet odpovedí bota na konverzáciu (0 = bez limitu)
internalLocale	string	kód lokalizácie vo formáte ll_CC	Jazyk ovládacích prvkov widgetu (odlišný od role.language)
productsViewEnabled	boolean		Ak má hodnotu true, sprístupní karty ponúk (Offer Cards) pre e-commerce v chate
includeProductsInKnowledgeBase	boolean		Ak má hodnotu true, zaindexuje katalóg produktov ako súčasť bázy znalostí

Mimo rozsahu API

Administrátorské rozhranie zahŕňa niekoľko oblastí, ktoré zámerne nie sú v tejto verzii rozhrania Management API sprístupnené:

• Záložka Flow (Tok) - vizuálny editor toku konverzácie Flow Editor (fázy a prechody). Nie je sprístupnené cez Management API.
• Záložka Actions (Akcie) - spravované e-commerce / rezervačné integrácie, funkcia AI Search a vlastné funkcie API. Volanie nástrojov nikdy nebolo súčasťou rozhrania Management API.
• Samotný nástroj na tvorbu vlastných formulárov - vytváranie a úprava vlastných formulárov nie sú sprístupnené. K botovi však môžete existujúci formulár pripojiť cez leadCollection.customFormId a humanSupport.customFormId.
• Vlastné ikony na otvorenie / zatvorenie chatu - customLauncherIconVisible, openChatIcon, closeChatIcon. Rozhranie API sprístupňuje iba hlavné multipart časti avatar a whitelabel_logo.
• Zoznamy IP adries a krajín - samotné záznamy sú určené iba pre administrátorov. Sprístupnený je len režim ich interpretácie prostredníctvom security.countryFilterMode.

Endpoints

POST /v1/management/bots

Vytvorte nového bota. Akceptované sú dva ekvivalentné typy Content-Type; vyberte si ten, ktorý vám viac vyhovuje.

Režim A - čistý JSON (odporúča sa, ak v tej istej požiadavke nepotrebujete nahrať avatar / logo):

• Content-Type: application/json
• Telo požiadavky je priamo konfiguračný JSON bota (bez obalu data)
• Súbory (avatar / logo) možno nahrať neskôr pomocou druhej požiadavky PATCH s využitím režimu B

Režim B - multipart/form-data (použite pri nahrávaní súborov v rámci tej istej požiadavky):

• Content-Type: multipart/form-data; boundary=...
• JSON časť data (povinné, Content-Type: application/json) - konfigurácia bota vo vnorenej štruktúre opísanej vyššie
• Súborová časť avatar (voliteľné) - obrázok avatara bota
• Súborová časť whitelabel_logo (voliteľné) - logo pre White Label (platí len v prípade, že váš účet zahŕňa funkciu White Label)

V JSON je povinný iba parameter name; pre každé ďalšie pole sa použije rovnaká predvolená hodnota, akú by nastavil sprievodca v administračnom rozhraní.

Úplné telo požiadavky

Toto je maximálny JSON pre data - každá sekcia je vyplnená. Odošlite iba tie sekcie, ktoré potrebujete; všetko ostatné prevezme predvolené 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é pravidlá s vlastnými chybovými správami:

• name - povinné, maximálne 150 znakov
• advanced.temperature - v rozsahu od 0.0 do 1.0
• chatMemory.summariesToKnowledgeRatio - celé číslo od 10 do 90 (percentá, krok 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - v rozsahu od 0 do 500
• appearance.footerMarkdown - maximálne 255 znakov
• humanSupport.enabled=true vyžaduje vyplnenie humanSupport.email
• leadCollection.enabled=true vyžaduje, aby aspoň jedna z hodnôt leadCollection.emailEnabled alebo leadCollection.phoneEnabled bola nastavená na true; zapnutý kanál zároveň vyžaduje svoj štítok, ako aj polia leaveDetailsMessage a thankYouMessage
• Polia s limitmi (advanced.chatContextSize, advanced.botMessagesLimit atď.) sa automaticky a bez upozornenia obmedzia podľa limitov vášho účtu

Polia, ktorých hodnota je na serveri null, sa v tele JSON vynechávajú - prenosová sieť prenáša iba polia s nenulovými hodnotami.

Úplné telo odpovede (201)

Rovnaká štruktúra ako požiadavka, navyše s blokom meta (iba na čítanie) a jednorazovým kľúčom apiKey na najvyššej úrovni. URL adresy súborov určené iba na čítanie (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) server doplní vtedy, keď boli nahrané príslušné časti multipart.

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

Pole apiKey sa zobrazuje iba pri vytvorení - ide o novo vygenerovaný kľúč Bot Talk API naviazaný na nového bota. Jeho otvorená textová podoba sa zobrazí iba raz a neskôr ju už cez API nemožno získať; okamžite si ju na svojej strane uložte.

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

Príklady pre Curl

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

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 avatarom:

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áti aktuálnu konfiguráciu bota, ktorého vlastníte.

Príklad pre Curl

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

Úplné telo odpovede (200)

Rovnaká štruktúra ako pri odpovedi na požiadavku POST, bez jednorazového poľa apiKey. Blok meta je súčasťou odpovede. Vracia 404 not_found_error, ak bot neexistuje alebo nepatrí k vášmu účtu.

Aktuálny avatar a logo pre White Label sa poskytujú ako plne kvalifikované URL adresy iba na čítanie (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - odvodené od rovnakej schémy, hostiteľa a kontextovej cesty, ktoré obslúžili túto požiadavku. Samotné bajty získate priamym volaním GET na tieto URL adresy; na nahradenie ktoréhokoľvek súboru nahrajte nový súbor cez multipart časť avatar / whitelabel_logo pri požiadavke PATCH. Ak tieto polia URL odošlete v tele požiadavky, budú ignorované.

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

Klonovanie bota

Telo požiadavky POST /v1/management/bots a telo odpovede GET /v1/management/bots/{bot_id} majú rovnakú štruktúru, takže klonovanie je trojkrokový proces: vykonajte GET zdrojového bota, odstráňte identifikačné polia spravované serverom a výsledok odošlite cez POST.

1. Vykonajte GET zdrojového bota.

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

2. Odstráňte blok meta na najvyššej úrovni. Objekt meta (id, createdAt, updatedAt) spravuje server a je určený len na čítanie - jeho ponechanie v tele požiadavky POST ničomu neublíži (server ho ignoruje), ale jeho odstránenie jasne vyjadruje zámer a udržiava payload čistý. Voliteľne upravte name, aby sa klon dal odlíšiť od zdroja.

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

3. Odošlite očistené telo cez POST na vytvorenie klonu. Kompletnú štruktúru tela a pravidlá validácie nájdete vyššie v referenčnej príručke 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

Odpoveď obsahuje meta.id nového bota a novo vygenerovaný apiKey (kľúč Bot Talk pre daný klon). Reťazec apiKey sa v čitateľnej podobe vracia iba v tejto odpovedi na vytvorenie - skopírujte si ho pred zahodením tela odpovede; neskôr ho už nie je možné získať.

Dve upozornenia:

• Súbory sa neklonujú. Polia appearance.avatarUrl a whiteLabel.whitelabelLogoUrl sú určené len na čítanie a odkazujú na súbory zdrojového bota. Ak na klone potrebujete rovnakého avatara alebo logo White Label, stiahnite si dáta zo zdrojových adries URL a nahrajte ich ako multipart časti avatar / whitelabel_logo - buď pri vytváraní cez POST (režim B), alebo v následnom volaní PATCH.
• Kľúče Bot Talk sa neklonujú. Každý bot má vlastnú zásobu kľúčov Bot Talk. Jediný kľúč apiKey vrátený požiadavkou POST na vytvorenie je ten, ktorý sa vygeneruje automaticky; ďalšie kľúče môžete v prípade potreby vytvoriť na karte API bota.

PATCH /v1/management/bots/{bot_id}

Aktualizuje jedno alebo viac polí bota, ktorého vlastníte. Menia sa iba sekcie a polia prítomné v JSONe; všetko vynechané (alebo odoslané ako null) zostáva nezmenené. Logika čiastočnej aktualizácie sa uplatňuje na jednotlivé polia v rámci odoslanej sekcie.

Akceptujú sa dva ekvivalentné typy Content-Type (rovnako ako pri POST):

Režim A - čistý JSON (odporúča sa, ak aktualizujete iba nastavenia):

• Content-Type: application/json
• Telo požiadavky je priamo JSON s aktualizáciami (bez obalu data)

Režim B - multipart/form-data (použite pri nahrávaní súborov):

• JSON časť data (voliteľná) - zmeny nastavení. Odošlite, iba ak chcete zmeniť polia. Vynechajte úplne, ak chcete nahrať iba avatara alebo logo.
• Súborová časť avatar (voliteľná) - nahradenie avatara
• Súborová časť whitelabel_logo (voliteľná) - nahradenie loga White Label (platí iba v prípade, že váš účet zahŕňa whitelabeling)

Všetky tri časti sú pri PATCH voliteľné, ale aspoň jedna musí byť prítomná, aby volanie malo zmysel.

Úplné telo požiadavky (maximálny rozsah)

Akékoľvek pole akceptované požiadavkou POST /v1/management/bots možno odoslať aj tu. Nižšie uvedený príklad predstavuje kompletný rozsah; v praxi odosielate iba kľúče, ktoré chcete zmeniť (pozrite si časť "Minimálna čiastočná aktualizácia" nižšie) - každý vynechaný kľúč (alebo odoslaný ako null) ponechá uloženú hodnotu nezmenenú.

{
  "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álna čiastočná aktualizácia

Aktualizujte jedno pole cez PATCH odoslaním presne tých kľúčov, ktoré chcete zmeniť - všetko ostatné zostane zachované.

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

Príklady curl

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

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 (pri nahradení 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 - nahradenie iba avatara (bez zmien polí):

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

Telo odpovede (200)

Rovnaká štruktúra ako GET /v1/management/bots/{bot_id} - úplná konfigurácia bota po aplikovaní zmien vrátane bloku meta. Bez poľa apiKey. Vracia 404 not_found_error, ak bot neexistuje alebo nepatrí k vášmu účtu.

Nižšie uvedený príklad zobrazuje odpoveď po aplikovaní vyššie uvedenej aktualizácie Úplné telo požiadavky (maximálny rozsah) na bota z príkladu GET - zmenené polia odrážajú nové hodnoty, nedotknuté polia zostávajú zachované a časová značka meta.updatedAt sa 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

Načíta aktuálne využitie predplatného pre účet, ktorý vlastní kľúč Management.

Telo odpovede (200)

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

• subscriptionType je identifikátor aktuálneho balíka účtu písaný malými písmenami (napr. standard v príklade). Balíky pochádzajú z dynamického katalógu, takže presná množina identifikátorov sa môže v čase meniť podľa toho, ako sa balíky premenovávajú alebo pridávajú - berte to ako ľubovoľný reťazec, nie ako fixný enum.
• messages.used / limit / remaining predstavujú kredity na správy v aktuálnom zúčtovacom období.
• bots.used / limit / remaining vyjadrujú počet aktívnych botov v porovnaní s limitom botov vášho účtu.

Hlavičky obmedzenia frekvencie (rate limit)

Odpovede, ktoré dosiahnu fázu kontroly obmedzenia frekvencie (t. j. prešli autentifikáciou a povolenými IP adresami), obsahujú:

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

• X-RateLimit-Limit - limit na kľúč skutočne uplatnený na toto volanie (predvolene 10, alebo vami nakonfigurovaný rateLimitPerMinute, ak je nižší).
• X-RateLimit-Remaining - tokeny zostávajúce v zásobníku (bucket) bezprostredne po tomto volaní.
• X-RateLimit-Reset - čas v sekundách podľa Unix epochy, kedy bude k dispozícii ďalší token (nejde o úplné obnovenie zásobníka; tokeny do zásobníka pribúdajú priebežne). Keď je zásobník plný, je to aktuálny čas.

Pri odpovediach 429 rate_limit_exceeded je nastavená aj hlavička Retry-After, vyjadrená v celých sekundách, kým sa neuvoľní aspoň jeden token.

Chyby pred overením (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) a 403 ip_not_whitelisted neobsahujú hlavičky X-RateLimit-* - obmedzovač sa uplatňuje až po úspešnej autentifikácii a kontrole IP adries.

Formát chýb

Rovnaká obálka ako pri 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 pred správu vkladajú cestu k chybnému poľu, takže problematickú časť ľahko nájdete:

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

Neplatné hodnoty pre polia typu enum / s uzavretou množinou hodnôt (napr. chatMemory.clientSummaryPromptType = "BOGUS") obsahujú cestu k poľu, odmietnutú hodnotu a zoznam povolených hodnôt:

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

Súvisiace

Pre koncové body konverzácie a streamovanie cez SSE si pozrite Bot Talk API.