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.

Premiers pas

1. Ouvrez l'application d'administration et accédez à Account Settings > Management API (Paramètres du compte > Management API).
2. Cliquez sur Create Management Key (Créer une clé de gestion), nommez-la, définissez éventuellement une liste blanche d'adresses IP et une limite de débit, puis validez.
3. Sélectionnez uniquement les autorisations nécessaires à votre intégration et copiez la clé complète depuis la fenêtre de confirmation. La clé en texte brut ne s'affiche qu'une seule fois.
4. Stockez-la sur votre serveur, et non dans du code côté navigateur ou dans un dépôt public. Effectuez une requête en lecture seule telle que GET /v1/usage avec l'autorisation usage pour vérifier l'accès.
5. Révoquez les clés inutilisées ou compromises depuis la page Management API.

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

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

POST et PATCH acceptent un corps JSON regroupé en 13 sections. Chaque section correspond à un sous-onglet de la barre latérale Paramètres du bot (Bot Settings) dans l'application d'administration, de sorte que les clés JSON et les onglets visibles s'alignent : si vous modifiez consent.humanSupportRequirePolicyAccept via l'API, vous verrez le même interrupteur basculer sur l'onglet Consent & Privacy (Consentement et confidentialité) dans 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)
• conversation - message de bienvenue, affinement des requêtes, continuité de la conversation, interrupteur d'évaluation + infobulles, contenu des suggestions de questions + relances dynamiques (onglet Chat Conversation)
• chatMemory - interrupteur de mémoire de chat, prompts de résumé, allocation de contexte (onglet Summaries & Memory)
• 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)
• humanSupport - formulaire de contact humain (onglet Human Contact Form)
• leadCollection - formulaire de capture de leads (onglet Lead Collection)
• liveChat - transfert vers le live chat (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)
• whiteLabel - masquage du logo, lien du logo personnalisé, hébergement sur domaine personnalisé (onglet Whitelabel)
• security - domaines autorisés, filtre anti-spam, limites de débit des échanges (onglet Security)
• voice - saisie vocale et conversations vocales : modèle, voix, langues, prompt, durée maximale (onglet Voice Conversation)
• multilingual - mode multilingue, langue de base, langues proposées, gestion de la langue des connaissances (onglet Languages)
• advanced - modèle de LLM, température, taille de contexte, limite de messages du bot, locale interne, Offer Cards (onglet Model & Advanced)

Parmi les paramètres modifiables, seul name se trouve au premier niveau, car il identifie le bot plutôt que d'appartenir à un onglet particulier.

La barre latérale Paramètres du bot comporte actuellement 16 sous-onglets, dont 13 correspondent aux sections ci-dessus. Les trois sous-onglets qui n'ont aucune section correspondante sont Flow, Actions et Forms - tous trois abordés dans la section « Hors périmètre de l'API » ci-dessous. 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 ajoute deux éléments supplémentaires :

• meta - en lecture seule : identifiant du bot et horodatages. Supprimez-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 fraîchement générée pour le nouveau bot.

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

• appearance.avatarUrl - URL publique absolue de l'image de l'avatar du bot (ex. https://api.chatlab.com/aichat/content/avatar_xyz.png). Effectuez un GET direct 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).

Les deux URL utilisent le protocole + l'hôte + le chemin de contexte de la requête courante ; ainsi, sur un domaine personnalisé White Label, elles reviennent avec ce domaine pour racine (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 au sein d'une section afin d'ignorer ce champ spécifique. Un null au niveau du champ n'efface jamais une valeur enregistrée - il signifie simplement « ne pas modifier ».

Construction du rôle et du prompt

Le prompt système que le LLM reçoit réellement est construit de deux manières différentes selon role.role. Savoir sur quelle branche vous vous trouvez vous indique quels champs sont pris en compte et lesquels sont enregistrés mais ignorés.

Branche A - role.role vaut CUSTOMER_SUPPORT, SALES ou LEAD_COLLECTION_AGENT (basé sur un modèle prédéfini)

Le backend assemble 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, injecté 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 - associé à un objectif de nombre de mots : Concise ≈ 50 mots, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - facultatif ; lorsqu'il est renseigné, il est ajouté sous la forme « for the users of the website {url} »
• role.companyDescription - facultatif ; lorsqu'il est renseigné, il est ajouté 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 surcoût d'un comportement calibré pour le rôle et de garde-fous de sécurité.

Branche B - role.role vaut CUSTOM (prompt fourni par l'appelant)

Le backend utilise role.rawPrompt comme prompt de rôle et ajoute les consignes fixes de longueur de réponse de la plateforme. C'est distinct de role.responseLength : le paramètre optionnel Concise/Normal/Detailed n'est pas injecté pour un rôle CUSTOM. De même, language, websiteAddress et companyDescription sont enregistrés mais ne sont pas injectés dans ce prompt de rôle. Intégrez vous-même la langue souhaitée, l'objectif de longueur de réponse ou le contexte de l'entreprise dans rawPrompt. Des instructions d'exécution supplémentaires et du contexte récupéré peuvent également être fournis, de sorte que rawPrompt ne constitue pas l'intégralité de l'entrée du modèle. Les consignes de ton du rôle prédéfini ne sont pas ajoutées, mais choisir CUSTOM ne supprime pas toutes les instructions de la plateforme.

N'utilisez CUSTOM que lorsque le prompt basé sur un modèle prédéfini ne correspond pas à votre cas d'usage (ex. 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 d'énumération / valeurs fixes

Les champs de type énumération ou à valeurs contraintes rejettent les valeurs non valides avec 400 invalid_parameter. D'autres champs sont de simples chaînes, même là où l'interface propose une liste fixe. Utilisez la syntaxe documentée et validez votre payload plutôt que de supposer que toute chaîne non prise en charge sera rejetée.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nom complet de la langue en anglais depuis le menu déroulant de l'administration, ex. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi, et ~80 autres. La valeur est enregistrée telle quelle et insérée dans le modèle de prompt ; ainsi, les codes ISO à deux lettres (en, pl) et les autres valeurs hors liste ne sont pas rejetés par l'API mais produisent une consigne incohérente du type « Output in en, unless... ». Vaut Auto Detect par défaut si omis lors de la création.
• advanced.model - voir « Modèles de texte IA » ci-dessous. Il s'agit d'une chaîne, et non d'une énumération validée dans le schéma de requête ; utilisez une valeur prise en charge et non un nom de modèle arbitraire.
• advanced.chatContextSize - utilisez 8000, 16000 ou 32000, en accord avec l'interface. Les valeurs supérieures au plafond du compte sont discrètement ramenées au maximum ; le DTO n'impose pas cet ensemble de trois valeurs.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - interrupteur booléen. true oblige l'utilisateur à remplir le formulaire de lead avant d'entamer une conversation ; false laisse l'IA décider du moment où afficher le formulaire (par défaut).

Champs structurés et plages de valeurs

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

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

• chatMemory.summariesToKnowledgeRatio - pourcentage entier, de 10 à 90 ; l'interface utilise des paliers de 10, mais l'API accepte des entiers sur toute la plage. Valeur par défaut : 50. Lorsque la mémoire est activée et que le contexte est supérieur à 8k, ce paramètre divise le budget alloué aux connaissances et à la mémoire après la réservation destinée au prompt et à la conversation récente, et non l'intégralité du contexte du modèle. À 8k, aucun budget de résumé n'est alloué par ce paramètre.

• liveChat.schedule - JSON encodé sous forme de chaîne, et non un objet JSON imbriqué sur le réseau. Le serveur enregistre la chaîne brute telle quelle ; l'interface d'administration l'analyse côté client lors de l'affichage de l'éditeur d'horaires. Une fois analysée, la chaîne se compose d'une entrée par jour de la semaine ainsi que d'une clé timezone :

  • chaque clé de jour de la semaine (monday-sunday) correspond à {enabled: boolean, from: "H:MM", to: "H:MM"} au format 24 heures
  • timezone est un identifiant de fuseau 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 plages horaires indiquées, liveChat.outOfHoursMessage est présenté au visiteur et le transfert vers le live chat est désactivé. La validation de la structure interne s'exécute uniquement côté client dans l'interface d'administration - un JSON mal formé ou des clés non reconnues sont acceptés par l'API comme une simple chaîne et apparaîtront sous la forme d'une erreur d'affichage lorsqu'un utilisateur ouvrira ultérieurement le bot dans l'administration. Validez la structure de votre côté avant l'envoi.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - libellés courts affichés sur les commandes d'évaluation de conversation 👍 / 👎 lorsque conversation.conversationRatingEnabled=true est activé. Le texte par défaut est « I like the response » / « I don't like the response ». Visible par les utilisateurs finaux.

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

• whiteLabel.whitelabelLogoLink - fonctionnalité White Label, soumise aux limites de votre compte. URL cible au clic sur le logo personnalisé lorsque hideRoboAssistLogo=true est activé 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 est activé. Valeur par défaut : 5.

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

• 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 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, et bien d'autres. Envoyer un code à deux lettres seul ("en") ou un code BCP-47 ("en-US") ne fait pas partie des formats autorisés. Valeur par défaut : en_US. Il s'agit de la locale utilisée pour le formatage des dates et nombres dans l'habillage du widget, distincte de role.language (la langue d'expression conversationnelle du bot).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - entiers (à envoyer sous forme de nombres JSON, ex. 30, et non "30"). Définissez la limite de messages sur 0 pour désactiver cette restriction par session. En cas d'activation, indiquez une durée positive. Le backend applique la règle de N messages par session par durée en secondes avant d'afficher security.talkMessagesRateLimitHitMessage au visiteur.

• advanced.botMessagesLimit - entier (nombre JSON, ex. 1000). 0 signifie qu'aucun plafond supplémentaire n'est défini par bot, le budget de crédits du compte restant applicable ; sinon, la valeur doit être un multiple de 1 000 (1000, 2000, 10000, ...). Les valeurs telles que 100 ou 1500 sont rejetées avec 400 invalid_parameter. Il s'agit d'un plafond mensuel de crédits par bot, et non d'un décompte de messages par conversation. Le convertisseur ne restreint pas cette valeur au budget du compte ; le budget global du compte continue d'encadrer l'utilisation réelle.

Modèles de texte IA (advanced.model)

Utilisez l'identifiant exact de modèle renvoyé dans advanced.model lors de la lecture d'un bot configuré avec le modèle visé dans Settings > Model & Advanced (Paramètres > Modèle et avancé). La valeur par défaut actuelle à la création est 5.6-LUNA. Les identifiants sont sensibles à la casse et diffèrent des noms d'affichage ; par exemple, 5.6-LUNA s'affiche sous la forme GPT 5.6-luna.

Le catalogue de modèles évolue au fil du temps. Ne présumez pas qu'une chaîne arbitraire ou qu'un identifiant public de modèle d'un fournisseur soit pris en charge sous prétexte que le schéma de requête accepte une chaîne. Relisez la configuration enregistrée et testez le chatbot obtenu avant son déploiement.

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

Les sections et champs pris en charge, avec leurs types et contraintes importantes. Sémantique PATCH : tout champ omis (ou envoyé sous la forme null) conserve sa valeur enregistrée sans modification. La même structure est utilisée pour la réponse (hors contenu binaire multipart ; avec le bloc meta en lecture seule sur chaque réponse et apiKey uniquement sur la réponse de création).

Niveau supérieur

Champ	Type	Contrainte	Description
name	chaîne	max 150, obligatoire à la création	Nom d'affichage du bot
role	objet		Voir § role
conversation	objet		Voir § conversation
chatMemory	objet		Voir § chatMemory
appearance	objet		Voir § appearance
humanSupport	objet		Voir § humanSupport
leadCollection	objet		Voir § leadCollection
liveChat	objet		Voir § liveChat
consent	objet		Voir § consent
whiteLabel	objet		Voir § whiteLabel
security	objet		Voir § security
advanced	objet		Voir § advanced

Ajouts réservés à la réponse :

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

§ role

Champ	Type	Contrainte	Description
role	chaîne (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Préréglage du persona ; sélectionne le modèle de prompt (voir « Construction du rôle et du prompt »)
language	chaîne	nom complet de la langue en anglais (English, Polish, ...) ou Auto Detect	Langue principale injectée dans le modèle de prompt
responseLength	chaîne	∈ {Concise, Normal, Detailed}	Niveau de détail souhaité pour les réponses de l'IA
websiteAddress	chaîne		Site web utilisé pour le contexte du prompt
companyDescription	chaîne		Description de l'entreprise utilisée pour le contexte du prompt
rawPrompt	chaîne		Prompt système personnalisé - utilisé textuellement uniquement lorsque role=CUSTOM

§ conversation

Champ	Type	Contrainte	Description
welcomeMessage	chaîne		Premier message affiché au visiteur à l'ouverture
queryRefinementEnabled	booléen		Si true, affine la question du visiteur avant la récupération RAG
conversationContinuityEnabled	booléen		Si true, les visiteurs qui reviennent reprennent leur dernière conversation
conversationRatingEnabled	booléen		Si true, affiche les boutons d'évaluation de la conversation (pouce vers le haut/bas)
positiveRatingTooltip	chaîne		Infobulle sur le bouton d'évaluation positive
negativeRatingTooltip	chaîne		Infobulle sur le bouton d'évaluation négative
suggestedQuestions	chaîne		Questions suggérées / amorces de conversation séparées par des sauts de ligne
dynamicSuggestedFollowups	booléen		Si true, l'IA propose des suggestions de suivi après chaque réponse
positiveRatingMessage	chaîne		Message affiché après un retour positif
negativeRatingMessage	chaîne		Message affiché après un retour négatif
hideSuggestedQuestionsAfterFirstUse	booléen		Masquer les suggestions statiques après utilisation
dynamicFollowupsAutoIcons	booléen		Si true, l'IA choisit automatiquement des émojis pour les relances dynamiques

§ chatMemory

Champ	Type	Contrainte	Description
enabled	booléen		Interrupteur principal de la fonctionnalité de mémoire de chat
summaryConversationsEnabled	booléen		Conserver les résumés par conversation
conversationSummaryPrompt	chaîne		Prompt personnalisé utilisé pour résumer chaque conversation
conversationSummaryPromptType	chaîne (enum)	∈ {DEFAULT, CUSTOM}	Utiliser le prompt de résumé par défaut ou personnalisé
clientSummaryPrompt	chaîne		Prompt personnalisé utilisé pour établir le profil du client d'une conversation à l'autre
clientSummaryPromptType	chaîne (enum)	∈ {DEFAULT, CUSTOM}	Prompt de profil client par défaut ou personnalisé
summariesToKnowledgeRatio	entier	10-90 (palier dans l'interface 10)	% du budget de connaissances/mémoire alloué aux résumés pour les contextes supérieurs à 8k

§ appearance

Champ	Type	Contrainte	Description
launcherLabelLine1	chaîne	max 60	Première ligne de texte du lanceur
launcherLabelLine2	chaîne	max 60	Seconde ligne de texte du lanceur
launcherTextColor	chaîne		Couleur du texte du lanceur
launcherDismissEnabled	booléen		Permettre de fermer le lanceur
widgetFontFamily	chaîne	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Famille de police du widget
chatDrawerEnabled	booléen		Activer l'affichage en volet latéral (drawer)
launcherColor	chaîne (hex)		Couleur d'arrière-plan du lanceur (icône de chat)
headerColor	chaîne (hex)		Couleur d'arrière-plan de l'en-tête du chat
titleColor	chaîne (hex)		Couleur du titre de l'en-tête du chat
subtitleColor	chaîne (hex)		Couleur du sous-titre de l'en-tête du chat
clientMessageBubbleColor	chaîne (hex)		Couleur de la bulle des messages du visiteur
clientMessageTextColor	chaîne (hex)		Couleur du texte des messages du visiteur
responseMessageBubbleColor	chaîne (hex)		Couleur de la bulle des réponses du bot
responseMessageTextColor	chaîne (hex)		Couleur du texte des réponses du bot
chatSubheader	chaîne		Slogan affiché sous le titre du chat
senderPlaceholder	chaîne		Texte indicatif dans le champ de saisie du message
resetConversationTooltip	chaîne		Infobulle sur le bouton « réinitialiser la conversation »
chatAlignment	chaîne (enum)	∈ {left, right}	Côté de l'écran où le chat est ancré
launcherBottomMargin	entier	0-500	Distance du lanceur par rapport au bord inférieur (px)
launcherSideMargin	entier	0-500	Distance du lanceur par rapport au bord latéral (px)
displayShadow	booléen		Ombre portée sous le widget
customCss	chaîne		CSS brut injecté dans l'iframe du widget
chatMessageLinkTarget	chaîne (enum)	∈ {_blank, _self}	Façon dont les liens s'ouvrent dans les messages du bot
minimizedDisplayMode	chaîne (enum)	∈ {icon, minified, pill}	État réduit : icône de lancement, barre d'envoi compacte ou pilule
chatDesktopWidthPx	entier		Largeur du widget sur ordinateur
chatDesktopHeightPx	entier		Hauteur du widget sur ordinateur
chatMobileSizePercent	entier		Taille du widget sur mobile en % de la fenêtre d'affichage
messageFontSize	entier		Taille de police du texte des messages (px)
showChatbotBubblesDesktop	booléen		Afficher les bulles d'accroche flottantes sur ordinateur
showChatbotBubblesMobile	booléen		Afficher les bulles d'accroche flottantes sur mobile
chatbotBubblesDelaySeconds	entier		Délai avant l'apparition des bulles d'accroche (secondes)
launcherIconFullSize	booléen		Afficher l'icône personnalisée du lanceur d'un bord à l'autre au lieu d'une marge intérieure
welcomeScreenEnabled	booléen		Afficher l'écran de bienvenue au lieu d'ouvrir directement le chat
welcomeScreenQuestionsLabel	chaîne		Libellé au-dessus des questions suggérées sur l'écran de bienvenue
welcomeScreenHideHumanContactForm	booléen		Masquer le bouton du formulaire de contact humain dans l'en-tête lorsque l'écran de bienvenue est affiché. Il réapparaît après le premier message du visiteur. Pour les bots créés avant le 2026-09-02, la valeur par défaut est true
welcomeScreenHideLiveChat	booléen		Masquer le bouton de chat en direct dans l'en-tête lorsque l'écran de bienvenue est affiché. Il réapparaît après le premier message du visiteur. Pour les bots créés avant le 2026-09-02, la valeur par défaut est true
headerActionsLayout	chaîne	ICONS ou 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). Pour les bots créés avant le 2026-09-02, la valeur par défaut est ICONS
stackSuggestedQuestions	booléen		Empiler verticalement les questions suggérées (au lieu de les aligner côte à côte)
suggestedQuestionsFontSize	entier		Taille de la police des pastilles de suggestions de questions (px)
suggestedQuestionsTextColor	chaîne (hex)		Couleur du texte des pastilles de suggestions de questions
suggestedQuestionsBackgroundColor	chaîne (hex)		Couleur d'arrière-plan des pastilles de suggestions de questions
autoOpenChat	booléen		Ouvrir automatiquement le chat sur ordinateur
autoOpenChatOnMobiles	booléen		Ouvrir automatiquement le chat sur mobile
autoOpenChatDelay	booléen		Appliquer un délai avant l'ouverture automatique
autoOpenChatDelaySeconds	entier		Délai avant ouverture automatique (secondes)
simulateHumanTyping	booléen		Diviser la réponse du bot en bulles avec animation de saisie
simulateHumanTypingDelay	entier	0-200	Délai entre les messages sous forme de bulles (secondes)
footerMarkdown	chaîne	max 255	Markdown de pied de page personnalisé affiché sous le chat
avatarUrl	chaîne	lecture seule	URL publique complète de l'avatar ; pour la modifier, importez un nouveau fichier via la partie multipart avatar

Multipart sur 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

Champ	Type	Contrainte	Description
enabled	booléen		Interrupteur du flux de support humain
email	chaîne	obligatoire (création stricte) lorsque enabled=true	Adresse recevant les e-mails d'assistance humaine
dialogMessage	chaîne		Message d'invitation affiché au-dessus du formulaire
thankYouMessage	chaîne		Confirmation affichée après l'envoi
emailMessageSubjectTemplate	chaîne		Modèle d'objet pour l'e-mail envoyé à l'agent
emailMessageContentTemplate	chaîne		Modèle de corps pour l'e-mail envoyé à l'agent
emailPlaceholder	chaîne		Texte indicatif dans le champ de saisie de l'e-mail
messagePlaceholder	chaîne		Texte indicatif dans la zone de texte du message
emailWithConversationContent	booléen		Si true, inclut la transcription de la conversation dans le corps de l'e-mail
customFormId	entier long	ID d'un formulaire personnalisé existant	Remplace le formulaire de contact intégré par un formulaire personnalisé. À la création, l'omettre utilise le formulaire intégré ; sur PATCH, null conserve la sélection actuelle
customFormMapping	chaîne	chaîne encodée en JSON	Associe les champs du formulaire personnalisé aux champs d'e-mail d'assistance humaine

requirePolicyAccept se trouve sur consent.humanSupportRequirePolicyAccept, pas ici.

§ leadCollection

Champ	Type	Contrainte	Description
enabled	booléen		Interrupteur du formulaire de lead
nameEnabled	booléen		Recueillir le nom
nameLabel	chaîne		Libellé sur le champ de saisie du nom
emailEnabled	booléen		Recueillir l'e-mail
emailLabel	chaîne	obligatoire (création stricte) lorsque enabled=true ET emailEnabled=true	Libellé sur le champ de saisie de l'e-mail
phoneEnabled	booléen		Recueillir le téléphone
phoneLabel	chaîne	obligatoire (création stricte) lorsque enabled=true ET phoneEnabled=true	Libellé sur le champ de saisie du téléphone
leaveDetailsMessage	chaîne	obligatoire (création stricte) lorsque enabled=true	Message incitant le visiteur à laisser ses coordonnées
thankYouMessage	chaîne	obligatoire (création stricte) lorsque enabled=true	Confirmation affichée après l'envoi
requireBeforeNewConversation	booléen		Si true, le formulaire doit être soumis avant le début du chat ; si false, l'IA détermine quand faire apparaître le formulaire
emailNotificationEnabled	booléen		Envoyer un e-mail au propriétaire à chaque collecte de lead
emailNotificationAddress	chaîne		Destinataire des notifications (par défaut l'e-mail du compte)
emailWithConversationContent	booléen		Si true, inclut la transcription de la conversation dans la notification

| customFormId | entier long | ID d'un formulaire personnalisé existant | Remplace le formulaire de lead intégré par un formulaire personnalisé. À la création, l'omettre utilise le formulaire intégré ; sur PATCH, null conserve la sélection actuelle | | customFormMapping | chaîne | chaîne encodée en JSON | Associe les champs du formulaire personnalisé au nom / e-mail / téléphone |

Règle de création stricte inter-champs : enabled=true requiert au moins l'un des deux parmi emailEnabled ou phoneEnabled. requirePolicyAccept se trouve sur consent.leadCollectionRequirePolicyAccept, pas ici.

§ liveChat

Champ	Type	Contrainte	Description
enabled	booléen		Interrupteur de la fonctionnalité Live Chat
infoMessage	chaîne		Message explicatif avant le transfert
startMessage	chaîne		Message affiché au début de la session en direct
endMessage	chaîne		Message affiché à la fin de la session en direct
nameLabel	chaîne		Libellé du champ de saisie du nom dans le pré-formulaire de chat en direct
emailLabel	chaîne		Libellé du champ de saisie de l'e-mail dans le pré-formulaire de chat en direct
schedule	chaîne	chaîne encodée en JSON (options par jour de la semaine + from/to + timezone)	Horaires de fonctionnement du chat en direct - voir « Champs structurés et plages de valeurs » pour la structure exacte
outOfHoursMessage	chaîne		Message affiché lorsque les horaires indiquent que le service est fermé
closeModalMessage	chaîne		Titre de la fenêtre modale « fermer le chat en direct ? »
closeModalConfirmLabel	chaîne		Libellé du bouton de confirmation sur la modale de fermeture
closeModalCancelLabel	chaîne		Libellé du bouton d'annulation sur la modale de fermeture
closeModalTooltipText	chaîne		Infobulle sur l'action de fermeture du chat
operatorHasJoinedLabel	chaîne		Libellé affiché lorsqu'un opérateur rejoint la conversation
operatorDidNotJoinInTimeLabel	chaîne		Libellé affiché si aucun opérateur ne répond avant le délai imparti
waitingForOperatorToJoinLabel	chaîne		Libellé affiché pendant l'attente d'un opérateur
waitingForOperatorSeconds	entier		Délai d'attente pour la prise en charge par un opérateur (secondes)
redirectToHumanSupportForm	booléen		Si true, bascule vers le formulaire de support humain si aucun opérateur ne prend le relais
requireAdminOnline	booléen		Exiger la présence d'un opérateur disponible selon les paramètres de présence
presenceMode	chaîne		Mode de présence ; utilisez la valeur provenant d'un bot configuré dans l'interface utilisateur
hideHumanSupportWhenLiveChatAvailable	booléen		Masquer le formulaire de contact lorsque le chat en direct est disponible
missedEmailEnabled	booléen	par défaut 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 équivaut à activé

requirePolicyAccept se trouve sur consent.liveChatRequirePolicyAccept, pas ici.

§ consent

Champ	Type	Contrainte	Description
newConversationRequirePolicyAccept	booléen		Exiger le consentement à la politique de confidentialité avant de démarrer une nouvelle conversation
humanSupportRequirePolicyAccept	booléen		Exiger le consentement à la politique de confidentialité avant d'envoyer le formulaire de support humain
leadCollectionRequirePolicyAccept	booléen		Exiger le consentement à la politique de confidentialité avant d'envoyer le formulaire de collecte de leads
liveChatRequirePolicyAccept	booléen		Exiger le consentement à la politique de confidentialité avant de démarrer une session de chat en direct
newConversationConsentDescription	chaîne		Texte d'introduction pour l'écran de consentement au début de la conversation
privacyPolicyConsentCheckboxLabel	chaîne		Libellé à côté de la case à cocher de consentement (contient généralement un lien vers la politique de confidentialité)

§ whiteLabel

Champ	Type	Contrainte	Description
hideRoboAssistLogo	booléen	fonctionnalité White Label ; soumise aux limites du compte	Masquer le logo ChatLab par défaut dans le pied de page
whitelabelLogoLink	chaîne	fonctionnalité White Label ; soumise aux limites du compte	URL vers laquelle pointe le logo personnalisé de pied de page
assignToCustomDomain	booléen	conditionné par la fonctionnalité CUSTOM_DOMAIN	Héberger le chat sur le domaine personnalisé configuré
whitelabelLogoUrl	chaîne	lecture seule	URL publique complète du logo White Label ; pour la modifier, importez un nouveau fichier via la partie multipart whitelabel_logo

Multipart sur 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

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

§ voice

Champ	Type	Contrainte	Description
inputEnabled	booléen		Permettre au visiteur de dicter des messages (reconnaissance vocale)
conversationEnabled	booléen	nécessite la fonctionnalité vocale sur l'abonnement	Activer les conversations vocales complètes
voiceId	chaîne	ID vocal spécifique au fournisseur (ex. alloy)	Voix synthétique utilisée
model	chaîne	ex. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modèle vocal. Facturé à la minute, les tarifs varient selon le modèle
turnDetection	chaîne	spécifique au fournisseur	Mode de gestion des tours de parole
audioPrompt	chaîne		Prompt système supplémentaire utilisé uniquement pour les tours de parole vocaux
welcomeMessage	chaîne		Phrase d'introduction énoncée à l'oral
language	chaîne	code langue	Langue vocale principale
additionalLanguages	chaîne	codes de langue séparés par des virgules	Langues supplémentaires acceptées par l'agent vocal
maxDurationSeconds	entier		Limite stricte imposée sur une conversation vocale individuelle
maxDurationMessage	chaîne		Message affiché lorsque la limite est atteinte

§ multilingual

Champ	Type	Contrainte	Description
enabled	booléen		Interrupteur du mode multilingue
mode	chaîne	AUTODETECT ou FIXED_LIST	Façon dont le bot choisit la langue de réponse
baseLanguage	chaîne	code langue	Langue dans laquelle les textes propres au bot sont rédigés
languages	chaîne	codes de langue séparés par des virgules	Langues proposées au visiteur
knowledgeLanguageMode	chaîne	NONE, MAIN, ou DYNAMIC	Traitement des connaissances rédigées dans d'autres langues
knowledgeLanguageFallback	chaîne	code langue	Langue utilisée lorsqu'aucune correspondance n'est trouvée

§ advanced

Champ	Type	Contrainte	Description
model	chaîne	soumis aux limites du compte ; voir « Modèles de texte IA » ci-dessus	Identifiant du LLM (ex. 5.6-LUNA)
temperature	décimal	0.0-1.0	Température d'échantillonnage (correspond au curseur dans l'interface)
chatContextSize	entier	∈ {8000, 16000, 32000} ; ajusté automatiquement à la limite de votre compte	Budget de contexte configuré, comprenant les instructions, l'historique et les connaissances
botMessagesLimit	entier long	0 ou multiple de 1000 (ex. 1000, 2000, 10000)	Plafond mensuel de crédits de messages du bot (0 = aucun plafond additionnel par bot ; le budget du compte s'applique toujours)
internalLocale	chaîne	code de paramètres régionaux sous la forme ll_CC	Paramètres régionaux pour les libellés de l'interface du widget (distinct de role.language)
productsViewEnabled	booléen		Si true, affiche les cartes d'offre e-commerce (Offer Cards) dans le chat
includeProductsInKnowledgeBase	booléen		Si 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 éléments qui sont délibérément exclus de cette version de la Management API :

• Entraînement et suppression - ces points de terminaison ne permettent pas de lister l'ensemble des bots, de gérer les jeux de données d'entraînement ni de supprimer des bots. Utilisez l'application pour ces flux de travail.
• Onglet Flow - l'éditeur visuel de flux de conversation Flow Editor (étapes et transitions). Non disponible via la Management API.
• Onglet Actions - intégrations e-commerce / de réservation gérées, AI Search et fonctions API personnalisées. L'appel d'outils (tool calling) n'a 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 via leadCollection.customFormId et humanSupport.customFormId.
• Icônes personnalisées d'ouverture / fermeture du chat - customLauncherIconVisible, openChatIcon, closeChatIcon. L'API n'expose que les parties multipart principales 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 disponible, via security.countryFilterMode.

Endpoints

POST /v1/management/bots

Créez 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 ou un 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 de wrapper data)
• Les fichiers (avatar / logo) peuvent être importés ultérieurement via une deuxième requête PATCH en utilisant le mode B

Mode B - multipart/form-data (à utiliser pour importer des fichiers dans la même requête) :

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

Seul name est obligatoire dans le JSON ; tous les autres champs reprennent la valeur par défaut définie par l'assistant de l'interface d'administration.

Exemple de corps de requête

Il s'agit du JSON data maximal, avec chaque section renseignée. N'envoyez que les sections qui vous intéressent ; tout le reste prend des 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

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

• name - obligatoire, 150 caractères max
• advanced.temperature - entre 0.0 et 1.0
• chatMemory.summariesToKnowledgeRatio - entier entre 10 et 90 (pourcentage, pas de 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - entre 0 et 500
• appearance.footerMarkdown - 255 caractères max
• humanSupport.enabled=true nécessite que humanSupport.email soit défini
• leadCollection.enabled=true nécessite qu'au moins l'un des deux, leadCollection.emailEnabled ou leadCollection.phoneEnabled, soit défini sur true ; le canal activé requiert également son libellé, en plus de leaveDetailsMessage et thankYouMessage
• advanced.chatContextSize est limité à la taille de contexte maximale prise en charge par le compte. Ne partez pas du principe que les autres champs numériques sont automatiquement ajustés.

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.

Exemple de corps de réponse (201)

Même format que la requête, avec en plus le bloc en lecture seule meta et le champ à usage unique apiKey au niveau racine. 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.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"
}

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 clé en clair n'est affichée qu'une seule fois et ne pourra plus être récupérée ultérieurement 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_..."

Exemple de corps de réponse (200)

Même structure que la réponse POST, sans le champ à usage 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 et le logo White Label actuels sont présentés sous forme d'URL complètes en lecture seule (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - basées sur les mêmes protocole, hôte et chemin de contexte que ceux ayant servi cette requête. Récupérez les octets en effectuant une requête GET directement sur ces URL ; pour remplacer l'un ou l'autre fichier, 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.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"
  }
}

Cloner un bot

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

1. Récupérer le bot source avec GET.

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

2. Supprimer le bloc de premier niveau meta. L'objet meta (id, createdAt, updatedAt) est géré par le serveur et en lecture seule - le laisser dans le corps POST ne pose pas de problème (le serveur l'ignore), mais le supprimer rend votre intention explicite et garde le payload propre. Vous pouvez éventuellement modifier name pour distinguer le clone de la source.

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

3. Envoyer le corps nettoyé avec POST pour créer le clone. Consultez la référence POST /v1/management/bots ci-dessus pour 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 nouveau meta.id du bot ainsi qu'une clé apiKey fraîchement générée (la clé Bot Talk du clone). La valeur en texte brut de apiKey est renvoyée uniquement lors de cette réponse de création - copiez-la avant de fermer le corps de réponse ; il sera impossible de la récupérer plus tard.

Cette opération copie les paramètres pris en charge, pas un chatbot entièrement entraîné. Le contenu d'entraînement, l'historique des conversations, les intégrations/actions, le Flow et les définitions de formulaires ne sont pas clonés par ces points de terminaison. Configurez-les séparément dans l'application.

Avertissements supplémentaires :

• 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 logo White Label sur le clone, téléchargez les octets depuis les URL sources et importez-les sous forme de parties multipart avatar / whitelabel_logo - soit lors du POST de création (Mode B), soit via 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 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é sous la valeur null) reste inchangé. La sémantique de mise à jour partielle s'applique par champ au sein d'une section envoyée.

Deux Content-Types équivalents sont acceptés (identique à POST) :

Mode A - JSON brut (recommandé pour mettre à jour uniquement les paramètres) :

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

Mode B - multipart/form-data (à utiliser pour importer des 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 fichier avatar (facultative) - remplace l'avatar
• Partie fichier whitelabel_logo (facultative) - remplace le logo White Label (s'applique uniquement si votre compte inclut la fonctionnalité White Label)

Ces trois parties sont facultatives lors d'un PATCH, mais au moins une doit être présente pour que l'appel soit utile.

Exemple de corps de requête (plusieurs sections)

Tout champ accepté par POST /v1/management/bots peut également être envoyé ici. L'exemple ci-dessous illustre plusieurs sections, mais pas tous les champs pris en charge ; 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) laisse la valeur enregistrée inchangée.

{
  "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 champ unique 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 réponse (200)

Même structure que GET /v1/management/bots/{bot_id} - la configuration complète du bot après application du patch, incluant 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 montre la réponse après application du patch complet Exemple de corps de requête (plusieurs sections) ci-dessus au bot de l'exemple GET - les champs modifiés affichent les nouvelles valeurs, les champs intacts sont conservés et meta.updatedAt est incrémenté.

{
  "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 réponse (200)

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

• subscriptionType est un identifiant en minuscules du plan actuel du compte (your-plan-id est un placeholder illustratif). Les forfaits proviennent d'un catalogue dynamique, l'ensemble exact des identifiants peut donc évoluer avec le temps au fil des ajouts ou renommages de forfaits - traitez ceci comme une chaîne opaque, non comme une énumération fixe.
• messages.used / limit / remaining représentent les crédits de messages du mois civil en cours, réinitialisés le premier jour du mois et non le jour de renouvellement de l'abonnement. Ils sont pondérés par crédits et ne correspondent pas à un simple décompte brut de réponses.
• bots.used / limit / remaining décomptent les bots possédés, y compris les bots en pause, par rapport à la limite totale 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 la 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.