Management API

Overzicht van de Management API

De Management API is bedoeld voor backoffice-taken waarbij geen chatberichten worden verzonden:

• programmatisch een bot aanmaken met POST /v1/management/bots
• een specifieke bot van jou opvragen met GET /v1/management/bots/{bot_id}
• een specifieke bot bijwerken met PATCH /v1/management/bots/{bot_id}
• verbruik van je abonnement opvragen met GET /v1/usage

Management-sleutels zijn gekoppeld aan je account, niet aan een specifieke bot. Ze worden bewust gescheiden gehouden van Bot Talk-sleutels, zodat een gecompromitteerde chatsleutel je bots niet kan wijzigen of je facturatiegegevens kan inzien.

Basis-URL

https://api.chatlab.com/aichat

Alle eindpunten in dit artikel zijn relatief ten opzichte van deze basis-URL.

Aan de slag

1. Open de beheeromgeving en ga naar Account Settings > Management API (Accountinstellingen > Management API).
2. Klik op Create Management Key (Management-sleutel aanmaken), geef deze een naam, stel eventueel een IP-whitelist en snelheidslimiet in en bevestig.
3. Kopieer de volledige sleutel uit de pop-up. De platte tekst wordt slechts eenmalig getoond.

Een sleutel ziet eruit als mk_abcdefghijklmnopqrstuvwxyz012345. Het voorvoegsel mk_ onderscheidt deze van Bot Talk-sleutels (ck_).

Authenticatie

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

Het verzenden van een mk_-sleutel naar /v1/chat (of een ander Bot Talk-eindpunt) retourneert 403 key_type_not_allowed. Het verzenden van een ck_-sleutel naar /v1/management/* retourneert dezelfde foutmelding.

Limieten

• Maximaal 5 actieve Management API-sleutels per gebruiker
• Maximaal 10 verzoeken per minuut per sleutel (token bucket, capaciteit van 10, gelijkmatige aanvulling met ~1 token elke 6 seconden). Kan bij het aanmaken naar beneden worden bijgesteld - stel een lagere rateLimitPerMinute in en het maximum daalt, waarbij de aanvulsnelheid evenredig meeschaalt.

Rechten

Elke Management-sleutel bevat een willekeurige subset van de drie onderstaande rechten. Er moet er bij het aanmaken minimaal één worden geselecteerd; anders wordt het verzoek geweigerd met 400 invalid_request_error. Het aanroepen van een eindpunt met een sleutel die de vereiste rechten mist, retourneert 403 insufficient_permissions.

• bot_read - vereist voor GET /v1/management/bots/{bot_id}
• bot_management - vereist voor POST /v1/management/bots en PATCH /v1/management/bots/{bot_id}
• usage - vereist voor GET /v1/usage

Structuur van de body: geneste secties die overeenkomen met de tabbladen in het beheerpaneel

POST en PATCH accepteren een JSON-body die is onderverdeeld in 13 secties. Elke sectie komt overeen met een subtabblad in de zijbalk van Bot Settings (Botinstellingen) in het beheerpaneel, zodat de JSON-sleutels en de zichtbare tabbladen op elkaar aansluiten: als je consent.humanSupportRequirePolicyAccept via de API wijzigt, zie je dezelfde schakelaar omgaan op het tabblad Consent & Privacy (Toestemming en privacy) in het beheerpaneel.

• role - botpersona, ruwe prompt, antwoordlengte, taal, context van website / bedrijf (tabblad Role & Behavior (Rol en gedrag))
• conversation - welkomstbericht, verfijning van zoekopdrachten, gesprekscontinuïteit, beoordelingsschakelaar + tooltips, inhoud van voorgestelde vragen + dynamische vervolgvragen (tabblad Chat Conversation (Chatgesprek))
• chatMemory - schakelaar voor chatgeheugen, samenvattingsprompts, toewijzing van context (tabblad Summaries & Memory (Samenvattingen en geheugen))
• appearance - kleuren, teksten, afmetingen, aangepaste CSS, welkomstscherm, vormgeving van voorgestelde vragen, gedrag voor automatisch openen, simulatie van typende medewerker, voettekst-markdown (tabblad Appearance (Vormgeving))
• humanSupport - contactformulier voor medewerker (tabblad Human Contact Form (Contactformulier medewerker))
• leadCollection - formulier voor leadverzameling (tabblad Lead Collection (Leadverzameling))
• liveChat - overdracht naar livechat (tabblad Live Chat (Livechat))
• consent - alle vier de toestemmingsschakelaars voor het privacybeleid plus de tekst van het toestemmingsscherm (tabblad Consent & Privacy (Toestemming en privacy))
• whiteLabel - logo verbergen, link voor aangepast logo, hosting op aangepast domein (tabblad Whitelabel)
• security - toegestane domeinen, spamfilter, snelheidslimieten voor gesprekken (tabblad Security (Beveiliging))
• voice - spraakinvoer en spraakgesprekken: model, stem, talen, prompt, maximale tijdsduur (tabblad Voice Conversation (Spraakgesprek))
• multilingual - meertalige modus, basistaal, aangeboden talen, omgang met kennistaal (tabblad Languages (Talen))
• advanced - LLM-model, temperatuur, contextgrootte, limiet voor botberichten, interne locale, Offer Cards (tabblad Model & Advanced (Model en geavanceerd))

Alleen name staat op het hoogste niveau, omdat dit de bot identificeert en niet bij een specifiek tabblad hoort.

De zijbalk van Bot Settings bevat momenteel 15 subtabbladen, waarvan er 13 overeenkomen met de bovenstaande secties. De twee subtabbladen zonder bijbehorende sectie zijn Flow en Actions (Acties) - beide worden hieronder behandeld onder "Buiten het bereik van de API". De 13 die wél overeenkomen zijn Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation en Languages.

De request-body en de response-body delen dezelfde structuur. De respons voegt twee extra elementen toe:

• meta - alleen-lezen: bot-id en tijdstempels. Verwijder dit om van een GET-respons een geldige POST-body te maken.
• apiKey - alleen aanwezig bij het aanmaken - de pas gegenereerde Bot Talk API-sleutel voor de nieuwe bot.

Twee velden binnen de gedeelde structuur zijn alleen-lezen - ze worden geretourneerd in het antwoord, maar genegeerd als je ze probeert mee te sturen via POST/PATCH:

• appearance.avatarUrl - volledig gekwalificeerde openbare URL van de bot-avatarafbeelding (bijv. https://api.chatlab.com/aichat/content/avatar_xyz.png). Voer hier rechtstreeks een GET op uit om de bytes te downloaden. Om deze te wijzigen, upload je een nieuw bestand via het multipart-onderdeel avatar (zie PATCH).
• whiteLabel.whitelabelLogoUrl - volledig gekwalificeerde openbare URL van het whitelabel-koptekstlogo. Hetzelfde patroon als avatarUrl. Om deze te wijzigen, upload je een nieuw bestand via het multipart-onderdeel whitelabel_logo (zie PATCH).

Beide URL's gebruiken het schema + host + contextpad van het huidige verzoek, dus op een whitelabel aangepast domein worden ze geretourneerd met dat domein als basis (bijv. https://api.acme.com/aichat/content/...).

Stuur null voor een sectie om deze over te slaan bij PATCH; stuur null voor een veld binnen een sectie om dat enkele veld over te slaan. Een null op veldniveau wist nooit een opgeslagen waarde - het betekent alleen "niet wijzigen".

Rol- en promptopbouw

De systeemprompt die het LLM daadwerkelijk ontvangt, wordt op een van de volgende twee manieren opgebouwd, afhankelijk van role.role. Door te weten welke route wordt gevolgd, weet je welke velden van belang zijn en welke worden opgeslagen maar genegeerd.

Route A - role.role is CUSTOMER_SUPPORT, SALES of LEAD_COLLECTION_AGENT (sjabloongestuurd)

De backend stelt de prompt samen op basis van een ingebouwd sjabloon en negeert role.rawPrompt volledig (de waarde wordt nog steeds opgeslagen bij de bot, maar niet gebruikt). Het sjabloon bevat:

• role.role - rollabel (bijv. "Customer Support") en automatisch toegevoegde rolspecifieke instructies
• name - naam van de bot, ingevoegd in de openingszin
• role.language - "Auto Detect" stelt de bot in om de taal van de gebruiker te volgen; elke andere waarde (bijv. "English", "Polish") wordt "Output in {language}, unless user uses another language"
• role.responseLength - gekoppeld aan een streefaantal woorden: Concise ≈ 50 woorden, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - optioneel; indien niet leeg, toegevoegd als "for the users of the website {url}"
• role.companyDescription - optioneel; indien niet leeg, voorafgegaan als een extra alinea vóór de rolinstructies

Dit is de aanbevolen route voor de meeste bots - je krijgt automatisch op de rol afgestemd gedrag en veiligheidskaders.

Route B - role.role is CUSTOM (door aanroeper geleverde prompt)

De backend gebruikt role.rawPrompt letterlijk als de volledige systeemprompt. responseLength, language, websiteAddress en companyDescription worden opgeslagen, maar niet in de prompt ingevoegd - als je wilt dat een van deze elementen terugkomt in het gedrag van de bot, moet je ze zelf opnemen in de tekst van je rawPrompt. Rolspecifieke veiligheidskaders en instructies voor de tone-of-voice worden ook niet toegevoegd; je beheert zelf de volledige prompt.

Gebruik CUSTOM alleen wanneer de sjabloongestuurde prompt niet aansluit op je use case (bijv. als je een zeer domeinspecifieke persona, je eigen veiligheidsbeperkingen of een niet-standaard uitvoerformaat nodig hebt).

Enum- / vastewaardenvelden

Verschillende velden accepteren uitsluitend een vaste set van tekenreekswaarden. Het verzenden van een waarde buiten de lijst wordt geweigerd met 400 validation_failed en het veldpad in error.param. Waarden zijn hoofdlettergevoelig.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - volledige Engelse taalnaam uit het vervolgkeuzemenu in het beheerpaneel, bijv. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi en ~80 andere. De waarde wordt letterlijk opgeslagen en ingevoegd in het promptsjabloon, dus tweeletterige ISO-codes (en, pl) en andere waarden buiten de lijst worden niet afgewezen door de API, maar leiden tot een verstoorde instructie zoals "Output in en, unless...". Standaard ingesteld op Auto Detect indien weggelaten bij het aanmaken.
• advanced.model - zie "AI-tekstmodellen" hieronder; de selecteerbare set is afhankelijk van je accountlimieten en elke waarde die je account niet kan gebruiken retourneert 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Afhankelijk van je accountlimieten; hogere waarden worden stilzwijgend afgekapt
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - booleaanse schakelaar. true verplicht de gebruiker om het leadformulier in te vullen voordat een gesprek wordt gestart; false laat de AI bepalen wanneer het formulier wordt getoond (standaard).

Gestructureerde velden en bereiken

Velden die eruitzien als eenvoudige strings of getallen, maar in werkelijkheid specifieke formaten, bereiken of eigenaardigheden in het beheerpaneel hebben die handig zijn om te weten.

• advanced.temperature - geaccepteerd bereik is 0.0 tot 1.0, overeenkomend met de schuifregelaar in het beheerpaneel. Waarden buiten dit bereik worden geweigerd met 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - geheel getal als percentage, 10-90 met stap 10. Bepaalt hoeveel van de chatcontext wordt gereserveerd voor historische samenvattingen van de bezoeker ten opzichte van de rest (kennisbank, huidig gesprek, instructies). Standaard 50. Waarden buiten 10-90 worden geweigerd met 400 validation_failed. Alleen van toepassing wanneer chatMemory.enabled=true EN chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON gecodeerd als string, geen genest JSON-object in het verzonden verzoek. De server slaat de ruwe string letterlijk op; het beheerpaneel ontleedt deze aan de clientzijde bij het renderen van de roosterbewerker. Na het ontleden heeft de string de structuur van één item per weekdag plus een timezone-sleutel:

  • elke weekdagsleutel (monday-sunday) is gekoppeld aan {enabled: boolean, from: "H:MM", to: "H:MM"} in een 24-uursnotatie
  • timezone is een IANA-zonenaam (bijv. "Europe/Warsaw", "America/New_York")

  Voorbeeldwaarde (let op de buitenste aanhalingstekens en de ge-escapete binnenste aanhalingstekens - het is één stringveld, geen genest object):

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

  Buiten de aangegeven uren wordt liveChat.outOfHoursMessage aan de bezoeker getoond en wordt de overdracht naar livechat onderdrukt. Validatie van de interne structuur vindt alleen plaats aan de clientzijde in het beheerpaneel - ongeldige JSON of niet-herkende sleutels worden door de API gewoon als string geaccepteerd en leiden tot een weergavefout wanneer een beheerder de bot later opent in het beheerpaneel. Valideer de structuur aan je eigen kant voordat je deze verstuurt.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - korte labels die worden weergegeven op de 👍 / 👎-knoppen naast elk AI-antwoord wanneer conversation.conversationRatingEnabled=true. De standaardtekst is "I like the response" / "I don't like the response". Zichtbaar voor eindgebruikers.

• whiteLabel.hideRoboAssistLogo - whitelabel-functie, afhankelijk van je accountlimieten. Verbergt de voettekstregel "Powered by ChatLab". Als je account geen whitelabeling bevat, wordt de waarde opgeslagen maar genegeerd en wordt de voettekst altijd weergegeven.

• whiteLabel.whitelabelLogoLink - whitelabel-functie, afhankelijk van je accountlimieten. URL voor de klikbestemming van het aangepaste logo wanneer hideRoboAssistLogo=true en er een aangepast logobestand is geüpload via het multipart-onderdeel whitelabel_logo.

• appearance.simulateHumanTypingDelay - seconden (geen milliseconden), geheel getal 0-200. Pauze tussen opeenvolgende bot-tekstballonnen wanneer simulateHumanTyping=true. Standaard 5.

• appearance.autoOpenChatDelaySeconds - seconden, geheel getal. Vertraging voordat de widget automatisch opent wanneer autoOpenChat=true en autoOpenChatDelay=true.

• advanced.internalLocale - IETF-code voor taal en regio in de vorm ll_CC (laag liggend streepje, NIET ll-CC met een koppelteken). Geaccepteerde waarden zijn afkomstig uit een vaste lijst van ~95 locales: 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 en vele andere. Het verzenden van alleen een tweeletterige code ("en") of BCP-47 ("en-US") komt niet voor in de lijst met toegestane waarden. Standaard en_US. Dit is de locale die wordt gebruikt voor de opmaak van datums en getallen in de interface van de widget, los van role.language (de uitvoertaal van de bot in gesprekken).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - gehele getallen (verzend als JSON-getallen, bijv. 30, niet "30"). 0 schakelt de snelheidslimiet per IP-adres uit. Indien niet-nul dwingt de widget maximaal N berichten per duur-in-seconden af voordat security.talkMessagesRateLimitHitMessage aan de bezoeker wordt getoond.

• advanced.botMessagesLimit - geheel getal (JSON-getal, bijv. 1000). 0 betekent "geen limiet"; anders moet het een veelvoud van 1000 zijn (1000, 2000, 10000, ...). Waarden zoals 100 of 1500 worden geweigerd met 400 validation_failed. Vervolgens wordt de waarde stilzwijgend begrensd op je accountlimiet.

AI-tekstmodellen (advanced.model)

Stuur de exacte API-waarde (de linkerkolom met code-opmaak). De weergavenaam in het beheerpaneel staat tussen haakjes. Je accountlimieten bepalen welke subset selecteerbaar is; het verzenden van een model dat je account niet kan gebruiken retourneert 400 invalid_parameter. De standaardwaarde voor nieuwe bots is 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)

Veldreferentie (volledig request-schema)

Elk veld op de lijn, met type, restrictie en een beschrijving van één regel. PATCH-semantiek: elk weggelaten veld (of verzonden als null) laat de opgeslagen waarde ongewijzigd. Dezelfde vorm wordt gebruikt voor de response (minus multipart binaire inhoud; plus het alleen-lezen meta-blok bij elke response en apiKey alleen bij de create-response).

Hoogste niveau

Veld	Type	Restrictie	Beschrijving
name	string	max 150, verplicht bij aanmaken	Weergavenaam van de bot
role	object		Zie § role
conversation	object		Zie § conversation
chatMemory	object		Zie § chatMemory
appearance	object		Zie § appearance
humanSupport	object		Zie § humanSupport
leadCollection	object		Zie § leadCollection
liveChat	object		Zie § liveChat
consent	object		Zie § consent
whiteLabel	object		Zie § whiteLabel
security	object		Zie § security
advanced	object		Zie § advanced

Toevoegingen die alleen in de response voorkomen:

• meta: { id, createdAt, updatedAt } - alleen-lezen.
• apiKey - string, alleen aanwezig in de response van POST /v1/management/bots - de nieuw aangemaakte Bot Talk-sleutel voor de nieuwe bot, precies één keer geretourneerd.

§ role

Veld	Type	Restrictie	Beschrijving
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Persona-voorinstelling; selecteert de prompt-template (zie "Role and prompt construction")
language	string	volledige Engelse taalnaam (English, Polish, ...) of Auto Detect	Primaire taal die aan de prompt-template wordt doorgegeven
responseLength	string	∈ {Concise, Normal, Detailed}	Gewenste breedsprakigheid van het AI-antwoord
websiteAddress	string		Website die wordt gebruikt voor prompt-context
companyDescription	string		Bedrijfsomschrijving die wordt gebruikt voor prompt-context
rawPrompt	string		Aangepaste systeemprompt - wordt alleen letterlijk gebruikt wanneer role=CUSTOM

§ conversation

Veld	Type	Restrictie	Beschrijving
welcomeMessage	string		Eerste bericht dat bij het openen aan de bezoeker wordt getoond
queryRefinementEnabled	boolean		Indien true, verfijn de vraag van de bezoeker vóór RAG-retrieval
conversationContinuityEnabled	boolean		Indien true, hervatten terugkerende bezoekers hun laatste gesprek
conversationRatingEnabled	boolean		Indien true, toon duim omhoog/omlaag-beoordeling bij botberichten
positiveRatingTooltip	string		Tooltip op de knop voor positieve beoordeling
negativeRatingTooltip	string		Tooltip op de knop voor negatieve beoordeling
suggestedQuestions	string		Door witregels gescheiden voorgestelde vragen / gesprekstarters
dynamicSuggestedFollowups	boolean		Indien true, stelt de AI na elk antwoord vervolgsuggesties voor
dynamicFollowupsAutoIcons	boolean		Indien true, kiest de AI automatisch emoji-pictogrammen voor de dynamische vervolgvragen

§ chatMemory

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Hoofdschakelaar voor de chatgeheugenfunctie
summaryConversationsEnabled	boolean		Samenvattingen per gesprek opslaan
conversationSummaryPrompt	string		Aangepaste prompt voor het samenvatten van elk gesprek
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Of de standaard of de aangepaste samenvattingsprompt moet worden gebruikt
clientSummaryPrompt	string		Aangepaste prompt voor het samenvatten van het klantprofiel over gesprekken heen
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Standaard versus aangepaste klantprofielprompt
summariesToKnowledgeRatio	int	10-90, stap 10	% van het chatcontextvenster toegewezen aan samenvattingen vs RAG-kennis

§ appearance

Veld	Type	Restrictie	Beschrijving
launcherColor	string (hex)		Achtergrondkleur van de launcher (chat-icoon)
headerColor	string (hex)		Achtergrondkleur van de chat-header
titleColor	string (hex)		Titelkleur van de chat-header
subtitleColor	string (hex)		Subtitelkleur van de chat-header
clientMessageBubbleColor	string (hex)		Tekstballonkleur van bezoekersberichten
clientMessageTextColor	string (hex)		Tekstkleur van bezoekersberichten
responseMessageBubbleColor	string (hex)		Tekstballonkleur van botantwoorden
responseMessageTextColor	string (hex)		Tekstkleur van botantwoorden
chatSubheader	string		Ondertitel die onder de chattitel wordt getoond
senderPlaceholder	string		Placetekst in het invoerveld voor berichten
resetConversationTooltip	string		Tooltip op de knop "gesprek resetten"
chatAlignment	string (enum)	∈ {left, right}	Aan welke kant van het scherm de chat wordt verankerd
launcherBottomMargin	int	0-500	Afstand van de launcher tot de onderrand (px)
launcherSideMargin	int	0-500	Afstand van de launcher tot de zijrand (px)
displayShadow	boolean		Slagschaduw onder de widget
customCss	string		Ruwe CSS die in het iframe van de widget wordt geïnjecteerd
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Hoe links in botberichten worden geopend
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Geminimaliseerde weergave: launcher-icoon of compacte balk
chatDesktopWidthPx	int		Breedte van desktop-widget
chatDesktopHeightPx	int		Hoogte van desktop-widget
chatMobileSizePercent	int		Grootte van mobiele widget als % van het weergavevenster
messageFontSize	int		Lettergrootte van berichttekst (px)
showChatbotBubblesDesktop	boolean		Toon de zwevende aandachttrekkende tekstballonnen op desktop
showChatbotBubblesMobile	boolean		Toon de zwevende aandachttrekkende tekstballonnen op mobiel
chatbotBubblesDelaySeconds	int		Vertraging voordat de tekstballonnen verschijnen (seconden)
launcherIconFullSize	boolean		Toon het aangepaste launcher-icoon beeldvullend in plaats van met marge
welcomeScreenEnabled	boolean		Toon het welkomstscherm in plaats van direct naar de chat te gaan
welcomeScreenQuestionsLabel	string		Label boven de voorgestelde vragen op het welkomstscherm
welcomeScreenHideHumanContactForm	boolean		Verberg de actie voor het contactformulier voor medewerkers in de header zolang het welkomstscherm actief is. Deze verschijnt weer na het eerste bericht van de bezoeker. Bots die vóór 2026-09-02 zijn aangemaakt, staan standaard op true
welcomeScreenHideLiveChat	boolean		Verberg de livechat-actie in de header zolang het welkomstscherm actief is. Deze verschijnt weer na het eerste bericht van de bezoeker. Bots die vóór 2026-09-02 zijn aangemaakt, staan standaard op true
headerActionsLayout	string	DROPDOWN	Hoe livechat en het contactformulier voor medewerkers in de chat-header worden aangeboden: ICONS (elk een apart icoon) of DROPDOWN (gegroepeerd in het headermenu). Bots die vóór 2026-09-02 zijn aangemaakt, staan standaard op ICONS
stackSuggestedQuestions	boolean		Voorgestelde vragen verticaal stapelen (in plaats van naast elkaar)
suggestedQuestionsFontSize	int		Lettergrootte van de chips met voorgestelde vragen (px)
suggestedQuestionsTextColor	string (hex)		Tekstkleur van de chips met voorgestelde vragen
suggestedQuestionsBackgroundColor	string (hex)		Achtergrondkleur van de chips met voorgestelde vragen
autoOpenChat	boolean		Chat automatisch openen op desktop
autoOpenChatOnMobiles	boolean		Chat automatisch openen op mobiel
autoOpenChatDelay	boolean		Vertraging gebruiken vóór automatisch openen
autoOpenChatDelaySeconds	int		Vertraging voor automatisch openen (seconden)
simulateHumanTyping	boolean		Splits botantwoord op in tekstballonnen met typanimatie
simulateHumanTypingDelay	int	0-200	Vertraging tussen tekstballonberichten (seconden)
footerMarkdown	string	max 255	Aangepaste footer-markdown die onder de chat wordt getoond
avatarUrl	string	alleen-lezen	Volledig gekwalificeerde openbare URL van de avatar; upload via het multipart-onderdeel avatar om deze te wijzigen

Multipart bij POST/PATCH: avatar (bestandsonderdeel). GET- / response-body's laten de bestandsinhoud weg - alleen de URL bevindt zich op de lijn.

§ humanSupport

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor de menselijke ondersteuningsflow
email	string	verplicht (create-strict) wanneer enabled=true	Adres dat e-mails voor menselijke ondersteuning ontvangt
dialogMessage	string		Aanmoedigend bericht dat boven het formulier wordt getoond
thankYouMessage	string		Bevestiging die na verzending wordt getoond
emailMessageSubjectTemplate	string		Onderwerptemplate voor de e-mail die naar de medewerker wordt gestuurd
emailMessageContentTemplate	string		Hoofdteksttemplate voor de e-mail die naar de medewerker wordt gestuurd
emailPlaceholder	string		Placetekst in het e-mailinvoerveld
messagePlaceholder	string		Placetekst in het tekstvak voor het bericht
emailWithConversationContent	boolean		Indien true, neem het transcript van het gesprek op in de e-mailtekst
customFormId	long	id van een bestaand aangepast formulier	Vervang het ingebouwde contactformulier door een aangepast formulier. null behoudt het ingebouwde formulier
customFormMapping	string	JSON-gecodeerde string	Koppelt velden van het aangepaste formulier aan de velden van de e-mail voor menselijke ondersteuning

requirePolicyAccept bevindt zich op consent.humanSupportRequirePolicyAccept, niet hier.

§ leadCollection

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor leadformulier
nameEnabled	boolean		Naam verzamelen
nameLabel	string		Label op het naaminvoerveld
emailEnabled	boolean		E-mailadres verzamelen
emailLabel	string	verplicht (create-strict) wanneer enabled=true EN emailEnabled=true	Label op het e-mailinvoerveld
phoneEnabled	boolean		Telefoonnummer verzamelen
phoneLabel	string	verplicht (create-strict) wanneer enabled=true EN phoneEnabled=true	Label op het telefooninvoerveld
leaveDetailsMessage	string	verplicht (create-strict) wanneer enabled=true	Bericht waarin de bezoeker wordt aangemoedigd gegevens achter te laten
thankYouMessage	string	verplicht (create-strict) wanneer enabled=true	Bevestiging die na verzending wordt getoond
requireBeforeNewConversation	boolean		Indien true, moet het formulier worden verzonden voordat de chat begint; indien false, bepaalt de AI wanneer het formulier wordt getoond
emailNotificationEnabled	boolean		Stuur de eigenaar een e-mail telkens wanneer een lead wordt verzameld
emailNotificationAddress	string		Ontvanger van de melding (standaard ingesteld op het account-e-mailadres)
emailWithConversationContent	boolean		Indien true, neem het transcript van het gesprek op in de melding

Create-strict regel over meerdere velden: enabled=true vereist ten minste emailEnabled of phoneEnabled. requirePolicyAccept bevindt zich op consent.leadCollectionRequirePolicyAccept, niet hier.

| customFormId | long | id van een bestaand aangepast formulier | Vervang het ingebouwde leadformulier door een aangepast formulier. null behoudt het ingebouwde formulier | | customFormMapping | string | JSON-gecodeerde string | Koppelt velden van het aangepaste formulier aan naam / e-mail / telefoon |

§ liveChat

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor Live Chat-functie
infoMessage	string		Toelichtend bericht voorafgaand aan overdracht
startMessage	string		Bericht dat wordt getoond wanneer de livesessie begint
endMessage	string		Bericht dat wordt getoond wanneer de livesessie eindigt
nameLabel	string		Label op het naaminvoerveld in het voorbereidende livechat-formulier
emailLabel	string		Label op het e-mailinvoerveld in het voorbereidende livechat-formulier
schedule	string	JSON-gecodeerde string (schakelaars voor weekdagen + from/to + timezone)	Bedrijfstijden voor livechat - zie "Structured fields and ranges" voor de exacte structuur
outOfHoursMessage	string		Bericht dat wordt getoond wanneer het schema aangeeft dat we gesloten zijn
closeModalMessage	string		Titel van de modal "livechat sluiten?"
closeModalConfirmLabel	string		Label op de bevestigingsknop in de sluitmodal
closeModalCancelLabel	string		Label op de annuleringsknop in de sluitmodal
closeModalTooltipText	string		Tooltip op het bedieningselement voor het sluiten van de chat
operatorHasJoinedLabel	string		Label dat wordt getoond wanneer een medewerker deelneemt
operatorDidNotJoinInTimeLabel	string		Label dat wordt getoond wanneer geen enkele medewerker binnen de time-outperiode deelneemt
waitingForOperatorToJoinLabel	string		Label dat wordt getoond tijdens het wachten op een medewerker
waitingForOperatorSeconds	int		Time-out voor het aannemen door een medewerker (seconden)
redirectToHumanSupportForm	boolean		Indien true, val terug op het formulier voor menselijke ondersteuning wanneer er geen medewerker reageert
missedEmailEnabled	boolean	standaard true	Stuur de eigenaar van de bot een e-mail wanneer een livechat-verzoek niet is beantwoord. Niet ingesteld bij verouderde bots, wat als ingeschakeld wordt geïnterpreteerd

requirePolicyAccept bevindt zich op consent.liveChatRequirePolicyAccept, niet hier.

§ consent

Veld	Type	Restrictie	Beschrijving
newConversationRequirePolicyAccept	boolean		Toestemming voor privacybeleid vereisen voordat een nieuw gesprek wordt gestart
humanSupportRequirePolicyAccept	boolean		Toestemming voor privacybeleid vereisen voordat het formulier voor menselijke ondersteuning wordt verzonden
leadCollectionRequirePolicyAccept	boolean		Toestemming voor privacybeleid vereisen voordat het leadformulier wordt verzonden
liveChatRequirePolicyAccept	boolean		Toestemming voor privacybeleid vereisen voordat een livechat-sessie wordt gestart
newConversationConsentDescription	string		Inleidende tekst voor het toestemmingsscherm bij de start van het gesprek
privacyPolicyConsentCheckboxLabel	string		Label naast het selectievakje voor toestemming (bevat meestal een link naar het privacybeleid)

§ whiteLabel

Veld	Type	Restrictie	Beschrijving
hideRoboAssistLogo	boolean	whitelabel-functie; onderhevig aan accountlimieten	Verberg het standaard ChatLab-logo in de footer
whitelabelLogoLink	string	whitelabel-functie; onderhevig aan accountlimieten	URL waar het aangepaste footer-logo naar linkt
assignToCustomDomain	boolean	gekoppeld aan CUSTOM_DOMAIN-functie	Host de chat op het geconfigureerde aangepaste domein
whitelabelLogoUrl	string	alleen-lezen	Volledig gekwalificeerde openbare URL van het whitelabel-logo; upload via het multipart-onderdeel whitelabel_logo om dit te wijzigen

Multipart bij POST/PATCH: whitelabel_logo (bestandsonderdeel). GET- / response-body's laten de bestandsinhoud weg - alleen de URL bevindt zich op de lijn.

§ security

Veld	Type	Restrictie	Beschrijving
allowedDomains	string		Door komma's gescheiden lijst van domeinen die de widget mogen insluiten (leeg = geen whitelist)
spamFilterEnabled	boolean		Schakel het spamfilter per bot in voor inkomende berichten
countryFilterMode	string	BLACKLIST of WHITELIST	Hoe de landenlijsten worden geïnterpreteerd. De lijsten zelf blijven alleen toegankelijk voor beheerders
talkMessagesRateLimit	int	>= 0; 0 schakelt uit	Maximaal aantal gebruikersberichten toegestaan binnen het rate-limitvenster
talkMessagesRateLimitDurationSeconds	int	>= 0	Duur van het rate-limitvenster (seconden)
talkMessagesRateLimitHitMessage	string		Bericht dat aan de bezoeker wordt getoond wanneer de rate-limit is bereikt

§ voice

Veld	Type	Restrictie	Beschrijving
inputEnabled	boolean		Bezoeker toestaan berichten in te spreken (spraak-naar-tekst)
conversationEnabled	boolean	vereist de voice-functie in het plan	Volledige spraakgesprekken inschakelen
voiceId	string	providerspecifieke stem-id (bijv. alloy)	Welke synthetische stem spreekt
model	string	bijv. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Spraakmodel. Gefactureerd per minuut, tarieven verschillen per model
turnDetection	string	providerspecifiek	Modus voor beurtverdeling
audioPrompt	string		Extra systeemprompt die alleen voor spraakbeurten wordt gebruikt
welcomeMessage	string		Gesproken openingszin
language	string	taalcode	Primaire spraaktaal
additionalLanguages	string	door komma's gescheiden taalcodes	Extra talen die de stemagent accepteert
maxDurationSeconds	int		Maximale harde limiet voor een enkel spraakgesprek
maxDurationMessage	string		Bericht dat wordt getoond wanneer de limiet is bereikt

§ multilingual

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor meertalige modus
mode	string	AUTODETECT of een vaste-lijstmodus	Hoe de bot de antwoordtaal kiest
baseLanguage	string	taalcode	Taal waarin de eigen teksten van de bot zijn geschreven
languages	string	door komma's gescheiden taalcodes	Talen die aan de bezoeker worden aangeboden
knowledgeLanguageMode	string		Hoe kennis in andere talen wordt behandeld
knowledgeLanguageFallback	string	taalcode	Terugvaltaal die wordt gebruikt als er geen match wordt gevonden

§ advanced

Veld	Type	Restrictie	Beschrijving
model	string	onderhevig aan accountlimieten; zie "AI text models" hierboven	LLM-identificator (bijv. 5-MINI)
temperature	decimal	0.0-1.0	Bemonsteringstemperatuur (komt overeen met de UI-schuifregelaar)
chatContextSize	int	∈ {8000, 16000, 32000}; stilzwijgend begrensd op jouw accountlimiet	Tokenvenster voor chatgeschiedenis
botMessagesLimit	long	0 of veelvoud van 1000 (bijv. 1000, 2000, 10000)	Maximaal aantal botantwoorden per gesprek (0 = geen limiet)
internalLocale	string	taalcode in de vorm ll_CC	Regio-instelling voor widget-chromelabels (verschilt van role.language)
productsViewEnabled	boolean		Indien true, toon de e-commerce Offer Cards in de chat
includeProductsInKnowledgeBase	boolean		Indien true, indexeer de productcatalogus als onderdeel van de kennisbank

Buiten het bereik van de API

De beheer-UI bevat een aantal onderdelen die bewust niet worden aangeboden in deze versie van de Management API:

• Tabblad Flow (Stroom) - de visuele Conversation Flow-editor (fasen en overgangen). Niet beschikbaar via de Management API.
• Tabblad Actions (Acties) - beheerde e-commerce- / boeking-integraties, AI Search en aangepaste API-functies. Tool calling is nooit onderdeel geweest van de Management API.
• De bouwer voor aangepaste formulieren zelf - het aanmaken en bewerken van aangepaste formulieren is niet beschikbaar. Je kunt echter wel een bestaand formulier aan een bot koppelen via leadCollection.customFormId en humanSupport.customFormId.
• Aangepaste pictogrammen voor chat openen / sluiten - customLauncherIconVisible, openChatIcon, closeChatIcon. De API biedt alleen de hoofdonderdelen avatar en whitelabel_logo via multipart aan.
• IP- en landenlijsten - de vermeldingen zelf zijn alleen toegankelijk voor beheerders. Alleen de interpretatiemodus wordt aangeboden via security.countryFilterMode.

Endpoints

POST /v1/management/bots

Maak een nieuwe bot aan. Er worden twee gelijkwaardige Content-Types geaccepteerd; kies het type dat het handigst is.

Modus A - gewone JSON (aanbevolen wanneer je niet in hetzelfde verzoek een avatar / logo hoeft te uploaden):

• Content-Type: application/json
• De request-body is de bot-configuratie-JSON (geen data-wrapper)
• Bestanden (avatar / logo) kunnen later worden geüpload via een tweede PATCH met modus B

Modus B - multipart/form-data (gebruik dit bij het uploaden van bestanden in hetzelfde verzoek):

• Content-Type: multipart/form-data; boundary=...
• data JSON-onderdeel (verplicht, Content-Type: application/json) - bot-configuratie in de hierboven beschreven geneste structuur
• avatar bestandsonderdeel (optioneel) - bot-avatarafbeelding
• whitelabel_logo bestandsonderdeel (optioneel) - white-label-logo (alleen van toepassing als je account White Label omvat)

Alleen name is verplicht in de JSON; elk ander veld valt terug op dezelfde standaardwaarde die de wizard in de admin-UI zou instellen.

Volledige request-body

Dit is de maximale data-JSON - elke sectie is ingevuld. Verstuur alleen de secties die voor jou van belang zijn; al het andere krijgt standaardwaarden.

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

Validatieregels met hun eigen foutmeldingen:

• name - verplicht, maximaal 150 tekens
• advanced.temperature - tussen 0.0 en 1.0
• chatMemory.summariesToKnowledgeRatio - geheel getal tussen 10 en 90 (percentage, stapgrootte 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - tussen 0 en 500
• appearance.footerMarkdown - maximaal 255 tekens
• humanSupport.enabled=true vereist dat humanSupport.email is ingesteld
• leadCollection.enabled=true vereist dat ten minste één van leadCollection.emailEnabled of leadCollection.phoneEnabled op true staat; welk kanaal ook actief is, het bijbehorende label is ook verplicht, plus leaveDetailsMessage en thankYouMessage
• Begrensde velden (advanced.chatContextSize, advanced.botMessagesLimit, etc.) worden geruisloos beperkt tot de limieten van je account

Velden waarvan de waarde op de server null is, worden weggelaten uit de JSON-body - alleen velden met niet-null-waarden worden verzonden.

Volledige response-body (201)

Dezelfde structuur als het verzoek, plus het alleen-lezen meta-blok en de eenmalige apiKey op het hoogste niveau. Alleen-lezen bestands-URL's (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) worden door de server ingevuld wanneer de bijbehorende multipart-onderdelen zijn geüpload.

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

Het veld apiKey verschijnt alleen bij het aanmaken - het is de nieuw gegenereerde Bot Talk-sleutel die aan de nieuwe bot is gekoppeld. De tekst zonder opmaak wordt eenmalig getoond en kan later niet meer via de API worden opgehaald; sla deze direct aan jouw kant op.

De respons-header Location bevat de URL van de nieuwe bot (/v1/management/bots/{id}).

Curl-voorbeelden

Modus A - gewone JSON (eenvoudigst):

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

Modus B - multipart met avatar:

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}

Haal de huidige configuratie op van een bot waarvan jij eigenaar bent.

Curl-voorbeeld

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

Volledige response-body (200)

Dezelfde structuur als de POST-respons, minus de eenmalige apiKey. Het meta-blok is inbegrepen. Retourneert 404 not_found_error als de bot niet bestaat of niet bij jouw account hoort.

De huidige avatar en het white-label-logo worden weergegeven als volledig gekwalificeerde alleen-lezen URL's (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - gebaseerd op hetzelfde schema + host + contextpad dat dit verzoek heeft afgehandeld. Haal de bytes op door een GET-verzoek rechtstreeks naar die URL's te sturen; om een bestand te vervangen, upload je een nieuw bestand via het multipart avatar / whitelabel_logo-onderdeel bij PATCH. Deze URL-velden worden genegeerd als ze in een request-body worden verzonden.

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

Een bot klonen

De request body van POST /v1/management/bots en de response body van GET /v1/management/bots/{bot_id} hebben dezelfde structuur, dus klonen is een proces in drie stappen: voer een GET uit op de bron, verwijder door de server beheerde identiteitsvelden en stuur het resultaat via POST.

1. Voer een GET uit op de bronbot.

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

2. Verwijder het meta-blok op het hoogste niveau. Het meta-object (id, createdAt, updatedAt) wordt door de server beheerd en is alleen-lezen - het in de POST-body laten staan kan geen kwaad (de server negeert het), maar door het te verwijderen maak je de intentie expliciet en blijft de payload overzichtelijk. Pas eventueel de name aan, zodat de kloon te onderscheiden is van de bron.

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

3. Voer een POST uit met de gestripte body om de kloon aan te maken. Raadpleeg de bovenstaande referentie van POST /v1/management/bots voor de volledige body-structuur en validatieregels.

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

De respons bevat de meta.id van de nieuwe bot plus een nieuw aangemaakte apiKey (de Bot Talk-sleutel voor de kloon). De apiKey in platte tekst wordt alleen bij deze create-respons geretourneerd - kopieer deze voordat je de response body verwijdert; deze kan later niet meer worden opgehaald.

Twee kanttekeningen:

• Bestanden worden niet gekloond. appearance.avatarUrl en whiteLabel.whitelabelLogoUrl zijn alleen-lezen en verwijzen naar de bestanden van de bronbot. Als je dezelfde avatar of hetzelfde White Label-logo op de kloon nodig hebt, download dan de bytes van de bron-URL's en upload ze als multipart avatar / whitelabel_logo-onderdelen - via de create-POST (Modus B) of via een latere PATCH.
• Bot Talk-sleutels worden niet gekloond. Elke bot heeft zijn eigen pool van Bot Talk-sleutels. De enkele apiKey die door de create-POST wordt geretourneerd, is de enige die automatisch wordt aangemaakt; maak indien nodig extra sleutels aan via het API-tabblad van de bot.

PATCH /v1/management/bots/{bot_id}

Werk een of meer velden bij van een bot die van jou is. Alleen secties / velden die in de JSON aanwezig zijn, worden gewijzigd; alles wat wordt weggelaten (of als null wordt verzonden), blijft ongewijzigd. Semantiek voor gedeeltelijke updates is van toepassing per veld binnen een verzonden sectie.

Er worden twee gelijkwaardige Content-Types geaccepteerd (hetzelfde als bij POST):

Modus A - platte JSON (aanbevolen wanneer je alleen instellingen bijwerkt):

• Content-Type: application/json
• Request body is de patch-JSON (geen data-wrapper)

Modus B - multipart/form-data (gebruik bij het uploaden van bestanden):

• data JSON-onderdeel (optioneel) - de patch. Stuur dit alleen mee als je velden wilt wijzigen. Laat het volledig weg als je alleen een avatar of logo wilt uploaden.
• avatar bestandsonderdeel (optioneel) - vervang de avatar
• whitelabel_logo bestandsonderdeel (optioneel) - vervang het White Label-logo (alleen van toepassing als je account White Label bevat)

Alle drie de onderdelen zijn optioneel bij PATCH, maar er moet er minstens één aanwezig zijn om de aanroep zinvol te maken.

Volledige request body (maximale omvang)

Elk veld dat wordt geaccepteerd door POST /v1/management/bots mag hier ook worden verzonden. Het onderstaande voorbeeld toont de volledige omvang; in de praktijk verzend je alleen de sleutels die je wilt wijzigen (zie "Minimale gedeeltelijke update" verderop) - elke sleutel die wordt weggelaten (of als null wordt verzonden), laat de opgeslagen waarde ongewijzigd.

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

Minimale gedeeltelijke update

Voer een PATCH uit op een enkel veld door precies die sleutels te verzenden die je wilt wijzigen - al het overige blijft behouden.

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

Curl-voorbeelden

Modus A - platte JSON (eenvoudigst):

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

Modus B - multipart (bij het vervangen van avatar / logo):

curl -X PATCH https://api.chatlab.com/aichat/v1/management/bots/4287 \
  -H "Authorization: Bearer mk_..." \
  -F 'data={"appearance":{"launcherColor":"#abcdef"}};type=application/json' \
  -F 'avatar=@./new-avatar.png'

Modus B - alleen de avatar vervangen (geen veldwijzigingen):

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

Response body (200)

Zelfde structuur als GET /v1/management/bots/{bot_id} - de volledige configuratie van de bot nadat de patch is toegepast, inclusief het meta-blok. Geen apiKey-veld. Retourneert 404 not_found_error als de bot niet bestaat of niet bij jouw account hoort.

Het onderstaande voorbeeld toont de respons na het toepassen van de bovenstaande Volledige request body (maximale omvang)-patch op de bot uit het GET-voorbeeld - gewijzigde velden tonen de nieuwe waarden, niet-gewijzigde velden blijven behouden en meta.updatedAt schuift op.

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

Lees het huidige abonnementsverbruik uit voor het account dat eigenaar is van de Management-sleutel.

Response body (200)

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

• subscriptionType is een identificatie in kleine letters van het huidige plan van het account (bijv. standard in het voorbeeld). Plannen zijn afkomstig uit een dynamische catalogus, dus de exacte set identificaties kan in de loop van de tijd veranderen naarmate plannen worden hernoemd of toegevoegd - behandel dit als een ondoorzichtige string, niet als een vast enum.
• messages.used / limit / remaining zijn de berichtcredits van de huidige factureringsperiode.
• bots.used / limit / remaining tellen het aantal actieve bots ten opzichte van de botlimiet van jouw account.

Rate limit headers

Antwoorden die de rate-limit-fase bereiken (d.w.z. authenticatie en IP-whitelist zijn geslaagd) bevatten:

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

• X-RateLimit-Limit - de limiet per sleutel die daadwerkelijk op deze aanroep is toegepast (standaard 10, of je geconfigureerde rateLimitPerMinute indien lager).
• X-RateLimit-Remaining - resterende tokens in de bucket direct na deze aanroep.
• X-RateLimit-Reset - Unix epoch-seconden waarop het volgende token beschikbaar komt (geen volledige bucket-reset; de bucket vult zich continu aan). Wanneer de bucket vol is, is dit de huidige tijd.

Bij 429 rate_limit_exceeded-antwoorden wordt ook Retry-After ingesteld, uitgedrukt in hele seconden totdat er minstens één token vrijkomt.

Fouten vóór authenticatie (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) en 403 ip_not_whitelisted bevatten geen X-RateLimit-*-headers - de limiter wordt pas geraadpleegd nadat de authenticatie- en IP-controles zijn geslaagd.

Foutindeling

Zelfde envelope als Bot Talk API:

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

Validatiefouten gebruiken code: "invalid_parameter" en plaatsen het pad van het mislukte veld vóór het bericht, zodat het problematische gedeelte eenvoudig te herkennen is:

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

Ongeldige waarden voor enum- / closed-set-velden (bijv. chatMemory.clientSummaryPromptType = "BOGUS") bevatten het veldpad, de afgewezen waarde en de lijst met toegestane waarden:

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

Gerelateerd

Zie voor gesprekseindpunten en SSE-streaming Bot Talk API.