Management API

Management API-overzicht

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 opvragen waarvan je eigenaar bent met GET /v1/management/bots/{bot_id}
• een specifieke bot bijwerken met PATCH /v1/management/bots/{bot_id}
• het abonnementsverbruik uitlezen met GET /v1/usage

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

Base 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 optioneel een IP-whitelist en snelheidslimiet (rate limit) in en sla op.
3. Selecteer alleen de permissies die jouw integratie nodig heeft en kopieer de volledige sleutel uit de succesmodal. De platte tekst wordt slechts één keer getoond.
4. Bewaar deze op jouw server, niet in browsercode of in een openbare repository. Voer een alleen-lezen verzoek uit zoals GET /v1/usage met de permissie usage om de toegang te verifiëren.
5. Trek ongebruikte of gecompromitteerde sleutels in via de pagina Management API.

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 10, geleidelijke aanvulling met ~1 token elke 6 seconden). Dit kan bij het aanmaken naar beneden worden bijgesteld - stel een lagere rateLimitPerMinute in om het maximum te verlagen; de aanvulsnelheid schaalt evenredig mee.

Permissies

Elke Management-sleutel bevat een willekeurige subset van de onderstaande drie permissies. Er moet 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 niet over de vereiste permissie beschikt, 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

Vorm van de body: geneste secties die de tabbladen van het beheerpaneel weerspiegelen

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

• role - botpersona, ruwe prompt, antwoordlengte, taal, website-/bedrijfscontext (tabblad Role & Behavior)
• conversation - welkomstbericht, vraagverfijning, gesprekscontinuïteit, beoordelingsschakelaar + tooltips, inhoud van voorgestelde vragen + dynamische vervolgvragen (tabblad Chat Conversation)
• chatMemory - chatgeheugenschakelaar, samenvattingsprompts, contexttoewijzing (tabblad Summaries & Memory)
• appearance - kleuren, teksten, afmetingen, aangepaste CSS, welkomstscherm, vormgeving van voorgestelde vragen, gedrag bij automatisch openen, simulatie van menselijk typen, voettekst-markdown (tabblad Appearance)
• humanSupport - contactformulier voor menselijke ondersteuning (tabblad Human Contact Form)
• leadCollection - lead capture-formulier (tabblad Lead Collection)
• liveChat - overdracht naar Live Chat (tabblad Live Chat)
• consent - alle vier de schakelaars voor toestemming met het privacybeleid plus de tekst van het toestemmingsscherm (tabblad Consent & Privacy)
• whiteLabel - logo verbergen, link naar aangepast logo, hosting op aangepast domein (tabblad Whitelabel)
• security - toegestane domeinen, spamfilter, snelheidslimieten voor gesprekken (tabblad Security)
• voice - spraakinvoer en spraakgesprekken: model, stem, talen, prompt, maximale tijdsduur (tabblad Voice Conversation)
• multilingual - meertalige modus, basistaal, aangeboden talen, verwerking van kennistalen (tabblad Languages)
• advanced - LLM-model, temperatuur, contextgrootte, limiet voor botberichten, interne locale, Offer Cards (tabblad Model & Advanced)

Van de schrijfbare instellingen bevindt alleen name zich op het hoogste niveau, omdat dit de bot identificeert en niet bij één specifiek tabblad hoort.

De zijbalk Bot Settings heeft momenteel 16 subtabbladen, waarvan er 13 overeenkomen met de bovenstaande secties. De drie subtabbladen zonder bijbehorende sectie zijn Flow, Actions en Forms - deze vallen alle drie onder "Buiten het bereik van de API" hieronder. De 13 die wel 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 hebben dezelfde opbouw. Het antwoord bevat twee extra onderdelen:

• 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 zojuist gegenereerde Bot Talk API-sleutel voor de nieuwe bot.

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

• appearance.avatarUrl - volledig gekwalificeerde openbare URL van de bot-avatarafbeelding (bijv. https://api.chatlab.com/aichat/content/avatar_xyz.png). Voer een rechtstreekse GET uit om de bytes te downloaden. Upload een nieuw bestand via het multipart-onderdeel avatar om dit te wijzigen (zie PATCH).
• whiteLabel.whitelabelLogoUrl - volledig gekwalificeerde openbare URL van het white-label headerlogo. Hetzelfde patroon als bij avatarUrl. Upload een nieuw bestand via het multipart-onderdeel whitelabel_logo om dit te wijzigen (zie PATCH).

Beide URL's gebruiken het schema + de host + het contextpad van het huidige verzoek, dus op een aangepast white-labeldomein verwijzen ze naar dat domein (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 specifieke veld over te slaan. Een null op veldniveau wist nooit een opgeslagen waarde - het betekent alleen "niet wijzigen".

Rol en promptconstructie

De systeemprompt die het LLM daadwerkelijk ontvangt, wordt op een van de twee volgende manieren opgebouwd, afhankelijk van role.role. Als je weet op welke tak je zit, weet je welke velden ertoe doen en welke worden opgeslagen maar genegeerd.

Tak 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 simpelweg niet gebruikt). Het sjabloon bevat:

• role.role - rollabel (bijv. "Customer Support") en rolspecifieke instructies die automatisch worden toegevoegd
• name - botnaam, 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 vertaald naar "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 ingevuld, toegevoegd als "for the users of the website {url}"
• role.companyDescription - optioneel; indien ingevuld, voorafgaand toegevoegd als een extra alinea vóór de rolinstructies

Dit is de aanbevolen tak voor de meeste bots - je krijgt direct op de rol afgestemd gedrag en veiligheidskaders zonder extra configuratie.

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

De backend gebruikt role.rawPrompt als de rolprompt en voegt de vaste richtlijnen voor antwoordlengte van het platform toe. Dit staat los van role.responseLength: de optionele instelling Concise/Normal/Detailed wordt niet toegepast bij een CUSTOM-rol. Evenzo worden language, websiteAddress en companyDescription wel opgeslagen, maar niet in deze rolprompt geïnjecteerd. Neem de gewenste taal, de streeflengte van het antwoord of de bedrijfscontext zelf op in rawPrompt. Er kunnen ook aanvullende runtime-instructies en opgehaalde context worden meegeleverd, waardoor rawPrompt niet de volledige invoer van het model vormt. De tooninstructies van de vooraf gedefinieerde rol worden niet toegevoegd, maar de keuze voor CUSTOM verwijdert niet alle platforminstructies.

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

Enum- / gesloten-setvelden

Enum- en beperkte velden weigeren ongeldige waarden met 400 invalid_parameter. Andere velden zijn gewone strings, zelfs waar de gebruikersinterface een vaste lijst aanbiedt. Gebruik de gedocumenteerde schrijfwijze en valideer jouw payload in plaats van aan te nemen dat elke niet-ondersteunde string automatisch wordt geweigerd.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - volledige Engelse taalnaam uit het dropdownmenu van 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; tweeletterige ISO-codes (en, pl) en andere waarden buiten de lijst worden dus niet afgewezen door de API, maar leiden tot een verminkte instructie zoals "Output in en, unless...". Standaard ingesteld op Auto Detect wanneer dit wordt weggelaten bij het aanmaken.
• advanced.model - zie "AI-tekstmodellen" hieronder. Dit is een string, geen gevalideerde enum in het request-schema; gebruik een ondersteunde waarde, geen willekeurige modelnaam.
• advanced.chatContextSize - gebruik 8000, 16000 of 32000, overeenkomstig de beheerinterface. Waarden boven het maximum van het account worden stilzwijgend afgekapt; de DTO dwingt deze set van drie waarden niet af.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - booleaanse schakelaar. true dwingt 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 vormen, bereiken of bijzonderheden 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 de beheerinterface. Waarden buiten dit bereik worden geweigerd met 400 invalid_parameter.

• chatMemory.summariesToKnowledgeRatio - geheel getal als percentage, 10-90; de beheerinterface gebruikt stappen van 10, maar de API accepteert gehele getallen binnen het hele bereik. Standaard 50. Wanneer geheugen is ingeschakeld en de context groter is dan 8k, verdeelt dit het budget voor kennis en geheugen na aftrek van de reservering voor de prompt/recente gesprekken, dus niet de volledige modelcontext. Bij 8k wordt met deze instelling geen samenvattingsbudget toegewezen.

• liveChat.schedule - JSON gecodeerd als string, geen genest JSON-object over de lijn. De server slaat de ruwe string letterlijk op; de beheerinterface parseert deze aan de clientzijde bij het renderen van de roosterbewerker. Eenmaal geparseerd heeft de string de vorm van één item per weekdag plus een timezone-sleutel:

  • elke weekdagsleutel (monday-sunday) verwijst naar {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ëscapete 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 krijgt de bezoeker liveChat.outOfHoursMessage te zien en wordt de overdracht naar live chat onderdrukt. De 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 een string geaccepteerd en leiden later tot een weergavefout wanneer een beheerder de bot in het beheerpaneel opent. Valideer de structuur aan jouw kant voordat je deze verzendt.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - korte labels die worden getoond op de 👍 / 👎 beoordelingsknoppen voor gesprekken wanneer conversation.conversationRatingEnabled=true. De standaardtekst is "I like the response" / "I don't like the response". Zichtbaar voor eindgebruikers.

• whiteLabel.hideRoboAssistLogo - White Label-functionaliteit, afhankelijk van jouw accountlimieten. Verbergt de voettekstregel "Powered by ChatLab". Als jouw account geen whitelabeling bevat, wordt de waarde wel opgeslagen maar genegeerd, en wordt de voettekst altijd weergegeven.

• whiteLabel.whitelabelLogoLink - White Label-functionaliteit, afhankelijk van jouw accountlimieten. De doel-URL bij het klikken op 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") staat niet in de toegestane lijst. 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 spreektaal van de bot in gesprekken).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - gehele getallen (verzend als JSON-getallen, bijv. 30, niet "30"). Stel de berichtlimiet in op 0 om deze sessiegebonden limiet uit te schakelen. Geef bij het inschakelen een positieve tijdsduur op. De backend handhaaft N berichten per sessie per tijdsduur in seconden voordat security.talkMessagesRateLimitHitMessage aan de bezoeker wordt getoond.

• advanced.botMessagesLimit - geheel getal (JSON-getal, bijv. 1000). 0 betekent geen aanvullend maximum per bot, waarbij het tegoedbudget van het account nog steeds van toepassing is; anders moet het een veelvoud van 1000 zijn (1000, 2000, 10000, ...). Waarden zoals 100 of 1500 worden geweigerd met 400 invalid_parameter. Dit is een maandelijks limiet aan bot-credits, geen aantal berichten per gesprek. De mapper kapt deze waarde niet af op basis van het accountbudget; het budget van het account begrenst nog steeds het daadwerkelijke verbruik.

AI-tekstmodellen (advanced.model)

Gebruik de exacte model-ID die wordt geretourneerd in advanced.model bij het uitlezen van een bot die is geconfigureerd met jouw gewenste model in Settings > Model & Advanced (Instellingen > Model en geavanceerd). De huidige standaardwaarde bij het aanmaken is 5.6-LUNA. Id's zijn hoofdlettergevoelig en verschillen van de weergavenamen; 5.6-LUNA wordt bijvoorbeeld weergegeven als GPT 5.6-luna.

Het modelaanbod verandert in de loop van de tijd. Ga er niet van uit dat een willekeurige string of een openbare model-ID van een provider wordt ondersteund puur omdat het request-schema een string accepteert. Lees de opgeslagen configuratie terug en test de resulterende chatbot voordat je deze in gebruik neemt.

Veldreferentie (volledig request-schema)

De ondersteunde secties en velden, met hun types en belangrijke restricties. PATCH-semantiek: elk weggelaten veld (of verzonden als null) laat de opgeslagen waarde ongewijzigd. Dezelfde structuur wordt gebruikt voor de respons (minus binaire multipart-inhoud; plus het alleen-lezen meta-blok bij elke respons en apiKey alleen bij de create-respons).

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 uitsluitend in de respons:

• meta: { id, createdAt, updatedAt } - alleen-lezen.
• apiKey - string, alleen aanwezig in de respons 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 het prompt-sjabloon (zie "Role and prompt construction")
language	string	volledige Engelse taalnaam (English, Polish, ...) of Auto Detect	Primaire taal die aan het prompt-sjabloon 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 aan de bezoeker wordt getoond bij het openen
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-knoppen voor gespreksbeoordeling
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
positiveRatingMessage	string		Bericht dat wordt getoond na positieve feedback
negativeRatingMessage	string		Bericht dat wordt getoond na negatieve feedback
hideSuggestedQuestionsAfterFirstUse	boolean		Verberg statische suggesties na gebruik
dynamicFollowupsAutoIcons	boolean		Indien true, kiest de AI automatisch emoji-pictogrammen voor de dynamische vervolgsuggesties

§ 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 de cliënt over meerdere gesprekken heen
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Standaard versus aangepaste cliëntprofielprompt
summariesToKnowledgeRatio	int	10-90 (UI-stap 10)	% van het beschikbare kennis-/geheugenbudget dat wordt toegewezen aan samenvattingen bij contexten boven 8k

§ appearance

Veld	Type	Restrictie	Beschrijving
launcherLabelLine1	string	max 60	Eerste regel van de launcher-tekst
launcherLabelLine2	string	max 60	Tweede regel van de launcher-tekst
launcherTextColor	string		Tekstkleur van de launcher
launcherDismissEnabled	boolean		Sluiten van de launcher toestaan
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Lettertypefamilie van de widget
chatDrawerEnabled	boolean		Drawer-weergave inschakelen
launcherColor	string (hex)		Achtergrondkleur van de launcher (chatpictogram)
headerColor	string (hex)		Achtergrondkleur van de chat-header
titleColor	string (hex)		Titelkleur van de chat-header
subtitleColor	string (hex)		Ondertitelkleur van de chat-header
clientMessageBubbleColor	string (hex)		Tekstballonkleur van het bezoekersbericht
clientMessageTextColor	string (hex)		Tekstkleur van het bezoekersbericht
responseMessageBubbleColor	string (hex)		Tekstballonkleur van het botantwoord
responseMessageTextColor	string (hex)		Tekstkleur van het botantwoord
chatSubheader	string		Subtitel die onder de chattitel wordt getoond
senderPlaceholder	string		Placeholdertekst 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 de iframe van de widget wordt geïnjecteerd
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Hoe links binnen botberichten worden geopend
minimizedDisplayMode	string (enum)	∈ {icon, minified, pill}	Geminimaliseerde weergave: launcher-pictogram, compacte verzendbalk of pilvorm
chatDesktopWidthPx	int		Widgetbreedte op desktop
chatDesktopHeightPx	int		Widgethoogte op desktop
chatMobileSizePercent	int		Widgetgrootte op mobiel als % van de viewport
messageFontSize	int		Lettergrootte van de berichttekst (px)
showChatbotBubblesDesktop	boolean		Zwevende aandachttrekkers (tease bubbles) tonen op desktop
showChatbotBubblesMobile	boolean		Zwevende aandachttrekkers (tease bubbles) tonen op mobiel
chatbotBubblesDelaySeconds	int		Vertraging voordat de aandachttrekkers verschijnen (seconden)
launcherIconFullSize	boolean		Aangepast launcher-pictogram beeldvullend weergeven in plaats van met marge (inset)
welcomeScreenEnabled	boolean		Welcome Screen (welkomstscherm) tonen in plaats van direct naar de chat te gaan
welcomeScreenQuestionsLabel	string		Label boven de voorgestelde vragen op het welkomstscherm
welcomeScreenHideHumanContactForm	boolean		Verberg de contactformulieractie voor menselijke ondersteuning in de header zolang het Welcome Screen wordt getoond. Deze verschijnt weer na het eerste bericht van de bezoeker. Voor bots die vóór 2026-09-02 zijn aangemaakt, staat dit standaard op true
welcomeScreenHideLiveChat	boolean		Verberg de Live Chat-actie in de header zolang het Welcome Screen wordt getoond. Deze verschijnt weer na het eerste bericht van de bezoeker. Voor bots die vóór 2026-09-02 zijn aangemaakt, staat dit standaard op true
headerActionsLayout	string	ICONS of DROPDOWN	Hoe Live Chat en het contactformulier voor menselijke ondersteuning worden aangeboden in de chat-header: ICONS (elk een apart pictogram) of DROPDOWN (gegroepeerd in het headermenu). Voor bots die vóór 2026-09-02 zijn aangemaakt, staat dit standaard op ICONS
stackSuggestedQuestions	boolean		Voorgestelde vragen verticaal stapelen (in plaats van naast elkaar)
suggestedQuestionsFontSize	int		Lettergrootte van de voorgestelde vraag-chips (px)
suggestedQuestionsTextColor	string (hex)		Tekstkleur van de voorgestelde vraag-chips
suggestedQuestionsBackgroundColor	string (hex)		Achtergrondkleur van de voorgestelde vraag-chips
autoOpenChat	boolean		De chat automatisch openen op desktop
autoOpenChatOnMobiles	boolean		De chat automatisch openen op mobiel
autoOpenChatDelay	boolean		Een vertraging gebruiken vóór het automatisch openen
autoOpenChatDelaySeconds	int		Vertraging voor automatisch openen (seconden)
simulateHumanTyping	boolean		Botantwoord opdelen in tekstballonnen met type-animatie
simulateHumanTypingDelay	int	0-200	Vertraging tussen tekstballonberichten (seconden)
footerMarkdown	string	max 255	Aangepaste voettekst-markdown die onder de chat wordt getoond
avatarUrl	string	alleen-lezen	Volledige publieke URL van de avatar; upload via het multipart avatar-onderdeel om deze te wijzigen

Multipart bij POST/PATCH: avatar (bestandsonderdeel). GET / response-bodies laten de bestandsinhoud weg - alleen de URL wordt overgedragen.

§ humanSupport

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor de Human Support-flow
email	string	verplicht (create-strict) wanneer enabled=true	Adres dat e-mails voor menselijke ondersteuning ontvangt
dialogMessage	string		Aanmoedigingsbericht dat boven het formulier wordt getoond
thankYouMessage	string		Bevestiging die wordt getoond na verzending
emailMessageSubjectTemplate	string		Onderwerpsjabloon voor de e-mail die naar de agent wordt verzonden
emailMessageContentTemplate	string		Inhoudssjabloon voor de e-mail die naar de agent wordt verzonden
emailPlaceholder	string		Placeholder op het e-mailinvoerveld
messagePlaceholder	string		Placeholder op het tekstvak voor het bericht
emailWithConversationContent	boolean		Indien true, voeg het transcript van het gesprek toe aan de e-mailinhoud
customFormId	long	id van een bestaand aangepast formulier	Vervang het ingebouwde contactformulier door een aangepast formulier. Bij het aanmaken gebruikt weglating het ingebouwde formulier; bij PATCH laat null de huidige selectie ongewijzigd
customFormMapping	string	JSON-geëncodeerde string	Koppelt velden van het aangepaste formulier aan de e-mailvelden voor menselijke ondersteuning

requirePolicyAccept bevindt zich op consent.humanSupportRequirePolicyAccept, niet hier.

§ leadCollection

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor het 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 dat de bezoeker aanmoedigt om gegevens achter te laten
thankYouMessage	string	verplicht (create-strict) wanneer enabled=true	Bevestiging die wordt getoond na verzending
requireBeforeNewConversation	boolean		Indien true, moet het formulier worden ingediend 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 e-mailadres van het account)
emailWithConversationContent	boolean		Indien true, voeg het transcript van het gesprek toe aan de melding

| customFormId | long | id van een bestaand aangepast formulier | Vervang het ingebouwde leadformulier door een aangepast formulier. Bij het aanmaken gebruikt weglating het ingebouwde formulier; bij PATCH laat null de huidige selectie ongewijzigd | | customFormMapping | string | JSON-geëncodeerde string | Koppelt velden van het aangepaste formulier aan naam / e-mail / telefoon |

Veldoverstijgende create-strict-regel: enabled=true vereist ten minste één van emailEnabled of phoneEnabled. requirePolicyAccept bevindt zich op consent.leadCollectionRequirePolicyAccept, niet hier.

§ liveChat

Veld	Type	Restrictie	Beschrijving
enabled	boolean		Schakelaar voor de Live Chat-functie
infoMessage	string		Toelichtend bericht voorafgaand aan de 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 Live Chat-formulier
emailLabel	string		Label op het e-mailinvoerveld in het voorbereidende Live Chat-formulier
schedule	string	JSON-geëncodeerde string (weekdagschakelaars + from/to + timezone)	Bedrijfstijden van de live chat - zie "Structured fields and ranges" voor de exacte structuur
outOfHoursMessage	string		Bericht dat wordt getoond wanneer we volgens het rooster niet beschikbaar zijn
closeModalMessage	string		Titel van de modal "live chat sluiten?"
closeModalConfirmLabel	string		Label van de bevestigingsknop op de sluitingsmodal
closeModalCancelLabel	string		Label van de annuleringsknop op de sluitingsmodal
closeModalTooltipText	string		Tooltip op de knop om de chat te sluiten
operatorHasJoinedLabel	string		Label dat wordt getoond wanneer een medewerker deelneemt
operatorDidNotJoinInTimeLabel	string		Label dat wordt getoond wanneer er niet op tijd een medewerker deelneemt binnen de time-out
waitingForOperatorToJoinLabel	string		Label dat wordt getoond tijdens het wachten op een medewerker
waitingForOperatorSeconds	int		Time-out voor een medewerker om op te nemen (seconden)
redirectToHumanSupportForm	boolean		Indien true, val terug op het Human Support-formulier wanneer er geen medewerker opneemt
requireAdminOnline	boolean		Vereis een beschikbare medewerker volgens de aanwezigheidsinstellingen
presenceMode	string		Aanwezigheidsmodus; gebruik de waarde van een bot die in de UI is geconfigureerd
hideHumanSupportWhenLiveChatAvailable	boolean		Verberg het contactformulier wanneer live chat beschikbaar is
missedEmailEnabled	boolean	standaard true	Stuur de boteigenaar een e-mail wanneer een live-chatverzoek onbeantwoord is gebleven. Niet ingesteld bij verouderde bots, wat wordt gelezen als ingeschakeld

requirePolicyAccept bevindt zich op consent.liveChatRequirePolicyAccept, niet hier.

§ consent

Veld	Type	Restrictie	Beschrijving
newConversationRequirePolicyAccept	boolean		Toestemming voor het privacybeleid vereisen voordat een nieuw gesprek wordt gestart
humanSupportRequirePolicyAccept	boolean		Toestemming voor het privacybeleid vereisen voordat het formulier voor menselijke ondersteuning wordt ingediend
leadCollectionRequirePolicyAccept	boolean		Toestemming voor het privacybeleid vereisen voordat het leadformulier wordt ingediend
liveChatRequirePolicyAccept	boolean		Toestemming voor het privacybeleid vereisen voordat een live-chatsessie wordt gestart
newConversationConsentDescription	string		Introductietekst voor het toestemmingsscherm bij het starten van een gesprek
privacyPolicyConsentCheckboxLabel	string		Label naast het selectievakje voor toestemming (bevat meestal een link naar het privacybeleid)

§ whiteLabel

Veld	Type	Restrictie	Beschrijving
hideRoboAssistLogo	boolean	White Label-functionaliteit; afhankelijk van accountlimieten	Het standaard ChatLab-logo in de voettekst verbergen
whitelabelLogoLink	string	White Label-functionaliteit; afhankelijk van accountlimieten	URL waar het aangepaste voettekstlogo naar verwijst
assignToCustomDomain	boolean	gekoppeld aan de CUSTOM_DOMAIN-functie	De chat hosten op het geconfigureerde aangepaste domein
whitelabelLogoUrl	string	alleen-lezen	Volledige publieke URL van het White Label-logo; upload via het multipart whitelabel_logo-onderdeel om deze te wijzigen

Multipart bij POST/PATCH: whitelabel_logo (bestandsonderdeel). GET / response-bodies laten de bestandsinhoud weg - alleen de URL wordt overgedragen.

§ security

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

§ voice

Veld	Type	Restrictie	Beschrijving
inputEnabled	boolean		De bezoeker toestaan berichten te dicteren (spraak-naar-tekst)
conversationEnabled	boolean	vereist de voice-functie binnen het abonnement	Volledige spraakgesprekken inschakelen
voiceId	string	providerspecifieke voice-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 beurtwisseling (turn-taking)
audioPrompt	string		Extra systeemprompt die alleen wordt gebruikt voor spraakbeurten
welcomeMessage	string		Gesproken openingszin
language	string	taalcode	Primaire spraaktaal
additionalLanguages	string	door komma's gescheiden taalcodes	Extra talen die de voice-agent accepteert
maxDurationSeconds	int		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 FIXED_LIST	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	NONE, MAIN, of DYNAMIC	Hoe wordt omgegaan met kennis in andere talen
knowledgeLanguageFallback	string	taalcode	Taal die wordt gebruikt wanneer er geen overeenkomst wordt gevonden

§ advanced

Veld	Type	Restrictie	Beschrijving
model	string	afhankelijk van accountlimieten; zie "AI text models" hierboven	LLM-identificatie (bijv. 5.6-LUNA)
temperature	decimal	0.0-1.0	Bemonsteringstemperatuur (komt overeen met de schuifregelaar in de UI)
chatContextSize	int	∈ {8000, 16000, 32000}; stilzwijgend begrensd tot je accountlimiet	Geconfigureerd contextbudget, inclusief instructies, geschiedenis en kennis
botMessagesLimit	long	0 of veelvoud van 1000 (bijv. 1000, 2000, 10000)	Maandelijks tegoedlimiet voor botberichten (0 = geen extra botlimiet; accountbudget blijft van toepassing)
internalLocale	string	locale-code in de vorm ll_CC	Locale voor widgetlabels van de interface (verschilt van role.language)
productsViewEnabled	boolean		Indien true, toon de e-commerce Offer Cards binnen de chat
includeProductsInKnowledgeBase	boolean		Indien true, indexeer de productcatalogus als onderdeel van de kennisbank

Buiten het bereik van de API

De beheer-UI bevat enkele onderdelen die opzettelijk niet worden blootgesteld in deze versie van de Management API:

• Trainen en verwijderen - deze eindpunten tonen niet alle bots, beheren geen trainingsdatasets en verwijderen geen bots. Gebruik de app voor deze workflows.
• Flow-tabblad - de visuele Conversation Flow editor (fasen en overgangen). Niet beschikbaar via de Management API.
• Actions-tabblad - beheerde e-commerce- / boekingsintegraties, AI Search en aangepaste API-functies. Tool calling heeft nooit deel uitgemaakt van de Management API.
• De bouwer van 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 open-/sluit-pictogrammen voor de chat - customLauncherIconVisible, openChatIcon, closeChatIcon. De API biedt alleen toegang tot de belangrijkste avatar- en whitelabel_logo-multipartonderdelen.
• IP- en landenlijsten - de invoergegevens zelf zijn uitsluitend toegankelijk voor beheerders. Alleen de interpretatiemodus is beschikbaar via security.countryFilterMode.

Endpoints

POST /v1/management/bots

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

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

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

Modus B - multipart/form-data (gebruik dit wanneer je bestanden in hetzelfde verzoek uploadt):

• Content-Type: multipart/form-data; boundary=...
• data JSON-deel (vereist, Content-Type: application/json) - botconfiguratie in de hierboven beschreven geneste structuur
• avatar bestandsdeel (optioneel) - bot-avatarafbeelding
• whitelabel_logo bestandsdeel (optioneel) - white-label-logo (is alleen van toepassing als je account white-labelling bevat)

Alleen name is verplicht in de JSON; voor elk ander veld wordt teruggevallen op dezelfde standaardwaarde die de wizard in de beheerinterface zou instellen.

Voorbeeld request body

Dit is de maximale data-JSON - elk onderdeel is ingevuld. Stuur alleen de onderdelen mee 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Validatieregels met hun eigen foutmeldingen:

• name - vereist, 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 minimaal één van leadCollection.emailEnabled of leadCollection.phoneEnabled de waarde true heeft; welk kanaal ook actief is vereist tevens een label, plus leaveDetailsMessage en thankYouMessage
• advanced.chatContextSize wordt begrensd tot de maximale contextgrootte die door het account wordt ondersteund. Ga er niet van uit dat andere numerieke velden automatisch worden begrensd.

Velden waarvan de waarde op de server null is, worden weggelaten uit de JSON body - over het netwerk worden alleen velden met een waarde anders dan null verzonden.

Voorbeeld response body (201)

Zelfde 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.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"
}

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

De Location-responsheader 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 die van jou is.

Curl-voorbeeld

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

Voorbeeld response body (200)

Zelfde structuur als het POST-antwoord, exclusief 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 getoond als volledige 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-deel bij een PATCH. Deze URL-velden worden genegeerd als ze in een request body worden meegestuurd.

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

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, waardoor klonen een proces van drie stappen is: haal de bron op met GET, verwijder de door de server beheerde identiteitsvelden en verstuur het resultaat met POST.

1. Haal de bronbot op met GET.

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 beheerd door de server en is alleen-lezen - het laten staan in de POST body kan geen kwaad (de server negeert het), maar door het te verwijderen maak je de intentie expliciet en blijft de payload schoon. Pas eventueel 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. Verstuur de gestripte body met POST om de kloon aan te maken. Zie de POST /v1/management/bots-referentie hierboven voor de volledige bodystructuur 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 het meta.id van de nieuwe bot plus een nieuw aangemaakte apiKey (de Bot Talk-sleutel voor de kloon). De platte tekst van de apiKey wordt alleen bij deze create-respons geretourneerd - kopieer deze voordat je de response body weggooit; deze kan later niet meer worden opgehaald.

Hiermee worden ondersteunde instellingen gekopieerd, geen volledig getrainde chatbot. Trainingsinhoud, gespreksgeschiedenis, integraties/acties, Flow en formulierdefinities worden niet gekloond door deze eindpunten. Configureer deze afzonderlijk in de app.

Aanvullende aandachtspunten:

• 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 bestanden van de bron-URL's en upload ze als multipart avatar / whitelabel_logo-onderdelen - hetzij bij de create-POST (Modus B) of bij 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 tabblad API 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 aanwezig zijn in de JSON worden gewijzigd; alles wat wordt weggelaten (of als null wordt verzonden) blijft ongewijzigd. Er gelden regels voor gedeeltelijke updates 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 (gebruiken bij het uploaden van bestanden):

• data JSON-onderdeel (optioneel) - de patch. Verstuur dit alleen 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 jouw account white-labelling bevat)

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

Voorbeeld request body (meerdere secties)

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

{
  "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 exact de sleutels te verzenden die je wilt wijzigen - al het andere 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)

Dezelfde 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 patch Volledige request body (meerdere secties) 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": "your-plan-id",
  "messages": {"used": 4123, "limit": 11000, "remaining": 6877},
  "bots": {"used": 3, "limit": 5, "remaining": 2}
}

• subscriptionType is een id in kleine letters van het huidige plan van het account (your-plan-id is een illustratieve tijdelijke aanduiding). Plannen zijn afkomstig uit een dynamische catalogus, waardoor de exacte set identificaties in de loop van de tijd kan 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 kalendermaand, die worden gereset op de eerste dag van de maand, niet op de verlengingsdag van het abonnement. Ze zijn gewogen op basis van credits, geen ruwe aantallen antwoorden.
• bots.used / limit / remaining tellen bots in eigendom, inclusief gepauzeerde bots, mee voor de totale botlimiet van jouw account.

Headers voor rate limits

Responses die de rate-limit-fase bereiken (d.w.z. authenticatie en IP-whitelist 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 jouw geconfigureerde rateLimitPerMinute als deze lager is).
• X-RateLimit-Remaining - resterende tokens in de bucket direct na deze aanroep.
• X-RateLimit-Reset - Unix epoch-seconden waarop de volgende token beschikbaar komt (geen volledige bucket-reset; de bucket wordt continu aangevuld). Wanneer de bucket vol is, is dit de huidige tijd.

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

Pre-auth-fouten (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

Dezelfde envelope als de 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 mislukkende veldpad 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- / gesloten-set-velden (bijv. chatMemory.clientSummaryPromptType = "BOGUS") bevatten het veldpad, de geweigerde 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 Bot Talk API voor gesprekseindpunten en SSE-streaming.