Management API

Prehľad Management API

Management API slúži na back-office operácie, 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}
• načítanie využitia predplatného pomocou GET /v1/usage

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

Základná URL adresa

https://api.chatlab.com/aichat

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

Začíname

1. Otvorte administrátorskú aplikáciu a prejdite na Account Settings > Management API (Nastavenia účtu > Management API).
2. Kliknite na Create Management Key (Vytvoriť kľúč Management API), pomenujte ho, voliteľne nastavte povolené IP adresy (whitelist) a limit požiadaviek (rate limit) a potom formulár odošlite.
3. Vyberte iba tie oprávnenia, ktoré vaša integrácia potrebuje, a skopírujte celý kľúč z modálneho okna s potvrdením úspechu. Nezašifrovaný text sa zobrazí iba raz.
4. Uložte ho na svojom serveri, nie v kóde prehliadača ani vo verejnom repozitári. Na overenie prístupu odošlite požiadavku iba na čítanie, napríklad GET /v1/usage s oprávnením usage.
5. Nepoužívané alebo kompromitované kľúče zrušte na stránke Management API.

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

Autentifikácia

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Odoslanie kľúča mk_ na /v1/chat (alebo na 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 kľúč (token bucket, kapacita 10, plynulé dopĺňanie približne 1 token každých 6 sekúnd). Pri vytvorení je možné nastaviť nižšiu hodnotu - nastavte nižší rateLimitPerMinute, limit klesne a rýchlosť dopĺňania sa podľa toho upraví.

Oprávnenia

Každý kľúč Management nesie ľubovoľnú podmnožinu troch nižšie uvedených oprávnení. Pri vytvorení musí byť vybraté aspoň jedno; 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 403 insufficient_permissions.

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

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

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

• role - osobnosť bota, nespracovaný prompt, dĺžka odpovede, jazyk, kontext webu / spoločnosti (záložka Role & Behavior)
• conversation - uvítacia správa, spresnenie otázky, kontinuita konverzácie, prepínač hodnotenia + popisy, 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 štýle markdown (záložka Appearance)
• humanSupport - kontaktný formulár pre spojenie s človekom (záložka Human Contact Form)
• leadCollection - formulár na zber 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 vlastného loga, hosting na vlastnej doméne (záložka Whitelabel)
• security - povolené domény, spam filter, limity počtu správ (záložka Security)
• voice - hlasový vstup a hlasové konverzácie: model, hlas, jazyky, prompt, limit trvania (záložka Voice Conversation)
• multilingual - viacjazyčný režim, základný jazyk, ponúkané jazyky, spracovanie jazyka znalostnej bázy (záložka Languages)
• advanced - model LLM, teplota, veľkosť kontextu, limit správ bota, interná lokalizácia, Offer Cards (záložka Model & Advanced)

Zo zapisovateľných nastavení sa na najvyššej úrovni nachádza iba name, pretože identifikuje bota a nepatrí pod žiadnu konkrétnu záložku.

Bočný panel Bot Settings má v súčasnosti 16 podzáložiek a 13 z nich sa mapuje na vyššie uvedené sekcie. Tri podzáložky bez zodpovedajúcej sekcie sú Flow, Actions a Forms - všetky tri sú popísané nižšie v časti "Mimo rozsahu API". Tých 13, ktoré sa mapujú, 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ď pridáva dva prvky navyše:

• meta - iba na čítanie: ID bota a časové pečiatky. Ich odstránením premeníte odpoveď GET na platné telo POST.
• apiKey - prítomný iba pri vytvorení - čerstvo vygenerovaný kľúč Bot Talk API pre nového bota.

Dve polia v rámci zdieľanej štruktúry sú iba na čítanie - vracajú sa v odpovedi a ignorujú sa, ak sa ich pokúsite odoslať v POST/PATCH:

• appearance.avatarUrl - úplná verejná URL adresa obrázka avatara bota (napr. https://api.chatlab.com/aichat/content/avatar_xyz.png). Na stiahnutie bajtov na ňu pošlite priamo požiadavku GET. Ak ju chcete zmeniť, nahrajte nový súbor cez multipart časť avatar (pozrite časť PATCH).
• whiteLabel.whitelabelLogoUrl - úplná verejná URL adresa loga v hlavičke pre white-label. Rovnaký princíp ako pri avatarUrl. Ak ju chcete zmeniť, nahrajte nový súbor cez multipart časť whitelabel_logo (pozrite časť PATCH).

Obe URL adresy používajú schému + hostiteľa + kontextovú cestu aktuálnej požiadavky, takže pri vlastnej white-label doméne sa vracajú s koreňom na tejto doméne (napr. https://api.acme.com/aichat/content/...).

Odoslaním hodnoty null pre celú sekciu ju v PATCH preskočíte; odoslaním hodnoty null pre pole v rámci sekcie preskočíte toto konkrétne pole. Hodnota null na úrovni poľa nikdy nevymaže uloženú hodnotu - znamená iba "nemenit".

Rola a zostavenie promptu

Systémový prompt, ktorý LLM v skutočnosti dostane, sa vytvára jedným z dvoch spôsobov v závislosti od role.role. Vedomosť o tom, v ktorej vetve sa nachádzate, vám povie, na ktorých poliach záleží a ktoré sú síce uložené, ale ignorujú sa.

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

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

• role.role - označenie roly (napr. "Customer Support") a automaticky pripojené inštrukcie špecifické pre danú rolu
• name - názov bota, vložený do úvodnej vety
• role.language - hodnota "Auto Detect" prepne bota tak, aby sledoval jazyk 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, vloží sa ako dodatočný odsek pred inštrukcie roly

Toto je odporúčaná vetva pre väčšinu botov - získate správanie vyladené pre danú rolu a bezpečnostné mantinely zadarmo.

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

Backend použije role.rawPrompt ako prompt roly a pripojí fixné usmernenie platformy týkajúce sa dĺžky odpovede. To je oddelené od role.responseLength: voliteľné nastavenie Concise/Normal/Detailed sa pre rolu CUSTOM nevkladá. Podobne platí, že language, websiteAddress a companyDescription sa síce uložia, ale do tohto promptu roly sa nevložia. Akýkoľvek požadovaný jazyk, cieľovú dĺžku odpovede alebo kontext spoločnosti uveďte priamo v parametri rawPrompt. Môžu sa dodať aj ďalšie inštrukcie počas behu a načítaný kontext, takže rawPrompt nepredstavuje celý vstup modelu. Inštrukcie k tónu z preddefinovanej roly sa nepridávajú, no voľba CUSTOM neodstraňuje všetky inštrukcie platformy.

Možnosť CUSTOM použite iba vtedy, keď prompt riadený šablónou nevyhovuje vášmu prípadu použitia (napr. potrebujete osobnosť veľmi špecifickú pre dané odvetvie, vlastné bezpečnostné obmedzenia, neštandardný formát výstupu).

Polia s výpočtovými typmi (Enum) / uzavretou množinou hodnôt

Polia typu enum a polia s obmedzenými hodnotami odmietajú neplatné hodnoty chybou 400 invalid_parameter. Ostatné polia sú bežné reťazce, a to aj tam, kde používateľské rozhranie ponúka fixný zoznam. Používajte zdokumentovaný zápis a overujte svoje dáta namiesto predpokladu, že každý nepodporovaný reťazec bude odmietnutý.

• 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 sa do šablóny promptu, takže dvojpísmenové kódy ISO (en, pl) a iné hodnoty mimo zoznamu API neodmietne, ale vytvoria skomolenú inštrukciu typu "Output in en, unless...". Ak sa vynechá pri vytvorení, predvolená hodnota je Auto Detect.
• advanced.model - pozrite časť "Textové AI modely" nižšie. Ide o reťazec, nie o validovaný enum v schéme požiadavky; použite podporovanú hodnotu, nie ľubovoľný názov modelu.
• advanced.chatContextSize - použite 8000, 16000 alebo 32000 podľa používateľského rozhrania. Hodnoty presahujúce maximum účtu sa ticho obmedzia; DTO túto trojicu hodnôt nevynucuje.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - boolovský prepínač. Hodnota true núti používateľa vyplniť formulár pre leady pred začatím konverzácie; hodnota false necháva na AI, kedy formulár zobrazí (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 špecifiká administrátorského rozhrania, o ktorých sa oplatí vedieť.

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

• chatMemory.summariesToKnowledgeRatio - celé číslo v percentách, 10-90; rozhranie používa kroky po 10, no API prijíma celé čísla v celom rozsahu. Predvolená hodnota je 50. Pri povolenej pamäti a kontexte väčšom ako 8k rozdeľuje rozpočet na znalosti a pamäť po vyhradení miesta na prompt/nedávnu konverzáciu, nie celý kontext modelu. Pri 8k sa týmto nastavením neprideľuje žiadny rozpočet na zhrnutia.

• liveChat.schedule - JSON kódovaný ako reťazec, nie vnorený objekt JSON v prenose. Server ukladá nespracovaný reťazec doslovne; administrátorské rozhranie ho analyzuje 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 plus kľúč 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 je názov pásma podľa IANA (napr. "Europe/Warsaw", "America/New_York")

  Príklad hodnoty (všimnite si vonkajšie úvodzovky a uniknuté vnútorné úvodzovky - ide o jedno reťazcové pole, nie 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 liveChat.outOfHoursMessage a odovzdanie na živý chat sa potlačí. Validácia vnútornej štruktúry prebieha iba na strane klienta v administrátorskom rozhraní - neplatný JSON alebo nerozpoznané kľúče API prijme ako obyčajný reťazec a prejavia sa chybou vykresľovania, keď neskôr administrátor otvorí bota v rozhraní. Pred odoslaním overte štruktúru na svojej strane.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - krátke texty zobrazené na ovládacích prvkoch hodnotenia konverzácie 👍 / 👎, keď platí 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 v závislosti od limitov vášho účtu. Skryje text v pätičke "Powered by ChatLab". Ak váš účet nezahŕňa white-label, hodnota sa uloží, ale ignoruje, a pätička sa vždy vykreslí.

• whiteLabel.whitelabelLogoLink - funkcia white-label v závislosti od limitov vášho účtu. Cieľová URL adresa po kliknutí na vlastné logo, ak platí hideRoboAssistLogo=true a súbor vlastného loga je nahraný cez multipart časť whitelabel_logo.

• appearance.simulateHumanTypingDelay - sekundy (nie milisekundy), celé číslo 0-200. Prestávka medzi jednotlivými bublinami bota, keď platí simulateHumanTyping=true. Predvolená hodnota je 5.

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

• advanced.internalLocale - kód regiónu a jazyka podľa IETF v tvare ll_CC (podčiarkovník, NIE ll-CC so spojovníkom). Prijímané hodnoty pochádzajú z fixné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é odoslanie dvojpísmenového kódu ("en") alebo BCP-47 ("en-US") sa v povolenom zozname nenachádza. Predvolená hodnota je en_US. Toto je lokalizácia používaná na formátovanie dátumu a čísel v rozhraní widgetu, odlišná 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"). Nastavením limitu správ na 0 tento limit viazaný na reláciu zakážete. Pri jeho povolení zadajte kladné trvanie. Backend vynucuje N správ na reláciu za trvanie v sekundách, kým návštevníkovi zobrazí správu security.talkMessagesRateLimitHitMessage.

• advanced.botMessagesLimit - celé číslo (číslo v JSON, napr. 1000). Hodnota 0 znamená žiadny dodatočný limit na bota, pričom kreditový rozpočet účtu stále platí; inak musí ísť o násobok 1000 (1000, 2000, 10000, ...). Hodnoty ako 100 alebo 1500 sú odmietnuté s chybou 400 invalid_parameter. Ide o mesačný limit kreditov bota, nie o počet správ na konverzáciu. Mapovač túto hodnotu neobmedzuje na rozpočet účtu; skutočné využitie stále obmedzuje rozpočet účtu.

Textové AI modely (advanced.model)

Použite presný identifikátor modelu vrátený v advanced.model pri načítaní bota nakonfigurovaného s požadovaným modelom v Settings > Model & Advanced (Nastavenia > Model a pokročilé). Aktuálna predvolená hodnota pri vytvorení je 5.6-LUNA. Identifikátory rozlišujú veľké a malé písmená a líšia sa od zobrazovaných názvov; napríklad 5.6-LUNA sa zobrazuje ako GPT 5.6-luna.

Katalóg modelov sa časom mení. Z faktu, že schéma požiadavky prijíma reťazec, nevyvodzujte, že je podporovaný ľubovoľný reťazec alebo verejné ID modelu od poskytovateľa. Pred nasadením chatbota si znova načítajte uloženú konfiguráciu a otestujte ho.

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

Podporované sekcie a polia spolu s ich typmi a dôležitými obmedzeniami. Sémantika PATCH: vynechanie ľubovoľného poľa (alebo jeho odoslanie ako null) ponechá uloženú hodnotu nezmenenú. Rovnaká štruktúra sa používa aj pre odpoveď (okrem multipart binárneho obsahu; navyše je v každej odpovedi blok meta určený len na čítanie a kľúč apiKey iba v 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 prítomné iba v odpovedi:

• meta: { id, createdAt, updatedAt } - iba na čítanie.
• apiKey - reťazec, prítomný iba v odpovedi na POST /v1/management/bots - nanovo vygenerovaný kľúč Bot Talk 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 „Role and prompt construction“)
language	string	celý anglický názov jazyka (English, Polish, ...) alebo Auto Detect	Primárny jazyk vstupujúci do šablóny promptu
responseLength	string	∈ {Concise, Normal, Detailed}	Požadovaná podrobnosť odpovede umelej inteligencie
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 pri role=CUSTOM

§ conversation

Pole	Typ	Obmedzenie	Popis
welcomeMessage	string		Prvá správa zobrazená návštevníkovi po otvorení
queryRefinementEnabled	boolean		Ak je hodnota true, otázka návštevníka sa pred vyhľadaním v RAG spresní
conversationContinuityEnabled	boolean		Ak je hodnota true, vracajúci sa návštevníci pokračujú v poslednej konverzácii
conversationRatingEnabled	boolean		Ak je hodnota true, zobrazia sa ovládacie prvky na hodnotenie konverzácie palcom hore/dole
positiveRatingTooltip	string		Popis tlačidla kladného hodnotenia
negativeRatingTooltip	string		Popis tlačidla záporného hodnotenia
suggestedQuestions	string		Navrhované otázky / podnety na začatie konverzácie oddelené novým riadkom
dynamicSuggestedFollowups	boolean		Ak je hodnota true, umelá inteligencia po každej odpovedi navrhne ďalšie otázky
positiveRatingMessage	string		Správa zobrazená po kladnom hodnotení
negativeRatingMessage	string		Správa zobrazená po zápornom hodnotení
hideSuggestedQuestionsAfterFirstUse	boolean		Skryť statické návrhy po použití
dynamicFollowupsAutoIcons	boolean		Ak je hodnota true, umelá inteligencia automaticky vyberie emoji ikony pre dynamické doplňujúce otázky

§ chatMemory

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Hlavný prepínač funkcie 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 zhrnutie profilu klienta naprieč konverzáciami
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Predvolený vs. vlastný prompt profilu klienta
summariesToKnowledgeRatio	int	10-90 (krok v rozhraní 10)	% z dostupného rozpočtu na znalosti/pamäť vyhradené na zhrnutia pri kontextoch nad 8k

§ appearance

Pole	Typ	Obmedzenie	Popis
launcherLabelLine1	string	max 60	Prvý riadok textu spúšťača
launcherLabelLine2	string	max 60	Druhý riadok textu spúšťača
launcherTextColor	string		Farba textu spúšťača
launcherDismissEnabled	boolean		Povoliť zatvorenie spúšťača
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Rodina písma widgetu
chatDrawerEnabled	boolean		Povoliť zobrazenie vo forme bočného panelu (drawer)
launcherColor	string (hex)		Farba pozadia spúšťača (ikony chatu)
headerColor	string (hex)		Farba pozadia hlavičky chatu
titleColor	string (hex)		Farba nadpisu hlavičky chatu
subtitleColor	string (hex)		Farba podnadpisu hlavičky 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		Podnadpis zobrazený pod názvom chatu
senderPlaceholder	string		Zástupný text vo vstupnom poli správy
resetConversationTooltip	string		Popis tlačidla „resetovať konverzáciu“
chatAlignment	string (enum)	∈ {left, right}	Na ktorú stranu obrazovky sa chat ukotví
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		Čisté CSS vložené do iframe widgetu
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Spôsob otvárania odkazov v správach bota
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Minimalizovaný stav: ikona spúšťača, kompaktný panel na odosielanie alebo pilulka
chatDesktopWidthPx	int		Šírka widgetu na desktope
chatDesktopHeightPx	int		Výška widgetu na desktope
chatMobileSizePercent	int		Veľkosť mobilného widgetu ako % z výrezu obrazovky
messageFontSize	int		Veľkosť písma textu správy (px)
showChatbotBubblesDesktop	boolean		Zobrazovať plávajúce pútacie bubliny na desktope
showChatbotBubblesMobile	boolean		Zobrazovať plávajúce pútacie bubliny na mobile
chatbotBubblesDelaySeconds	int		Oneskorenie pred zobrazením pútacích bublín (sekundy)
launcherIconFullSize	boolean		Vykresliť vlastnú ikonu spúšťača od okraja po okraj namiesto odsadenia
welcomeScreenEnabled	boolean		Zobraziť uvítaciu obrazovku namiesto priameho prechodu do chatu
welcomeScreenQuestionsLabel	string		Štítok nad navrhovanými otázkami na uvítacej obrazovke
welcomeScreenHideHumanContactForm	boolean		Skryť akciu kontaktného formulára na živú podporu v hlavičke, kým sa zobrazuje uvítacia obrazovka. Znovu sa objaví po prvej správe návštevníka. Boti vytvorení pred 2026-09-02 majú predvolene nastavené true
welcomeScreenHideLiveChat	boolean		Skryť akciu Live Chat v hlavičke, kým sa zobrazuje uvítacia obrazovka. Znovu sa objaví po prvej správe návštevníka. Boti vytvorení pred 2026-09-02 majú predvolene nastavené true
headerActionsLayout	string	ICONS or DROPDOWN	Spôsob ponuky funkcie Live Chat a formulára na živú podporu v hlavičke chatu: ICONS (samostatná ikona pre každú) alebo DROPDOWN (zoskupené v ponuke hlavičky). Boti vytvorení pred 2026-09-02 majú predvolene nastavené ICONS
stackSuggestedQuestions	boolean		Zoradiť navrhované otázky vertikálne (namiesto vedľa seba)
suggestedQuestionsFontSize	int		Veľkosť písma prvkov navrhovaných otázok (px)
suggestedQuestionsTextColor	string (hex)		Farba textu prvkov navrhovaných otázok
suggestedQuestionsBackgroundColor	string (hex)		Farba pozadia prvkov navrhovaných otázok
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 správami v bublinách (sekundy)
footerMarkdown	string	max 255	Vlastný markdown pätičky zobrazený pod chatom
avatarUrl	string	read-only	Úplná verejná URL adresa avatara; ak ju chcete zmeniť, nahrajte súbor cez časť avatar v rámci multipart

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

§ humanSupport

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač postupu pre Human Support
email	string	povinné (create-strict), keď enabled=true	Adresa, na ktorú prichádzajú e-maily pre živú podporu
dialogMessage	string		Motivačná správa zobrazená nad formulárom
thankYouMessage	string		Potvrdenie zobrazené po odoslaní
emailMessageSubjectTemplate	string		Šablóna predmetu e-mailu odosielaného agentovi
emailMessageContentTemplate	string		Šablóna tela e-mailu odosielaného agentovi
emailPlaceholder	string		Zástupný text vo vstupnom poli pre e-mail
messagePlaceholder	string		Zástupný text v textovom poli správy
emailWithConversationContent	boolean		Ak je hodnota true, do tela e-mailu sa zahrnie prepis konverzácie
customFormId	long	id existujúceho vlastného formulára	Nahradí vstavaný kontaktný formulár vlastným formulárom. Pri vytvorení sa pri vynechaní použije vstavaný formulár; pri PATCH hodnota null ponechá aktuálny výber nezmenený
customFormMapping	string	reťazec vo formáte JSON	Mapuje polia vlastného formulára na polia e-mailu živej podpory

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

§ leadCollection

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač formulára na zber leadov
nameEnabled	boolean		Zbierať meno
nameLabel	string		Štítok vstupného poľa pre meno
emailEnabled	boolean		Zbierať e-mail
emailLabel	string	povinné (create-strict), keď enabled=true A ZÁROVEŇ emailEnabled=true	Štítok vstupného poľa pre e-mail
phoneEnabled	boolean		Zbierať telefónne číslo
phoneLabel	string	povinné (create-strict), keď enabled=true A ZÁROVEŇ phoneEnabled=true	Štítok vstupného poľa pre telefón
leaveDetailsMessage	string	povinné (create-strict), keď enabled=true	Správa vyzývajúca návštevníka na zanechanie kontaktných údajov
thankYouMessage	string	povinné (create-strict), keď enabled=true	Potvrdenie zobrazené po odoslaní
requireBeforeNewConversation	boolean		Ak je hodnota true, formulár sa musí odoslať pred začatím chatu; ak je false, umelá inteligencia rozhodne, kedy formulár zobraziť
emailNotificationEnabled	boolean		Odoslať e-mail majiteľovi pri každom získaní leadu
emailNotificationAddress	string		Príjemca oznámení (predvolene e-mail účtu)
emailWithConversationContent	boolean		Ak je hodnota true, do oznámenia sa zahrnie prepis konverzácie

| customFormId | long | id existujúceho vlastného formulára | Nahradí vstavaný formulár na leady vlastným formulárom. Pri vytvorení sa pri vynechaní použije vstavaný formulár; pri PATCH hodnota null ponechá aktuálny výber nezmenený | | customFormMapping | string | reťazec vo formáte JSON | Mapuje polia vlastného formulára na meno / e-mail / telefón |

Krížové pravidlo create-strict: enabled=true vyžaduje povolenie aspoň jedného z polí emailEnabled alebo phoneEnabled. Pole requirePolicyAccept sa nachádza v consent.leadCollectionRequirePolicyAccept, nie tu.

§ liveChat

Pole	Typ	Obmedzenie	Popis
enabled	boolean		Prepínač funkcie Live Chat
infoMessage	string		Vysvetľujúca správa pred odovzdaním konverzácie
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 vstupného poľa pre meno v úvodnom formulári funkcie Live Chat
emailLabel	string		Štítok vstupného poľa pre e-mail v úvodnom formulári funkcie Live Chat
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 „Structured fields and ranges“
outOfHoursMessage	string		Správa zobrazená mimo prevádzkových hodín podľa harmonogramu
closeModalMessage	string		Nadpis modálneho okna „ukončiť živý chat?“
closeModalConfirmLabel	string		Štítok potvrdzovacieho tlačidla v modálnom okne zatvorenia
closeModalCancelLabel	string		Štítok tlačidla zrušenia v modálnom okne zatvorenia
closeModalTooltipText	string		Popis prvku na ukončenie chatu
operatorHasJoinedLabel	string		Štítok zobrazený po pripojení operátora
operatorDidNotJoinInTimeLabel	string		Štítok zobrazený, ak sa operátor nepripojí v stanovenom limite
waitingForOperatorToJoinLabel	string		Štítok zobrazený počas čakania na operátora
waitingForOperatorSeconds	int		Časový limit na prevzatie konverzácie operátorom (sekundy)
redirectToHumanSupportForm	boolean		Ak je hodnota true, pri neprevzatí operátorom sa prejde na formulár Human Support
requireAdminOnline	boolean		Vyžadovať dostupného operátora podľa nastavení prítomnosti
presenceMode	string		Režim prítomnosti; použite hodnotu z bota nakonfigurovaného v používateľskom rozhraní
hideHumanSupportWhenLiveChatAvailable	boolean		Skryť kontaktný formulár, keď je k dispozícii Live Chat
missedEmailEnabled	boolean	predvolene true	Odoslať e-mail majiteľovi bota, ak požiadavka na Live Chat zostala bez odpovede. Pri starších botoch nie je nastavené, čo sa vyhodnocuje ako povolené

Pole 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 živej podpory
leadCollectionRequirePolicyAccept	boolean		Vyžadovať súhlas so zásadami ochrany osobných údajov pred odoslaním formulára na zber leadov
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 začatí konverzácie
privacyPolicyConsentCheckboxLabel	string		Štítok vedľa začiarkavacieho poľa 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	viazané na funkciu CUSTOM_DOMAIN	Prevádzkovať chat na nakonfigurovanej vlastnej doméne
whitelabelLogoUrl	string	read-only	Úplná verejná URL adresa loga White Label; ak ju chcete zmeniť, nahrajte súbor cez časť whitelabel_logo v rámci multipart

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

§ security

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

§ voice

Pole	Typ	Obmedzenie	Popis
inputEnabled	boolean		Umožniť návštevníkovi diktovať správy (prevod reči na text)
conversationEnabled	boolean	vyžaduje hlasovú funkciu v predplatenom balíku	Povoliť plnohodnotné hlasové konverzácie
voiceId	string	ID hlasu špecifické pre poskytovateľa (napr. alloy)	Ktorý syntetický hlas hovorí
model	string	napr. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Hlasový model. Účtuje sa 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é vstupy
welcomeMessage	string		Hovorená úvodná fráza
language	string	kód jazyka	Primárny jazyk hlasu
additionalLanguages	string	kódy jazykov oddelené čiarkou	Ďalšie jazyky, ktoré hlasový agent prijíma
maxDurationSeconds	int		Pevný limit na jednu hlasovú konverzáciu
maxDurationMessage	string		Správa zobrazená po dosiahnutí limitu

§ multilingual

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

§ advanced

Pole	Typ	Obmedzenie	Popis
model	string	podlieha limitom účtu; pozrite časť „AI text models“ vyššie	Identifikátor LLM (napr. 5.6-LUNA)
temperature	decimal	0.0-1.0	Vzorkovacia teplota (zodpovedá posuvníku v rozhraní)
chatContextSize	int	∈ {8000, 16000, 32000}; automaticky ohraničené limitom vášho účtu	Nakonfigurovaný rozpočet kontextu vrátane inštrukcií, histórie a znalostí
botMessagesLimit	long	0 alebo násobok 1000 (napr. 1000, 2000, 10000)	Mesačný limit kreditov na správy bota (0 = bez dodatočného limitu na bota; rozpočet účtu stále platí)
internalLocale	string	kód jazykového prostredia v tvare ll_CC	Jazykové prostredie pre systémové texty widgetu (odlišné od role.language)
productsViewEnabled	boolean		Ak je hodnota true, v chate sa sprístupnia e-commerce Offer Cards
includeProductsInKnowledgeBase	boolean		Ak je hodnota true, katalóg produktov sa indexuje ako súčasť znalostnej bázy

Mimo rozsahu API

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

• Trénovanie a mazanie - tieto koncové body neumožňujú vypísať zoznam všetkých botov, spravovať trénovacie datasety ani mazať botov. Na tieto činnosti použite aplikáciu.
• Záložka Flow (Tok) - vizuálny Flow Editor konverzácií (fázy a prechody). Nie je sprístupnený cez Management API.
• Záložka Actions (Akcie) - spravované e-commerce / rezervačné integrácie, AI Search a vlastné funkcie API. Volanie nástrojov nikdy nebolo súčasťou Management API.
• Samotný nástroj na tvorbu vlastných formulárov - vytváranie a úprava vlastných formulárov nie sú sprístupnené. Môžete však k botovi pripojiť existujúci formulár prostredníctvom leadCollection.customFormId a humanSupport.customFormId.
• Vlastné ikony otvorenia / zatvorenia chatu - customLauncherIconVisible, openChatIcon, closeChatIcon. Rozhranie API sprístupňuje iba hlavné časti avatar a whitelabel_logo v rámci multipart.
• Zoznamy IP adries a krajín - samotné položky sú prístupné len správcom. Cez security.countryFilterMode je sprístupnený iba režim ich interpretácie.

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 rovnakej požiadavke nepotrebujete nahrať avatar / logo):

• Content-Type: application/json
• Telo požiadavky je priamo konfiguračný JSON bota (žiadny obalový objekt data)
• Súbory (avatar / logo) možno nahrať neskôr pomocou druhej požiadavky PATCH v režime B

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

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

V objekte JSON je povinné iba pole name; všetky ostatné polia preberajú rovnaké predvolené hodnoty, aké by nastavil sprievodca v administračnom UI.

Príklad tela požiadavky

Toto je maximálny JSON objektu data - so všetkými vyplnenými sekciami. Odosielajte iba tie sekcie, ktoré potrebujete; všetko ostatné použije 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Validačné pravidlá s vlastnými chybovými správami:

• name - povinné, max. 150 znakov
• advanced.temperature - medzi 0.0 a 1.0
• chatMemory.summariesToKnowledgeRatio - celé číslo medzi 10 a 90 (percentá, krok 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - medzi 0 a 500
• appearance.footerMarkdown - max. 255 znakov
• humanSupport.enabled=true vyžaduje nastavenie poľa humanSupport.email
• leadCollection.enabled=true vyžaduje, aby aspoň jedno z polí leadCollection.emailEnabled alebo leadCollection.phoneEnabled malo hodnotu true; aktívny kanál vyžaduje aj svoj štítok a polia leaveDetailsMessage a thankYouMessage
• advanced.chatContextSize sa automaticky obmedzí na maximálnu veľkosť kontextu podporovanú vaším účtom. Nepredpokladajte, že ostatné číselné polia sa obmedzujú automaticky.

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

Príklad tela odpovede (201)

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

{
  "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 sa zobrazuje iba pri vytvorení - ide o novo vygenerovaný kľúč Bot Talk viazaný na nového bota. Reťazec v čistom texte sa zobrazí iba raz a neskôr ho už cez API nie je možné získať; ihneď si ho uložte na svojej strane.

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

Príklady 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 curl

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

Príklad tela odpovede (200)

Rovnaká štruktúra ako odpoveď na POST, bez jednorazového kľúča apiKey. Blok meta je zahrnutý. Ak bot neexistuje alebo nepatrí k vášmu účtu, vráti chybu 404 not_found_error.

Aktuálny avatar a white-label logo sú sprístupnené ako plne kvalifikované URL adresy určené len na čítanie (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - s koreňom na rovnakej schéme, hostiteľovi a kontextovej ceste, ktoré obslúžili túto požiadavku. Samotné dáta získate priamou požiadavkou GET na tieto URL adresy; ak chcete niektorý zo súborov nahradiť, nahrajte nový cez multipart časť avatar / whitelabel_logo v požiadavke PATCH. Ak tieto polia URL odošlete v tele požiadavky, ignorujú sa.

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

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 pozostáva z troch krokov: stiahnutie zdroja pomocou GET, odstránenie identifikačných polí spravovaných serverom a odoslanie výsledku cez POST.

1. Získajte zdrojového bota pomocou GET.

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č nepokazí (server ho ignoruje), ale jeho odstránením jasne vyjadríte svoj zámer a udržíte payload čistý. Voliteľne upravte pole 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 upravené telo cez POST na vytvorenie klonu. Úplnú štruktúru tela a pravidlá validácie nájdete vyššie v referenčnej príručke pre 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). Nešifrovaný textový reťazec apiKey sa vráti 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ť.

Týmto postupom sa skopírujú podporované nastavenia, nie kompletne natrénovaný chatbot. Trénovací obsah, história konverzácií, integrácie/akcie, Flow a definície formulárov sa cez tieto koncové body neklonujú. Tieto položky nakonfigurujte osobitne v aplikácii.

Ďalšie 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ý avatar alebo logo pre White Label, stiahnite si dáta zo zdrojových URL adries a nahrajte ich ako multipart časti avatar / whitelabel_logo - buď pri volaní POST na vytvorenie (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ý volaním POST na vytvorenie je ten, ktorý sa vygeneruje automaticky; ďalšie kľúče si v prípade potreby vytvorte na karte API bota.

PATCH /v1/management/bots/{bot_id}

Aktualizujte jedno alebo viac polí bota, ktorého vlastníte. Upravia sa iba sekcie a polia prítomné v JSON; všetko vynechané (alebo odoslané ako null) zostane nedotknuté. Pravidlá čiastočnej aktualizácie platia pre každé pole v rámci odoslanej sekcie.

Podporované sú dva rovnocenné 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 úpravami (bez obalu data)

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

• JSON časť data (voliteľné) - úpravy. Odošlite iba vtedy, ak chcete zmeniť polia. Vynechajte úplne, ak chcete nahrať iba avatar alebo logo.
• súborová časť avatar (voliteľné) - nahradenie avatara
• súborová časť whitelabel_logo (voliteľné) - nahradenie loga pre White Label (platí len vtedy, ak váš účet zahŕňa whitelabeling)

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

Príklad tela požiadavky (viacero sekcií)

Odoslať je možné akékoľvek pole, ktoré akceptuje POST /v1/management/bots. Nižšie uvedený príklad znázorňuje niekoľko sekcií, nie každé podporované pole; v praxi odosielate iba kľúče, ktoré chcete zmeniť (pozri časť „Minimálna čiastočná aktualizácia" nižšie) - každý vynechaný kľúč (alebo kľúč 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 jednotlivé pole cez PATCH odoslaním presne tých kľúčov, ktoré chcete zmeniť - všetko ostatné zostane zachované.

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

Príklady pre Curl

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

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 pri GET /v1/management/bots/{bot_id} - kompletná konfigurácia bota po aplikovaní aktualizácií vrátane bloku meta. Bez poľa apiKey. Ak bot neexistuje alebo nepatrí k vášmu účtu, vráti sa 404 not_found_error.

Nižšie uvedený príklad ukazuje odpoveď po aplikovaní vyššie uvedenej požiadavky Úplné telo požiadavky (viacero sekcií) na bota z príkladu pre GET - zmenené polia odrážajú nové hodnoty, nedotknuté polia zostali zachované a hodnota meta.updatedAt sa posunula dopredu.

{
  "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čítajte aktuálne využitie predplatného pre účet, ktorý vlastní kľúč Management.

Telo odpovede (200)

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

• subscriptionType je identifikátor aktuálneho plánu účtu zapísaný malými písmenami (your-plan-id slúži ako ilustračný zástupný symbol). Plány pochádzajú z dynamického katalógu, takže presná množina identifikátorov sa môže časom meniť pri premenovaní alebo pridávaní plánov - pracujte s tým ako s nepriehľadným reťazcom, nie ako s pevne daným výčtom (enum).
• messages.used / limit / remaining predstavujú kredity na správy v aktuálnom kalendárnom mesiaci, ktoré sa resetujú v prvý deň mesiaca, nie v deň obnovenia predplatného. Sú vážené kreditmi, nejde o prostý počet odpovedí.
• bots.used / limit / remaining započítavajú vlastnených botov vrátane pozastavených botov do celkového limitu botov vášho účtu.

Hlavičky rate limitu

Odpovede, ktoré sa dostanú do fázy rate limitu (t. j. prejdú autentifikáciou a whitelistom IP adries), obsahujú:

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

• X-RateLimit-Limit - limit na kľúč skutočne aplikovaný na toto volanie (predvolene 10, alebo vaša nakonfigurovaná hodnota rateLimitPerMinute, ak je nižšia).
• X-RateLimit-Remaining - tokeny zostávajúce v zásobníku hneď po tomto volaní.
• X-RateLimit-Reset - sekundy Unix epoch, kedy bude k dispozícii ďalší token (nejde o úplný reset zásobníka; zásobník sa dopĺňa priebežne). Keď je zásobník plný, ide o 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 autentifikáciou (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) a 403 ip_not_whitelisted neobsahujú hlavičky X-RateLimit-* - kontrola limitov prebieha až po úspešnom overení autentifikácie a IP adries.

Formát chýb

Rovnaká štruktúra 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, aby sa problematická časť dala ľahko identifikovať:

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

Nesprávne 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ácií a streamovanie cez SSE si pozrite Bot Talk API.