Management API

Aperçu de la Management API

La Management API est conçue pour les tâches de back-office qui n'impliquent pas l'envoi de messages de discussion :

• créer un bot par programmation avec POST /v1/management/bots
• consulter un bot spécifique vous appartenant avec GET /v1/management/bots/{bot_id}
• mettre à jour un bot spécifique avec PATCH /v1/management/bots/{bot_id}
• consulter la consommation de l'abonnement avec GET /v1/usage

Les clés Management sont associées à votre compte et non à un bot en particulier. Elles sont délibérément séparées des clés Bot Talk afin qu'une clé de chat compromise ne puisse pas modifier vos bots ni accéder à vos données de facturation.

URL de base

https://api.chatlab.com/aichat

Tous les endpoints de cet article sont relatifs à cette URL de base.

Pour commencer

1. Ouvrez l'application d'administration et allez dans Account Settings > Management API (Paramètres du compte > Management API).
2. Cliquez sur Create Management Key (Créer une clé Management), donnez-lui un nom, définissez éventuellement une liste blanche d'adresses IP ainsi qu'une limite de débit, puis validez.
3. Copiez la clé complète à partir de la modale de confirmation. La valeur en texte brut n'est affichée qu'une seule fois.

Une clé ressemble à mk_abcdefghijklmnopqrstuvwxyz012345. Le préfixe mk_ la distingue des clés Bot Talk (ck_).

Authentification

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

L'envoi d'une clé mk_ vers /v1/chat (ou tout autre endpoint Bot Talk) renvoie 403 key_type_not_allowed. L'envoi d'une clé ck_ vers /v1/management/* renvoie la même erreur.

Limites

• 5 clés Management API actives maximum par utilisateur
• 10 requêtes par minute maximum par clé (token bucket, capacité de 10, recharge progressive d'environ 1 jeton toutes les 6 secondes). Configurable à la baisse lors de la création - définissez un paramètre rateLimitPerMinute inférieur et le plafond baissera, la vitesse de recharge s'ajustant en conséquence.

Permissions

Chaque clé Management dispose d'un sous-ensemble des trois permissions ci-dessous. Au moins une doit être sélectionnée au moment de la création ; sinon, la requête est rejetée avec l'erreur 400 invalid_request_error. L'appel d'un endpoint avec une clé dépourvue de la permission requise renvoie 403 insufficient_permissions.

• bot_read - requis pour GET /v1/management/bots/{bot_id}
• bot_management - requis pour POST /v1/management/bots et PATCH /v1/management/bots/{bot_id}
• usage - requis pour GET /v1/usage

Structure du corps : des sections imbriquées qui reflètent les onglets de l'interface d'administration

POST et PATCH acceptent un corps JSON divisé en 13 sections. Chaque section correspond à un sous-onglet de la barre latérale Bot Settings (Paramètres du bot) dans l'application d'administration, de sorte que les clés JSON et les onglets visibles concordent : si vous modifiez consent.humanSupportRequirePolicyAccept via l'API, vous verrez le même interrupteur basculer dans l'onglet Consent & Privacy (Consentement et confidentialité) de l'application d'administration.

• role - persona du bot, prompt brut, longueur de réponse, langue, contexte du site web / de l'entreprise (onglet Role & Behavior [Rôle et comportement])
• conversation - message de bienvenue, reformulation de requête, continuité de conversation, bouton d'évaluation + infobulles, contenu des suggestions de questions + relances dynamiques (onglet Chat Conversation [Conversation du chat])
• chatMemory - activation de la mémoire du chat, prompts de synthèse, allocation du contexte (onglet Summaries & Memory [Résumés et mémoire])
• appearance - couleurs, textes, dimensions, CSS personnalisé, écran de bienvenue, style des suggestions de questions, comportement d'ouverture automatique, simulation de frappe humaine, markdown du pied de page (onglet Appearance [Apparence])
• humanSupport - formulaire de contact humain (onglet Human Contact Form [Formulaire de contact humain])
• leadCollection - formulaire de capture de leads (onglet Lead Collection [Collecte de leads])
• liveChat - transfert vers le chat en direct (onglet Live Chat)
• consent - les quatre interrupteurs de consentement à la politique de confidentialité ainsi que le texte de l'écran de consentement (onglet Consent & Privacy [Consentement et confidentialité])
• whiteLabel - masquage du logo, lien de logo personnalisé, hébergement sur domaine personnalisé (onglet Whitelabel [Marque blanche])
• security - domaines autorisés, filtre anti-spam, limites de débit de conversation (onglet Security [Sécurité])
• voice - saisie vocale et conversations vocales : modèle, voix, langues, prompt, durée maximale (onglet Voice Conversation [Conversation vocale])
• multilingual - mode multilingue, langue de base, langues proposées, gestion de la langue des connaissances (onglet Languages [Langues])
• advanced - modèle LLM, température, taille de contexte, limite de messages du bot, locale interne, Offer Cards (onglet Model & Advanced [Modèle et options avancées])

Seul le champ name se trouve au niveau racine, car il identifie le bot au lieu d'appartenir à un onglet en particulier.

La barre latérale Bot Settings comprend actuellement 15 sous-onglets, et 13 d'entre eux correspondent aux sections ci-dessus. Les deux sous-onglets qui n'ont aucune section correspondante sont Flow et Actions - tous deux abordés ci-dessous dans la section « Hors périmètre de l'API ». Les 13 onglets qui correspondent sont Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation et Languages.

Le corps de la requête et le corps de la réponse partagent la même structure. La réponse y ajoute deux éléments supplémentaires :

• meta - en lecture seule : identifiant du bot et horodatages. Retirez-le pour transformer une réponse GET en un corps POST valide.
• apiKey - présent uniquement lors de la création - la clé Bot Talk API nouvellement générée pour le nouveau bot.

Deux champs au sein de la structure partagée sont en lecture seule - ils sont renvoyés dans la réponse et ignorés si vous tentez de les envoyer lors d'un POST/PATCH :

• appearance.avatarUrl - URL publique absolue de l'image d'avatar du bot (ex. https://api.chatlab.com/aichat/content/avatar_xyz.png). Effectuez directement un GET dessus pour télécharger les octets. Pour la modifier, importez un nouveau fichier via la partie multipart avatar (voir PATCH).
• whiteLabel.whitelabelLogoUrl - URL publique absolue du logo d'en-tête White Label. Même fonctionnement que pour avatarUrl. Pour le modifier, importez un nouveau fichier via la partie multipart whitelabel_logo (voir PATCH).

Ces deux URL utilisent le protocole + hôte + chemin de contexte de la requête en cours ; ainsi, sur un domaine personnalisé White Label, elles renvoient une racine basée sur ce domaine (ex. https://api.acme.com/aichat/content/...).

Envoyez null pour une section afin de l'ignorer lors d'un PATCH ; envoyez null pour un champ précis au sein d'une section pour ignorer ce champ uniquement. Un null au niveau d'un champ n'efface jamais une valeur enregistrée - il signifie simplement « ne pas toucher ».

Rôle et construction du prompt

Le prompt système que le LLM reçoit réellement est construit de deux façons différentes selon la valeur de role.role. Savoir quelle branche est active vous permet de savoir quels champs sont pris en compte et lesquels sont enregistrés mais ignorés.

Branche A - role.role a pour valeur CUSTOMER_SUPPORT, SALES ou LEAD_COLLECTION_AGENT (génération par modèle prédéfini)

Le backend compose le prompt à partir d'un modèle prédéfini intégré et ignore entièrement role.rawPrompt (la valeur reste enregistrée sur le bot, mais n'est pas utilisée). Le modèle intègre :

• role.role - libellé du rôle (ex. « Support client ») et instructions spécifiques au rôle ajoutées automatiquement
• name - nom du bot, inséré dans la phrase d'introduction
• role.language - "Auto Detect" configure le bot pour qu'il s'adapte à la langue de l'utilisateur ; toute autre valeur (ex. "English", "Polish") devient « Output in {language}, unless user uses another language »
• role.responseLength - correspond à un objectif de nombre de mots : Concise ≈ 50 mots, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - facultatif ; si non vide, ajouté sous la forme « for the users of the website {url} »
• role.companyDescription - facultatif ; si non vide, inséré en tant que paragraphe supplémentaire avant les instructions de rôle

C'est la branche recommandée pour la plupart des bots - vous bénéficiez sans effort d'un comportement ajusté au rôle et de garde-fous de sécurité.

Branche B - role.role a pour valeur CUSTOM (prompt personnalisé fourni par l'appelant)

Le backend utilise role.rawPrompt textuellement comme l'intégralité du prompt système. responseLength, language, websiteAddress et companyDescription sont enregistrés mais ne sont pas injectés dans le prompt - si vous souhaitez que certains d'entre eux influent sur le comportement du bot, vous devez les inclure vous-même dans le texte de votre rawPrompt. Les garde-fous de sécurité et les instructions de ton spécifiques au rôle ne sont pas non plus ajoutés ; vous maîtrisez l'ensemble du prompt.

N'utilisez CUSTOM que lorsque le prompt généré par le modèle prédéfini ne convient pas à votre cas d'usage (par exemple, si vous avez besoin d'un persona très spécifique à votre secteur, de vos propres contraintes de sécurité ou d'un format de sortie non standard).

Champs énumérés / à valeurs restreintes

Plusieurs champs n'acceptent qu'un ensemble fixe de chaînes de caractères. Tout envoi d'une valeur extérieure à cette liste est rejeté avec l'erreur 400 validation_failed et le chemin du champ dans error.param. Les valeurs sont sensibles à la casse.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nom anglais complet de la langue issu de la liste déroulante d'administration, ex. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi, et environ 80 autres. La valeur est enregistrée telle quelle et insérée dans le modèle de prompt ; par conséquent, les codes ISO à deux lettres (en, pl) et autres valeurs hors liste ne sont pas rejetés par l'API mais génèrent une instruction tronquée du type « Output in en, unless... ». Valeur par défaut : Auto Detect si omis à la création.
• advanced.model - voir « Modèles de texte d'IA » ci-dessous ; la liste des choix disponibles dépend des limites de votre compte et toute valeur inaccessible pour votre compte renvoie 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Soumis aux limites de votre compte ; les valeurs plus élevées sont automatiquement plafonnées
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - sélecteur booléen. true oblige l'utilisateur à remplir le formulaire de lead avant de démarrer une conversation ; false laisse l'IA décider du moment où présenter le formulaire (valeur par défaut).

Champs structurés et plages de valeurs

Champs qui ressemblent à de simples chaînes ou à des nombres mais qui possèdent en réalité des formats, des plages de valeurs ou des particularités d'interface d'administration à connaître.

• advanced.temperature - la plage acceptée va de 0.0 à 1.0, correspondant au curseur de l'interface d'administration. Les valeurs en dehors de cette plage sont rejetées avec l'erreur 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - pourcentage entier, de 10 à 90 par pas de 10. Contrôle la part de contexte de discussion réservée aux historiques de résumés du client par rapport au reste (base de connaissances, conversation courante, instructions). Valeur par défaut : 50. Les valeurs hors de la plage 10-90 sont rejetées avec l'erreur 400 validation_failed. S'applique uniquement lorsque chatMemory.enabled=true ET chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON encodé sous forme de chaîne, et non un objet JSON imbriqué dans la requête réseau. Le serveur enregistre la chaîne brute telle quelle ; l'interface d'administration l'analyse côté client lors du rendu de l'éditeur d'horaires. Une fois analysée, la chaîne est structurée avec une entrée par jour de la semaine ainsi qu'une clé timezone :

  • chaque clé de jour (monday-sunday) correspond à {enabled: boolean, from: "H:MM", to: "H:MM"} au format 24 heures
  • timezone est un nom de fuseau horaire IANA (ex. "Europe/Warsaw", "America/New_York")

  Exemple de valeur (notez les guillemets externes et les guillemets internes échappés - il s'agit d'un champ chaîne unique, pas d'un objet imbriqué) :

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

  En dehors des horaires indiqués, le message liveChat.outOfHoursMessage s'affiche pour le visiteur et le basculement vers le chat en direct est désactivé. La validation de la structure interne ne s'exécute que côté client dans l'interface d'administration - un JSON mal formé ou des clés inconnues sont acceptés par l'API comme une simple chaîne et généreront une erreur d'affichage lorsqu'un utilisateur ouvrira plus tard le bot dans l'administration. Validez la structure de votre côté avant l'envoi.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - courts libellés affichés sur les boutons 👍 / 👎 à côté de chaque réponse de l'IA lorsque conversation.conversationRatingEnabled=true. Les textes par défaut sont « J'aime la réponse » / « Je n'aime pas la réponse ». Visibles par les utilisateurs finaux.

• whiteLabel.hideRoboAssistLogo - fonctionnalité White Label, soumise aux limites de votre compte. Masque la ligne « Powered by ChatLab » du pied de page. Si votre compte n'inclut pas le White Label, la valeur est enregistrée mais ignorée et le pied de page s'affiche toujours.

• whiteLabel.whitelabelLogoLink - fonctionnalité White Label, soumise aux limites de votre compte. URL de destination au clic sur le logo personnalisé lorsque hideRoboAssistLogo=true et qu'un fichier de logo personnalisé est importé via la partie multipart whitelabel_logo.

• appearance.simulateHumanTypingDelay - secondes (et non millisecondes), entier de 0 à 200. Pause entre les bulles successives du bot lorsque simulateHumanTyping=true. Valeur par défaut : 5.

• appearance.autoOpenChatDelaySeconds - secondes, entier. Délai avant l'ouverture automatique du widget lorsque autoOpenChat=true et autoOpenChatDelay=true.

• advanced.internalLocale - code région/locale IETF sous la forme ll_CC (tiret bas, et NON ll-CC avec un tiret). Les valeurs acceptées proviennent d'une liste fixe d'environ 95 paramètres régionaux : 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, et bien d'autres. L'envoi d'un code à deux lettres seul ("en") ou BCP-47 ("en-US") ne fait pas partie de la liste autorisée. Valeur par défaut : en_US. Il s'agit de la locale utilisée pour le formatage des dates/nombres dans l'interface du widget, à ne pas confondre avec role.language (la langue de réponse du bot lors de la discussion).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - entiers (à envoyer sous forme de nombres JSON, ex. 30, et non "30"). 0 désactive la limite de débit par IP. Lorsqu'elle n'est pas nulle, le widget applique une limite de N messages par durée en secondes avant d'afficher security.talkMessagesRateLimitHitMessage au visiteur.

• advanced.botMessagesLimit - entier (nombre JSON, ex. 1000). 0 signifie « aucune limite » ; sinon, il doit s'agir d'un multiple de 1000 (1000, 2000, 10000, ...). Les valeurs telles que 100 ou 1500 sont rejetées avec l'erreur 400 validation_failed. La valeur est ensuite automatiquement plafonnée à la limite de votre compte.

Modèles de texte d'IA (advanced.model)

Envoyez la valeur API exacte (colonne de gauche entre accents graves). Le nom affiché dans l'interface d'administration est indiqué entre parenthèses. Les limites de votre compte déterminent le sous-ensemble sélectionnable ; l'envoi d'un modèle non autorisé pour votre compte renvoie 400 invalid_parameter. La valeur par défaut pour les nouveaux bots est 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)

Référence des champs (schéma complet de requête)

Chaque champ transmis sur le réseau, avec son type, ses contraintes et une description synthétique. Sémantique PATCH : tout champ omis (ou envoyé avec la valeur null) conserve sa valeur enregistrée sans la modifier. La même structure est utilisée pour la réponse (hors contenu binaire multipart ; avec en plus le bloc en lecture seule meta sur chaque réponse et apiKey uniquement sur la réponse de création).

Niveau supérieur

Field	Type	Constraint	Description
name	string	max 150, required on create	Nom d'affichage du bot
role	object		Voir § role
conversation	object		Voir § conversation
chatMemory	object		Voir § chatMemory
appearance	object		Voir § appearance
humanSupport	object		Voir § humanSupport
leadCollection	object		Voir § leadCollection
liveChat	object		Voir § liveChat
consent	object		Voir § consent
whiteLabel	object		Voir § whiteLabel
security	object		Voir § security
advanced	object		Voir § advanced

Ajouts spécifiques à la réponse :

• meta: { id, createdAt, updatedAt } - lecture seule.
• apiKey - chaîne de caractères, présente uniquement dans la réponse à POST /v1/management/bots - la clé Bot Talk nouvellement générée pour le nouveau bot, renvoyée exactement une fois.

§ role

Field	Type	Constraint	Description
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Profil prédéfini ; sélectionne le modèle de prompt (voir « Role and prompt construction »)
language	string	full English language name (English, Polish, ...) or Auto Detect	Langue principale injectée dans le modèle de prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Niveau de verbosité souhaité pour les réponses de l'IA
websiteAddress	string		Site web utilisé pour le contexte du prompt
companyDescription	string		Description de l'entreprise utilisée pour le contexte du prompt
rawPrompt	string		Prompt système personnalisé - utilisé textuellement uniquement lorsque role=CUSTOM

§ conversation

Field	Type	Constraint	Description
welcomeMessage	string		Premier message affiché au visiteur lors de l'ouverture
queryRefinementEnabled	boolean		Si défini sur true, reformule la question du visiteur avant la recherche RAG
conversationContinuityEnabled	boolean		Si défini sur true, les visiteurs qui reviennent reprennent leur dernière conversation
conversationRatingEnabled	boolean		Si défini sur true, affiche l'évaluation par pouce vers le haut/bas sur les messages du bot
positiveRatingTooltip	string		Infobulle sur le bouton d'évaluation positive
negativeRatingTooltip	string		Infobulle sur le bouton d'évaluation négative
suggestedQuestions	string		Questions suggérées / amorces de conversation, séparées par des sauts de ligne
dynamicSuggestedFollowups	boolean		Si défini sur true, l'IA suggère des relances de suivi après chaque réponse
dynamicFollowupsAutoIcons	boolean		Si défini sur true, l'IA sélectionne automatiquement des icônes emoji pour les relances dynamiques

§ chatMemory

Field	Type	Constraint	Description
enabled	boolean		Interrupteur principal pour la fonctionnalité de mémoire de chat
summaryConversationsEnabled	boolean		Enregistre des résumés pour chaque conversation
conversationSummaryPrompt	string		Prompt personnalisé utilisé pour résumer chaque conversation
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Détermine s'il faut utiliser le prompt de résumé par défaut ou personnalisé
clientSummaryPrompt	string		Prompt personnalisé utilisé pour dresser le profil du client au fil des conversations
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt de profil client par défaut ou personnalisé
summariesToKnowledgeRatio	int	10-90, step 10	% de la fenêtre de contexte de chat alloué aux résumés par rapport aux connaissances RAG

§ appearance

Field	Type	Constraint	Description
launcherColor	string (hex)		Couleur d'arrière-plan du lanceur (icône de chat)
headerColor	string (hex)		Couleur d'arrière-plan de l'en-tête du chat
titleColor	string (hex)		Couleur du titre de l'en-tête du chat
subtitleColor	string (hex)		Couleur du sous-titre de l'en-tête du chat
clientMessageBubbleColor	string (hex)		Couleur de la bulle des messages du visiteur
clientMessageTextColor	string (hex)		Couleur du texte des messages du visiteur
responseMessageBubbleColor	string (hex)		Couleur de la bulle des réponses du bot
responseMessageTextColor	string (hex)		Couleur du texte des réponses du bot
chatSubheader	string		Phrase d'accroche affichée sous le titre du chat
senderPlaceholder	string		Texte de placeholder dans le champ de saisie du message
resetConversationTooltip	string		Infobulle sur le bouton de réinitialisation de conversation
chatAlignment	string (enum)	∈ {left, right}	Côté de l'écran auquel le chat s'ancre
launcherBottomMargin	int	0-500	Distance entre le lanceur et le bord inférieur (px)
launcherSideMargin	int	0-500	Distance entre le lanceur et le bord latéral (px)
displayShadow	boolean		Ombre portée sous le widget
customCss	string		CSS brut injecté dans l'iframe du widget
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Mode d'ouverture des liens présents dans les messages du bot
minimizedDisplayMode	string (enum)	∈ {icon, minified}	État réduit : icône de lanceur ou barre de saisie compacte
chatDesktopWidthPx	int		Largeur du widget sur ordinateur
chatDesktopHeightPx	int		Hauteur du widget sur ordinateur
chatMobileSizePercent	int		Taille du widget sur mobile en % de la fenêtre d'affichage
messageFontSize	int		Taille de police du texte des messages (px)
showChatbotBubblesDesktop	boolean		Afficher les bulles d'accroche flottantes sur ordinateur
showChatbotBubblesMobile	boolean		Afficher les bulles d'accroche flottantes sur mobile
chatbotBubblesDelaySeconds	int		Délai avant l'apparition des bulles d'accroche (secondes)
launcherIconFullSize	boolean		Rendre l'icône personnalisée du lanceur d'un bord à l'autre sans marge interne
welcomeScreenEnabled	boolean		Afficher le Welcome Screen (écran d'accueil) au lieu d'ouvrir directement le chat
welcomeScreenQuestionsLabel	string		Libellé au-dessus des questions suggérées sur l'écran d'accueil
welcomeScreenHideHumanContactForm	boolean		Masquer l'action du formulaire de contact humain dans l'en-tête pendant l'affichage du Welcome Screen. Elle réapparaît après le premier message du visiteur. Les bots créés avant le 02/09/2026 sont définis par défaut sur true
welcomeScreenHideLiveChat	boolean		Masquer l'action de chat en direct dans l'en-tête pendant l'affichage du Welcome Screen. Elle réapparaît après le premier message du visiteur. Les bots créés avant le 02/09/2026 sont définis par défaut sur true
headerActionsLayout	string	DROPDOWN	Façon dont le chat en direct et le formulaire de contact humain sont proposés dans l'en-tête du chat : ICONS (une icône distincte pour chacun) ou DROPDOWN (regroupés dans le menu de l'en-tête). Les bots créés avant le 02/09/2026 sont définis par défaut sur ICONS
stackSuggestedQuestions	boolean		Empiler verticalement les questions suggérées (plutôt que côte à côte)
suggestedQuestionsFontSize	int		Taille de police des puces de questions suggérées (px)
suggestedQuestionsTextColor	string (hex)		Couleur du texte des puces de questions suggérées
suggestedQuestionsBackgroundColor	string (hex)		Couleur d'arrière-plan des puces de questions suggérées
autoOpenChat	boolean		Ouvrir automatiquement le chat sur ordinateur
autoOpenChatOnMobiles	boolean		Ouvrir automatiquement le chat sur mobile
autoOpenChatDelay	boolean		Appliquer un délai avant l'ouverture automatique
autoOpenChatDelaySeconds	int		Délai d'ouverture automatique (secondes)
simulateHumanTyping	boolean		Découper la réponse du bot en bulles successives avec une animation de saisie
simulateHumanTypingDelay	int	0-200	Délai entre les bulles de message (secondes)
footerMarkdown	string	max 255	Markdown de pied de page personnalisé affiché sous le chat
avatarUrl	string	read-only	URL publique absolue de l'avatar ; pour le modifier, importez-le via la partie multipart avatar

Multipart lors de POST/PATCH : avatar (partie fichier). Les corps de réponse GET omettent le contenu du fichier - seule l'URL transite sur le réseau.

§ humanSupport

Field	Type	Constraint	Description
enabled	boolean		Interrupteur pour le flux Human Support (assistance humaine)
email	string	required (create-strict) when enabled=true	Adresse recevant les e-mails d'assistance humaine
dialogMessage	string		Message incitatif affiché au-dessus du formulaire
thankYouMessage	string		Confirmation affichée après l'envoi
emailMessageSubjectTemplate	string		Modèle d'objet pour l'e-mail envoyé à l'agent
emailMessageContentTemplate	string		Modèle de corps pour l'e-mail envoyé à l'agent
emailPlaceholder	string		Placeholder sur le champ de saisie de l'e-mail
messagePlaceholder	string		Placeholder sur la zone de saisie du message
emailWithConversationContent	boolean		Si défini sur true, inclut la transcription de la conversation dans le corps de l'e-mail
customFormId	long	id of an existing custom form	Remplace le formulaire de contact intégré par un formulaire personnalisé. null conserve le formulaire intégré
customFormMapping	string	JSON-encoded string	Mappe les champs du formulaire personnalisé vers les champs de l'e-mail d'assistance humaine

requirePolicyAccept se trouve sur consent.humanSupportRequirePolicyAccept, et non ici.

§ leadCollection

Field	Type	Constraint	Description
enabled	boolean		Interrupteur pour le formulaire de collecte de leads
nameEnabled	boolean		Collecter le nom
nameLabel	string		Libellé sur le champ de saisie du nom
emailEnabled	boolean		Collecter l'e-mail
emailLabel	string	required (create-strict) when enabled=true AND emailEnabled=true	Libellé sur le champ de saisie de l'e-mail
phoneEnabled	boolean		Collecter le téléphone
phoneLabel	string	required (create-strict) when enabled=true AND phoneEnabled=true	Libellé sur le champ de saisie du téléphone
leaveDetailsMessage	string	required (create-strict) when enabled=true	Message invitant le visiteur à laisser ses coordonnées
thankYouMessage	string	required (create-strict) when enabled=true	Confirmation affichée après l'envoi
requireBeforeNewConversation	boolean		Si true, le formulaire doit être envoyé avant de commencer le chat ; si false, l'IA détermine le moment opportun pour présenter le formulaire
emailNotificationEnabled	boolean		Envoyer un e-mail au propriétaire à chaque lead collecté
emailNotificationAddress	string		Destinataire de la notification (par défaut l'e-mail du compte)
emailWithConversationContent	boolean		Si défini sur true, inclut la transcription de la conversation dans la notification

Règle stricte de validation croisée à la création : enabled=true requiert qu'au moins l'un des deux paramètres emailEnabled ou phoneEnabled soit activé. requirePolicyAccept se trouve sur consent.leadCollectionRequirePolicyAccept, et non ici.

| customFormId | long | id of an existing custom form | Remplace le formulaire de lead intégré par un formulaire personnalisé. null conserve le formulaire intégré | | customFormMapping | string | JSON-encoded string | Mappe les champs du formulaire personnalisé vers le nom / l'e-mail / le téléphone |

§ liveChat

Field	Type	Constraint	Description
enabled	boolean		Interrupteur pour la fonctionnalité Live Chat
infoMessage	string		Message explicatif préalable au transfert
startMessage	string		Message affiché lors du début de la session en direct
endMessage	string		Message affiché lorsque la session en direct prend fin
nameLabel	string		Libellé du champ de saisie du nom dans le pré-formulaire de chat en direct
emailLabel	string		Libellé du champ de saisie de l'e-mail dans le pré-formulaire de chat en direct
schedule	string	JSON-encoded string (weekday toggles + from/to + timezone)	Horaires de disponibilité du chat en direct - voir « Structured fields and ranges » pour la structure exacte
outOfHoursMessage	string		Message affiché en dehors des horaires prévus
closeModalMessage	string		Titre de la fenêtre modale « fermer le chat en direct ? »
closeModalConfirmLabel	string		Libellé du bouton de confirmation sur la fenêtre modale de fermeture
closeModalCancelLabel	string		Libellé du bouton d'annulation sur la fenêtre modale de fermeture
closeModalTooltipText	string		Infobulle sur l'élément de fermeture du chat
operatorHasJoinedLabel	string		Libellé affiché lorsqu'un opérateur se connecte
operatorDidNotJoinInTimeLabel	string		Libellé affiché lorsqu'aucun opérateur ne se connecte dans le délai imparti
waitingForOperatorToJoinLabel	string		Libellé affiché pendant l'attente d'un opérateur
waitingForOperatorSeconds	int		Délai d'attente imparti pour la prise en charge par un opérateur (secondes)
redirectToHumanSupportForm	boolean		Si défini sur true, bascule vers le formulaire Human Support si aucun opérateur ne prend en charge le chat
missedEmailEnabled	boolean	default true	Envoyer un e-mail au propriétaire du bot lorsqu'une demande de chat en direct est restée sans réponse. Non défini sur les anciens bots, ce qui est interprété comme activé

requirePolicyAccept se trouve sur consent.liveChatRequirePolicyAccept, et non ici.

§ consent

Field	Type	Constraint	Description
newConversationRequirePolicyAccept	boolean		Exiger le consentement à la politique de confidentialité avant de démarrer une nouvelle conversation
humanSupportRequirePolicyAccept	boolean		Exiger le consentement à la politique de confidentialité avant d'envoyer le formulaire d'assistance humaine
leadCollectionRequirePolicyAccept	boolean		Exiger le consentement à la politique de confidentialité avant d'envoyer le formulaire de collecte de leads
liveChatRequirePolicyAccept	boolean		Exiger le consentement à la politique de confidentialité avant de lancer une session de chat en direct
newConversationConsentDescription	string		Texte d'introduction pour l'écran de consentement au début de la conversation
privacyPolicyConsentCheckboxLabel	string		Libellé situé à côté de la case à cocher de consentement (contient généralement un lien vers la politique de confidentialité)

§ whiteLabel

Field	Type	Constraint	Description
hideRoboAssistLogo	boolean	white-label capability; subject to account limits	Masquer le logo ChatLab par défaut dans le pied de page
whitelabelLogoLink	string	white-label capability; subject to account limits	URL vers laquelle pointe le logo personnalisé de pied de page
assignToCustomDomain	boolean	gated by CUSTOM_DOMAIN feature	Héberger le chat sur le domaine personnalisé configuré
whitelabelLogoUrl	string	read-only	URL publique absolue du logo White Label ; pour le modifier, importez-le via la partie multipart whitelabel_logo

Multipart lors de POST/PATCH : whitelabel_logo (partie fichier). Les corps de réponse GET omettent le contenu du fichier - seule l'URL transite sur le réseau.

§ security

Field	Type	Constraint	Description
allowedDomains	string		Liste séparée par des virgules des domaines autorisés à intégrer le widget (vide = aucune liste blanche)
spamFilterEnabled	boolean		Activer le filtre antispam par bot sur les messages entrants
countryFilterMode	string	BLACKLIST or WHITELIST	Façon dont les listes de pays sont interprétées. Les listes elles-mêmes restent réservées aux administrateurs
talkMessagesRateLimit	int	>= 0; 0 disables	Nombre maximal de messages utilisateur autorisés dans la fenêtre de limite de débit
talkMessagesRateLimitDurationSeconds	int	>= 0	Durée de la fenêtre de limite de débit (secondes)
talkMessagesRateLimitHitMessage	string		Message affiché au visiteur lorsque la limite de débit est atteinte

§ voice

Field	Type	Constraint	Description
inputEnabled	boolean		Permettre au visiteur de dicter des messages (reconnaissance vocale)
conversationEnabled	boolean	requires the voice feature on the plan	Activer les conversations vocales complètes
voiceId	string	provider-specific voice id (e.g. alloy)	Voix de synthèse utilisée
model	string	e.g. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modèle vocal. Facturé à la minute, les tarifs varient selon le modèle
turnDetection	string	provider-specific	Mode de détection de prise de parole
audioPrompt	string		Prompt système supplémentaire réservé aux échanges vocaux
welcomeMessage	string		Phrase d'introduction énoncée vocalement
language	string	language code	Langue principale pour la voix
additionalLanguages	string	comma-separated language codes	Langues supplémentaires acceptées par l'agent vocal
maxDurationSeconds	int		Limite stricte de durée d'une conversation vocale unique
maxDurationMessage	string		Message affiché lorsque la limite de durée est atteinte

§ multilingual

Field	Type	Constraint	Description
enabled	boolean		Interrupteur pour le mode multilingue
mode	string	AUTODETECT or a fixed-list mode	Façon dont le bot choisit la langue de réponse
baseLanguage	string	language code	Langue dans laquelle les textes du bot sont rédigés
languages	string	comma-separated language codes	Langues proposées au visiteur
knowledgeLanguageMode	string		Traitement réservé aux connaissances rédigées dans d'autres langues
knowledgeLanguageFallback	string	language code	Langue utilisée par défaut si aucune correspondance n'est trouvée

§ advanced

Field	Type	Constraint	Description
model	string	subject to account limits; see "AI text models" above	Identifiant du LLM (par ex. 5-MINI)
temperature	decimal	0.0-1.0	Température d'échantillonnage (correspond au curseur dans l'interface utilisateur)
chatContextSize	int	∈ {8000, 16000, 32000}; silently clamped to your account limit	Fenêtre de tokens pour l'historique de chat
botMessagesLimit	long	0 or multiple of 1000 (e.g. 1000, 2000, 10000)	Nombre maximal de réponses du bot par conversation (0 = aucune limite)
internalLocale	string	locale code in ll_CC form	Paramètres régionaux pour les libellés de l'interface du widget (distinct de role.language)
productsViewEnabled	boolean		Si défini sur true, affiche les Offer Cards (fiches d'offres) e-commerce au sein du chat
includeProductsInKnowledgeBase	boolean		Si défini sur true, indexe le catalogue de produits dans la base de connaissances

Hors du périmètre de l'API

L'interface d'administration présente plusieurs sections qui ne sont délibérément pas exposées dans cette version de la Management API :

• Onglet Flow (flux) - l'éditeur visuel Conversation Flow (étapes et transitions). Non exposé via la Management API.
• Onglet Actions - intégrations gérées d'e-commerce / de réservation, AI Search, et fonctions API personnalisées. Les appels d'outils n'ont jamais fait partie de la Management API.
• Le générateur de formulaires personnalisés lui-même - la création et la modification de formulaires personnalisés ne sont pas exposées. Vous pouvez en revanche associer un formulaire existant à un bot au moyen de leadCollection.customFormId et de humanSupport.customFormId.
• Icônes personnalisées d'ouverture / fermeture du chat - customLauncherIconVisible, openChatIcon, closeChatIcon. L'API n'expose que les éléments multipart principaux avatar et whitelabel_logo.
• Listes d'adresses IP et de pays - les entrées elles-mêmes sont réservées aux administrateurs. Seul le mode d'interprétation est exposé, via security.countryFilterMode.

Endpoints

POST /v1/management/bots

Créer un nouveau bot. Deux Content-Types équivalents sont acceptés ; choisissez celui qui vous convient le mieux.

Mode A - JSON brut (recommandé lorsque vous n'avez pas besoin d'importer un avatar / logo dans la même requête) :

• Content-Type: application/json
• Le corps de la requête est le JSON de configuration du bot (pas d'encapsuleur data)
• Les fichiers (avatar / logo) peuvent être importés ultérieurement via un second PATCH en utilisant le mode B

Mode B - multipart/form-data (à utiliser lors de l'importation de fichiers dans la même requête) :

• Content-Type: multipart/form-data; boundary=...
• Partie JSON data (requise, Content-Type: application/json) - configuration du bot selon la structure imbriquée décrite ci-dessus
• Partie de fichier avatar (facultative) - image de l'avatar du bot
• Partie de fichier whitelabel_logo (facultative) - logo White Label (s'applique uniquement si votre compte inclut l'option White Label)

Seul le champ name est requis dans le JSON ; tous les autres champs reprennent la valeur par défaut que l'assistant de configuration de l'interface d'administration définirait.

Corps complet de la requête

Voici le JSON data maximal - chaque section est renseignée. N'envoyez que les sections qui vous intéressent ; toutes les autres prendront leurs valeurs par défaut.

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

Règles de validation avec leurs propres messages d'erreur :

• name - requis, 150 caractères maximum
• advanced.temperature - entre 0.0 et 1.0
• chatMemory.summariesToKnowledgeRatio - entier entre 10 et 90 (pourcentage, par paliers de 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - entre 0 et 500
• appearance.footerMarkdown - 255 caractères maximum
• humanSupport.enabled=true requiert que humanSupport.email soit défini
• leadCollection.enabled=true requiert qu'au moins un des champs leadCollection.emailEnabled ou leadCollection.phoneEnabled soit défini à true ; le canal activé requiert également son libellé respectif, ainsi que leaveDetailsMessage et thankYouMessage
• Les champs plafonnés (advanced.chatContextSize, advanced.botMessagesLimit, etc.) sont automatiquement limités aux plafonds de votre compte sans générer d'erreur

Les champs dont la valeur est null sur le serveur sont omis du corps JSON - seules les valeurs non nulles transitent sur le réseau.

Corps complet de la réponse (201)

Même structure que la requête, avec en plus le bloc en lecture seule meta et la clé à usage unique apiKey au niveau supérieur. Les URL de fichiers en lecture seule (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) sont renseignées par le serveur lorsque les parties multipart correspondantes ont été importées.

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

Le champ apiKey apparaît uniquement lors de la création - il s'agit de la clé Bot Talk nouvellement générée et liée au nouveau bot. La valeur en clair n'est affichée qu'une seule fois et ne pourra plus être récupérée depuis l'API ; enregistrez-la immédiatement de votre côté.

L'en-tête de réponse Location contient l'URL du nouveau bot (/v1/management/bots/{id}).

Exemples Curl

Mode A - JSON brut (le plus simple) :

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

Mode B - multipart avec 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}

Renvoie la configuration actuelle d'un bot qui vous appartient.

Exemple Curl

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

Corps complet de la réponse (200)

Même structure que la réponse POST, sans la clé unique apiKey. Le bloc meta est inclus. Renvoie 404 not_found_error si le bot n'existe pas ou n'appartient pas à votre compte.

L'avatar actuel et le logo White Label sont fournis sous forme d'URL complètes en lecture seule (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - basées sur le même protocole + hôte + chemin de contexte ayant servi cette requête. Récupérez les fichiers en effectuant directement une requête GET sur ces URL ; pour remplacer l'un ou l'autre de ces fichiers, importez-en un nouveau via la partie multipart avatar / whitelabel_logo lors d'un PATCH. Ces champs d'URL sont ignorés s'ils sont envoyés dans le corps d'une requête.

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

Cloner un bot

Le corps de la requête de POST /v1/management/bots et le corps de la réponse de GET /v1/management/bots/{bot_id} partagent la même structure, de sorte que le clonage s'effectue en trois étapes : faire un GET sur la source, retirer les champs d'identité gérés par le serveur, puis faire un POST du résultat.

1. Effectuez un GET sur le bot source.

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

2. Retirez le bloc meta de premier niveau. L'objet meta (id, createdAt, updatedAt) est géré par le serveur et en lecture seule - le laisser dans le corps du POST n'a pas d'incidence négative (le serveur l'ignore), mais le supprimer rend l'intention explicite et permet de garder une charge utile propre. Vous pouvez éventuellement modifier name afin de distinguer le clone de la source.

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

3. Envoyez par POST le corps allégé pour créer le clone. Consultez la référence de POST /v1/management/bots ci-dessus pour connaître la structure complète du corps et les règles de validation.

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

La réponse contient le meta.id du nouveau bot ainsi qu'une clé apiKey fraîchement générée (la clé Bot Talk pour le clone). La valeur en clair de l'apiKey est renvoyée uniquement lors de cette réponse de création - copiez-la avant de fermer le corps de la réponse ; elle ne pourra plus être récupérée ultérieurement.

Deux remarques importantes :

• Les fichiers ne sont pas clonés. appearance.avatarUrl et whiteLabel.whitelabelLogoUrl sont en lecture seule et pointent vers les fichiers du bot source. Si vous avez besoin du même avatar ou du même logo en marque blanche sur le clone, téléchargez les octets depuis les URL sources et importez-les en tant que parties multipart avatar / whitelabel_logo - soit lors du POST de création (Mode B), soit lors d'un PATCH ultérieur.
• Les clés Bot Talk ne sont pas clonées. Chaque bot possède son propre ensemble de clés Bot Talk. L'unique apiKey renvoyée par le POST de création est la seule générée automatiquement ; créez des clés supplémentaires depuis l'onglet API (API tab) du bot si nécessaire.

PATCH /v1/management/bots/{bot_id}

Mettez à jour un ou plusieurs champs d'un bot qui vous appartient. Seules les sections / champs présents dans le JSON sont modifiés ; tout ce qui est omis (ou envoyé avec la valeur null) reste intact. La sémantique de mise à jour partielle s'applique par champ au sein d'une section envoyée.

Deux en-têtes Content-Type équivalents sont acceptés (comme pour POST) :

Mode A - JSON brut (recommandé pour une simple mise à jour des paramètres) :

• Content-Type: application/json
• Le corps de la requête est le JSON du patch (sans enveloppe data)

Mode B - multipart/form-data (à utiliser lors de l'importation de fichiers) :

• Partie JSON data (facultative) - le patch. À envoyer uniquement si vous souhaitez modifier des champs. Omettez-la entièrement si vous souhaitez seulement importer un avatar ou un logo.
• Partie de fichier avatar (facultative) - remplace l'avatar
• Partie de fichier whitelabel_logo (facultative) - remplace le logo en marque blanche (s'applique uniquement si votre compte inclut l'option White Label)

Les trois parties sont facultatives sur un PATCH, mais au moins l'une d'entre elles doit être présente pour que l'appel ait un sens.

Corps de requête complet (surface maximale)

Tout champ accepté par POST /v1/management/bots peut également être envoyé ici. L'exemple ci-dessous représente la surface complète ; en pratique, vous n'envoyez que les clés que vous souhaitez modifier (voir « Mise à jour partielle minimale » plus bas) - chaque clé omise (ou envoyée avec la valeur null) conserve sa valeur enregistrée intacte.

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

Mise à jour partielle minimale

Appliquez un PATCH sur un seul champ en envoyant exactement les clés que vous souhaitez modifier - tout le reste est conservé.

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

Exemples Curl

Mode A - JSON brut (le plus simple) :

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

Mode B - multipart (pour remplacer l'avatar / le 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'

Mode B - remplacer uniquement l'avatar (aucune modification de champ) :

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

Corps de la réponse (200)

Même structure que GET /v1/management/bots/{bot_id} - la configuration complète du bot après application du patch, y compris le bloc meta. Pas de champ apiKey. Renvoie 404 not_found_error si le bot n'existe pas ou n'appartient pas à votre compte.

L'exemple ci-dessous illustre la réponse après avoir appliqué le patch du Corps de requête complet (surface maximale) ci-dessus au bot de l'exemple GET - les champs modifiés reflètent les nouvelles valeurs, les champs non touchés sont conservés, et meta.updatedAt est mis à jour.

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

Consultez l'utilisation actuelle de l'abonnement pour le compte propriétaire de la clé Management.

Corps de la réponse (200)

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

• subscriptionType est l'identifiant en minuscules du plan actuel du compte (par exemple standard dans l'exemple). Les plans proviennent d'un catalogue dynamique, de sorte que l'ensemble exact des identifiants peut évoluer au fil du temps à mesure que des plans sont renommés ou ajoutés - traitez ceci comme une chaîne opaque, et non comme un enum fixe.
• messages.used / limit / remaining représentent les crédits de messages pour la période de facturation en cours.
• bots.used / limit / remaining comptabilisent les bots actifs par rapport à la limite de bots de votre compte.

En-têtes de limitation de débit

Les réponses qui atteignent l'étape de limitation de débit (c'est-à-dire une fois l'authentification et la liste blanche d'adresses IP validées) incluent :

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

• X-RateLimit-Limit - le plafond par clé réellement appliqué à cet appel (10 par défaut, ou votre valeur configurée dans rateLimitPerMinute si elle est inférieure).
• X-RateLimit-Remaining - le nombre de jetons restants dans le compartiment juste après cet appel.
• X-RateLimit-Reset - horodatage Unix en secondes auquel le prochain jeton sera disponible (il ne s'agit pas d'une réinitialisation complète du compartiment ; le compartiment se remplit en continu). Lorsque le compartiment est plein, cette valeur correspond à l'heure actuelle.

Sur les réponses 429 rate_limit_exceeded, l'en-tête Retry-After est également défini, exprimé en secondes entières jusqu'à ce qu'au moins un jeton se libère.

Les erreurs préalables à l'authentification (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) et 403 ip_not_whitelisted ne comportent pas les en-têtes X-RateLimit-* - le limiteur n'est sollicité qu'après la réussite de l'authentification et des vérifications d'adresses IP.

Format des erreurs

Même enveloppe que pour l'API Bot Talk API :

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

Les erreurs de validation utilisent code: "invalid_parameter" et préfixent le message par le chemin du champ défaillant afin de repérer facilement la section concernée :

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

Les valeurs non valides pour les champs enum / à ensemble fini (par exemple chatMemory.clientSummaryPromptType = "BOGUS") incluent le chemin du champ, la valeur rejetée et la liste des valeurs autorisées :

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

Ressources associées

Pour les points de terminaison de conversation et le streaming SSE, consultez l'article sur la Bot Talk API.