Management API

Panoramica della Management API

La Management API è destinata alle operazioni di back-office che non prevedono l'invio di messaggi di chat:

• creare un bot a livello programmatico con POST /v1/management/bots
• leggere un bot specifico di tua proprietà con GET /v1/management/bots/{bot_id}
• aggiornare un bot specifico con PATCH /v1/management/bots/{bot_id}
• leggere l'utilizzo dell'abbonamento con GET /v1/usage

Le chiavi Management sono associate al tuo account, non a un bot particolare. Sono tenute volutamente separate dalle chiavi Bot Talk, in modo che una chiave di chat compromessa non possa modificare i tuoi bot o leggere i tuoi dati di fatturazione.

URL di base

https://api.chatlab.com/aichat

Tutti gli endpoint descritti in questo articolo sono relativi a questo URL di base.

Per iniziare

1. Apri l'applicazione di amministrazione e vai su Account Settings > Management API (Impostazioni account > Management API).
2. Fai clic su Create Management Key (Crea chiave Management), assegnale un nome, imposta facoltativamente la whitelist degli IP e il rate limit, quindi invia.
3. Copia la chiave completa dalla finestra modale di conferma. Il testo in chiaro viene mostrato una sola volta.

Una chiave ha un formato simile a mk_abcdefghijklmnopqrstuvwxyz012345. Il prefisso mk_ la distingue dalle chiavi Bot Talk (ck_).

Autenticazione

Authorization: Bearer mk_abcdefghijklmnopqrstuvwxyz012345

L'invio di una chiave mk_ a /v1/chat (o a qualsiasi altro endpoint di Bot Talk) restituisce 403 key_type_not_allowed. L'invio di una chiave ck_ a /v1/management/* restituisce lo stesso errore.

Limiti

• Massimo 5 chiavi Management API attive per utente
• Massimo 10 richieste al minuto per chiave (token bucket, capacità 10, ricarica graduale di circa 1 token ogni 6 secondi). Configurabile al ribasso al momento della creazione: impostando un valore rateLimitPerMinute inferiore, il limite massimo scende e la frequenza di ricarica si adatta di conseguenza.

Autorizzazioni

Ciascuna chiave Management include un qualsiasi sottoinsieme delle tre autorizzazioni indicate di seguito. Al momento della creazione è necessario selezionarne almeno una; in caso contrario, la richiesta viene rifiutata con l'errore 400 invalid_request_error. La chiamata a un endpoint con una chiave priva dell'autorizzazione necessaria restituisce 403 insufficient_permissions.

• bot_read - richiesta per GET /v1/management/bots/{bot_id}
• bot_management - richiesta per POST /v1/management/bots e PATCH /v1/management/bots/{bot_id}
• usage - richiesta per GET /v1/usage

Struttura del corpo: sezioni nidificate che riflettono le schede dell'interfaccia di amministrazione

POST e PATCH accettano un corpo JSON suddiviso in 13 sezioni. Ciascuna sezione corrisponde a una sottoscheda nella barra laterale delle impostazioni del bot nell'app di amministrazione, in modo che le chiavi JSON e le schede visibili siano allineate: se modifichi consent.humanSupportRequirePolicyAccept tramite API, vedrai cambiare la stessa voce nella scheda Consent & Privacy (Consenso e privacy) nell'app di amministrazione.

• role - persona del bot, prompt non elaborato, lunghezza della risposta, lingua, contesto del sito web / dell'azienda (scheda Role & Behavior - Ruolo e comportamento)
• conversation - messaggio di benvenuto, perfezionamento della query, continuità della conversazione, selettore di valutazione + tooltip, contenuto delle domande suggerite + follow-up dinamici (scheda Chat Conversation - Conversazione chat)
• chatMemory - selettore della memoria di chat, prompt per i riepiloghi, allocazione del contesto (scheda Summaries & Memory - Riepiloghi e memoria)
• appearance - colori, testi, dimensioni, CSS personalizzato, schermata di benvenuto, stile delle domande suggerite, comportamento di apertura automatica, simulazione della digitazione umana, markdown del piè di pagina (scheda Appearance - Aspetto)
• humanSupport - modulo di contatto umano (scheda Human Contact Form - Modulo di contatto umano)
• leadCollection - modulo di acquisizione lead (scheda Lead Collection - Acquisizione lead)
• liveChat - passaggio alla live chat (scheda Live Chat)
• consent - tutti e quattro i selettori di consenso all'informativa sulla privacy più il testo della schermata di consenso (scheda Consent & Privacy - Consenso e privacy)
• whiteLabel - nascondi logo, link al logo personalizzato, hosting su dominio personalizzato (scheda Whitelabel)
• security - domini consentiti, filtro antispam, limiti di frequenza per le conversazioni (scheda Security - Sicurezza)
• voice - input vocale e conversazioni vocali: modello, voce, lingue, prompt, limite di durata (scheda Voice Conversation - Conversazione vocale)
• multilingual - modalità multilingue, lingua di base, lingue offerte, gestione della lingua della knowledge base (scheda Languages - Lingue)
• advanced - modello LLM, temperatura, dimensione del contesto, limite di messaggi del bot, impostazioni locali interne, Offer Cards (scheda Model & Advanced - Modello e impostazioni avanzate)

Solo name si trova al livello principale, poiché identifica il bot anziché appartenere a una singola scheda.

La barra laterale delle impostazioni del bot include attualmente 15 sottoschede e 13 di queste corrispondono alle sezioni sopra indicate. Le due sottoschede che non hanno una sezione corrispondente sono Flow (Flusso) e Actions (Azioni), entrambe descritte di seguito nella sezione "Non incluso nell'ambito dell'API". Le 13 che corrispondono sono Appearance, Chat Conversation, Role & Behavior, Human Contact Form, Lead Collection, Live Chat, Whitelabel, Consent & Privacy, Security, Model & Advanced, Summaries & Memory, Voice Conversation e Languages.

Il corpo della richiesta e il corpo della risposta condividono la stessa struttura. La risposta include due elementi aggiuntivi:

• meta - di sola lettura: ID del bot e timestamp. Rimuovilo per trasformare una risposta GET in un corpo POST valido.
• apiKey - presente solo al momento della creazione: la chiave Bot Talk API generata per il nuovo bot.

Due campi all'interno della struttura condivisa sono di sola lettura: vengono restituiti nella risposta e ignorati se tenti di inviarli con POST/PATCH:

• appearance.avatarUrl - URL pubblico completo dell'immagine dell'avatar del bot (ad es. https://api.chatlab.com/aichat/content/avatar_xyz.png). Esegui una GET direttamente su di esso per scaricare i byte. Per modificarlo, carica un nuovo file tramite la parte multipart avatar (vedi PATCH).
• whiteLabel.whitelabelLogoUrl - URL pubblico completo del logo dell'intestazione in modalità white-label. Segue la stessa logica di avatarUrl. Per modificarlo, carica un nuovo file tramite la parte multipart whitelabel_logo (vedi PATCH).

Entrambi gli URL utilizzano lo schema + host + percorso di contesto della richiesta corrente; pertanto, su un dominio personalizzato in white-label, verranno restituiti con radice su quel dominio (ad es. https://api.acme.com/aichat/content/...).

Invia null per una sezione per ignorarla in un'operazione PATCH; invia null per un campo all'interno di una sezione per ignorare quel singolo campo. Il valore null a livello di campo non cancella mai un valore salvato: significa semplicemente "non modificare".

Ruolo e costruzione del prompt

Il prompt di sistema effettivamente ricevuto dall'LLM viene costruito in uno dei due modi seguenti, a seconda del valore di role.role. Sapere quale ramo stai utilizzando ti permette di capire quali campi sono rilevanti e quali vengono salvati ma ignorati.

Ramo A - role.role è CUSTOMER_SUPPORT, SALES o LEAD_COLLECTION_AGENT (basato su modello predefinito)

Il backend compone il prompt a partire da un modello integrato e ignora del tutto role.rawPrompt (il valore viene comunque salvato sul bot, ma non viene utilizzato). Il modello incorpora:

• role.role - etichetta del ruolo (ad es. "Customer Support") e istruzioni specifiche del ruolo aggiunte automaticamente
• name - nome del bot, inserito nella frase iniziale
• role.language - "Auto Detect" imposta il bot per seguire la lingua dell'utente; qualsiasi altro valore (ad es. "English", "Polish") diventa "Output in {language}, unless user uses another language"
• role.responseLength - mappato su un conteggio di parole indicativo: Concise ≈ 50 parole, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - facoltativo; se non vuoto, viene aggiunto come "for the users of the website {url}"
• role.companyDescription - facoltativo; se non vuoto, viene anteposto come paragrafo aggiuntivo prima delle istruzioni del ruolo

Questo è il ramo consigliato per la maggior parte dei bot: offre un comportamento ottimizzato per il ruolo e vincoli di sicurezza inclusi.

Ramo B - role.role è CUSTOM (prompt fornito dal chiamante)

Il backend utilizza role.rawPrompt esattamente così com'è per l'intero prompt di sistema. I campi responseLength, language, websiteAddress e companyDescription vengono memorizzati ma non inseriti nel prompt: se desideri che influiscano sul comportamento del bot, devi includerli direttamente nel testo di rawPrompt. Inoltre, non vengono aggiunti vincoli di sicurezza o indicazioni di tono specifici per il ruolo: il controllo del prompt è interamente tuo.

Utilizza CUSTOM solo quando il prompt basato su modello predefinito non è adatto al tuo caso d'uso (ad es. se necessiti di una persona altamente specifica per il tuo settore, di vincoli di sicurezza personalizzati o di un formato di output non standard).

Campi enum / a set chiuso

Diversi campi accettano solo una serie fissa di valori stringa. L'invio di qualsiasi valore esterno all'elenco viene rifiutato con 400 validation_failed e il percorso del campo specificato in error.param. I valori fanno distinzione tra maiuscole e minuscole.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nome completo in inglese della lingua presente nel menu a discesa dell'amministrazione, ad es. Auto Detect, English, Polish, Spanish, German, French, Italian, Portuguese, Dutch, Russian, Chinese (Simplified), Japanese, Arabic, Hindi e circa altre 80. Il valore viene memorizzato così com'è e inserito nel modello del prompt; pertanto, i codici ISO a due lettere (en, pl) e altri valori non presenti nell'elenco non vengono rifiutati dall'API, ma producono un'istruzione scorretta come "Output in en, unless...". Se omesso al momento della creazione, il valore predefinito è Auto Detect.
• advanced.model - consulta la sezione "Modelli di testo AI" più avanti; l'insieme dei modelli selezionabili dipende dai limiti del tuo account e qualsiasi valore non utilizzabile dal tuo account restituirà l'errore 400 invalid_parameter
• advanced.chatContextSize - 8000, 16000, 32000. Soggetto ai limiti del tuo account; i valori superiori vengono ridotti automaticamente al limite massimo consentito
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - selettore booleano. true impone all'utente di compilare il modulo lead prima di avviare una conversazione; false consente all'IA di decidere quando mostrare il modulo (impostazione predefinita).

Campi strutturati e intervalli

Campi che sembrano semplici stringhe o numeri, ma che in realtà presentano strutture, intervalli o comportamenti specifici nell'interfaccia di amministrazione da tenere in considerazione.

• advanced.temperature - l'intervallo accettato va da 0.0 a 1.0, corrispondente al cursore nell'interfaccia di amministrazione. I valori esterni a questo intervallo vengono rifiutati con 400 validation_failed.

• chatMemory.summariesToKnowledgeRatio - percentuale intera, da 10 a 90 con incrementi di 10. Controlla la porzione di contesto della chat riservata ai riepiloghi storici del cliente rispetto al resto (knowledge base, conversazione corrente, istruzioni). Valore predefinito 50. I valori non compresi tra 10 e 90 vengono rifiutati con 400 validation_failed. Si applica solo quando chatMemory.enabled=true E chatMemory.summaryConversationsEnabled=true.

• liveChat.schedule - JSON codificato come stringa, non un oggetto JSON nidificato nella trasmissione dati. Il server archivia la stringa non elaborata così com'è; l'interfaccia di amministrazione ne esegue il parsing lato client durante il rendering dell'editor degli orari. Una volta analizzata, la stringa è strutturata con una voce per ciascun giorno della settimana più una chiave timezone:

  • ciascuna chiave del giorno della settimana (monday-sunday) è mappata su {enabled: boolean, from: "H:MM", to: "H:MM"} in formato 24 ore
  • timezone è il nome di un fuso orario IANA (ad es. "Europe/Warsaw", "America/New_York")

  Esempio di valore (nota le virgolette esterne e le virgolette interne con escape: si tratta di un unico campo stringa, non di un oggetto nidificato):

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

  Al di fuori degli orari indicati, al visitatore viene mostrato liveChat.outOfHoursMessage e il passaggio alla chat dal vivo viene bloccato. La convalida della struttura interna viene eseguita solo lato client nell'interfaccia di amministrazione: un JSON non valido o chiavi sconosciute vengono accettati dall'API come semplice stringa e si manifesteranno come errore di rendering solo in un secondo momento, quando un operatore aprirà il bot nell'amministrazione. Convalida la struttura dal tuo lato prima dell'invio.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - brevi etichette visualizzate sui pulsanti 👍 / 👎 accanto a ogni risposta dell'IA quando conversation.conversationRatingEnabled=true. I testi predefiniti sono "I like the response" / "I don't like the response". Visibili agli utenti finali.

• whiteLabel.hideRoboAssistLogo - funzionalità White Label, soggetta ai limiti del tuo account. Nasconde la dicitura "Powered by ChatLab" nel piè di pagina. Se il tuo account non include le funzioni White Label, il valore viene memorizzato ma ignorato e il piè di pagina viene sempre visualizzato.

• whiteLabel.whitelabelLogoLink - funzionalità White Label, soggetta ai limiti del tuo account. URL di destinazione del clic per il logo personalizzato quando hideRoboAssistLogo=true e un file di logo personalizzato è stato caricato tramite la parte multipart whitelabel_logo.

• appearance.simulateHumanTypingDelay - secondi (non millisecondi), numero intero 0-200. Pausa tra i singoli messaggi consecutivi del bot quando simulateHumanTyping=true. Valore predefinito 5.

• appearance.autoOpenChatDelaySeconds - secondi, numero intero. Tempo di attesa prima dell'apertura automatica del widget quando autoOpenChat=true e autoOpenChatDelay=true.

• advanced.internalLocale - codice di impostazione regionale IETF nel formato ll_CC (con trattino basso, NON ll-CC con il trattino). I valori accettati provengono da un elenco fisso di circa 95 impostazioni locali: 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 e molti altri. L'invio di un codice di sole due lettere ("en") o nel formato BCP-47 ("en-US") non è consentito dall'elenco. Valore predefinito en_US. Questa è l'impostazione locale utilizzata per la formattazione di date e numeri negli elementi visivi del widget, distinta da role.language (la lingua delle risposte del bot).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - numeri interi (invia come numeri JSON, ad es. 30, non "30"). Il valore 0 disattiva il rate limit per IP. Quando è diverso da zero, il widget applica un limite di N messaggi per la durata indicata in secondi prima di mostrare security.talkMessagesRateLimitHitMessage al visitatore.

• advanced.botMessagesLimit - numero intero (numero JSON, ad es. 1000). Il valore 0 indica "nessun limite"; altrimenti deve essere un multiplo di 1000 (1000, 2000, 10000, ...). Valori come 100 o 1500 vengono rifiutati con 400 validation_failed. Il valore viene inoltre limitato automaticamente al tetto massimo previsto dal tuo account.

Modelli di testo AI (advanced.model)

Invia il valore API esatto (colonna a sinistra tra apici). Il nome visualizzato nell'interfaccia di amministrazione è indicato tra parentesi. I limiti del tuo account stabiliscono quali modelli sono selezionabili; l'invio di un modello non utilizzabile dal tuo account restituisce l'errore 400 invalid_parameter. L'impostazione predefinita per i nuovi bot è 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)

Informazioni di riferimento sui campi (schema completo della richiesta)

Ogni campo inviato in rete, con il rispettivo tipo, vincolo e descrizione sintetica. Semantica PATCH: qualsiasi campo omesso (o inviato come null) lascia inalterato il valore memorizzato. La stessa struttura viene utilizzata per la risposta (senza il contenuto binario multipart; con in più il blocco di sola lettura meta in ogni risposta e apiKey solo nella risposta di creazione).

Livello principale

Campo	Tipo	Vincolo	Descrizione
name	string	max 150, obbligatorio in creazione	Nome visualizzato del bot
role	object		Vedi § role
conversation	object		Vedi § conversation
chatMemory	object		Vedi § chatMemory
appearance	object		Vedi § appearance
humanSupport	object		Vedi § humanSupport
leadCollection	object		Vedi § leadCollection
liveChat	object		Vedi § liveChat
consent	object		Vedi § consent
whiteLabel	object		Vedi § whiteLabel
security	object		Vedi § security
advanced	object		Vedi § advanced

Aggiunte presenti solo nella risposta:

• meta: { id, createdAt, updatedAt } - sola lettura.
• apiKey - stringa, presente solo nella risposta a POST /v1/management/bots - la chiave Bot Talk appena generata per il nuovo bot, restituita una sola volta.

§ role

Campo	Tipo	Vincolo	Descrizione
role	string (enum)	CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM	Preset del profilo; seleziona il template del prompt (vedi "Role and prompt construction")
language	string	nome completo della lingua in inglese (English, Polish, ...) o Auto Detect	Lingua principale inserita nel template del prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Livello di dettaglio desiderato per le risposte dell'IA
websiteAddress	string		Sito web utilizzato come contesto per il prompt
companyDescription	string		Descrizione dell'azienda utilizzata come contesto per il prompt
rawPrompt	string		Prompt di sistema personalizzato - utilizzato verbatim solo quando role=CUSTOM

§ conversation

Campo	Tipo	Vincolo	Descrizione
welcomeMessage	string		Primo messaggio mostrato al visitatore all'apertura
queryRefinementEnabled	boolean		Se impostato su true, perfeziona la domanda del visitatore prima del recupero RAG
conversationContinuityEnabled	boolean		Se impostato su true, i visitatori che ritornano riprendono la loro ultima conversazione
conversationRatingEnabled	boolean		Se impostato su true, mostra la valutazione con pollice su/giù sui messaggi del bot
positiveRatingTooltip	string		Tooltip sul pulsante di valutazione positiva
negativeRatingTooltip	string		Tooltip sul pulsante di valutazione negativa
suggestedQuestions	string		Domande suggerite / spunti di conversazione separati da a capo
dynamicSuggestedFollowups	boolean		Se impostato su true, l'IA propone suggerimenti di approfondimento dopo ogni risposta
dynamicFollowupsAutoIcons	boolean		Se impostato su true, l'IA sceglie automaticamente le icone emoji per i suggerimenti dinamici

§ chatMemory

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Selettore principale per la funzione di memoria della chat
summaryConversationsEnabled	boolean		Salva i riepiloghi per singola conversazione
conversationSummaryPrompt	string		Prompt personalizzato utilizzato per riassumere ogni conversazione
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Indica se utilizzare il prompt di riepilogo predefinito o personalizzato
clientSummaryPrompt	string		Prompt personalizzato utilizzato per riassumere il cliente attraverso le conversazioni
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt per il profilo del cliente predefinito o personalizzato
summariesToKnowledgeRatio	int	10-90, intervallo 10	% della finestra di contesto della chat allocata ai riepiloghi rispetto alla knowledge base RAG

§ appearance

Campo	Tipo	Vincolo	Descrizione
launcherColor	string (hex)		Colore di sfondo del launcher (icona della chat)
headerColor	string (hex)		Colore di sfondo dell'intestazione della chat
titleColor	string (hex)		Colore del titolo dell'intestazione della chat
subtitleColor	string (hex)		Colore del sottotitolo dell'intestazione della chat
clientMessageBubbleColor	string (hex)		Colore del fumetto del messaggio del visitatore
clientMessageTextColor	string (hex)		Colore del testo del messaggio del visitatore
responseMessageBubbleColor	string (hex)		Colore del fumetto di risposta del bot
responseMessageTextColor	string (hex)		Colore del testo di risposta del bot
chatSubheader	string		Slogan mostrato sotto il titolo della chat
senderPlaceholder	string		Testo segnaposto nel campo di inserimento del messaggio
resetConversationTooltip	string		Tooltip sul pulsante "reset conversation" (reimposta conversazione)
chatAlignment	string (enum)	∈ {left, right}	Lato dello schermo a cui si aggancia la chat
launcherBottomMargin	int	0-500	Distanza del launcher dal bordo inferiore (px)
launcherSideMargin	int	0-500	Distanza del launcher dal bordo laterale (px)
displayShadow	boolean		Ombreggiatura sotto il widget
customCss	string		CSS non elaborato inserito nell'iframe del widget
chatMessageLinkTarget	string (enum)	∈ {_blank, _self}	Modalità di apertura dei link all'interno dei messaggi del bot
minimizedDisplayMode	string (enum)	∈ {icon, minified}	Stato ridotto a icona: icona del launcher o barra di invio compatta
chatDesktopWidthPx	int		Larghezza del widget su desktop
chatDesktopHeightPx	int		Altezza del widget su desktop
chatMobileSizePercent	int		Dimensioni del widget su mobile come % del viewport
messageFontSize	int		Dimensione del font del testo del messaggio (px)
showChatbotBubblesDesktop	boolean		Mostra i fumetti teaser fluttuanti su desktop
showChatbotBubblesMobile	boolean		Mostra i fumetti teaser fluttuanti su mobile
chatbotBubblesDelaySeconds	int		Ritardo prima della comparsa dei fumetti teaser (secondi)
launcherIconFullSize	boolean		Mostra l'icona personalizzata del launcher da bordo a bordo anziché rientrata
welcomeScreenEnabled	boolean		Mostra la schermata di benvenuto invece di passare direttamente alla chat
welcomeScreenQuestionsLabel	string		Etichetta sopra le domande suggerite nella schermata di benvenuto
welcomeScreenHideHumanContactForm	boolean		Nasconde l'azione del modulo di contatto umano nell'intestazione mentre è visualizzata la schermata di benvenuto. Riappare dopo il primo messaggio del visitatore. Per i bot creati prima del 2026-09-02 il valore predefinito è true
welcomeScreenHideLiveChat	boolean		Nasconde l'azione di live chat nell'intestazione mentre è visualizzata la schermata di benvenuto. Riappare dopo il primo messaggio del visitatore. Per i bot creati prima del 2026-09-02 il valore predefinito è true
headerActionsLayout	string	DROPDOWN	Modalità con cui la live chat e il modulo di contatto umano vengono proposti nell'intestazione della chat: ICONS (un'icona separata per ciascuno) o DROPDOWN (raggruppati nel menu dell'intestazione). Per i bot creati prima del 2026-09-02 il valore predefinito è ICONS
stackSuggestedQuestions	boolean		Impila le domande suggerite verticalmente (anziché affiancate)
suggestedQuestionsFontSize	int		Dimensione del font dei pulsanti con le domande suggerite (px)
suggestedQuestionsTextColor	string (hex)		Colore del testo dei pulsanti con le domande suggerite
suggestedQuestionsBackgroundColor	string (hex)		Colore di sfondo dei pulsanti con le domande suggerite
autoOpenChat	boolean		Apertura automatica della chat su desktop
autoOpenChatOnMobiles	boolean		Apertura automatica della chat su mobile
autoOpenChatDelay	boolean		Utilizza un ritardo prima dell'apertura automatica
autoOpenChatDelaySeconds	int		Ritardo di apertura automatica (secondi)
simulateHumanTyping	boolean		Suddivide la risposta del bot in fumetti con animazione di digitazione
simulateHumanTypingDelay	int	0-200	Ritardo tra i messaggi a fumetto (secondi)
footerMarkdown	string	max 255	Markdown personalizzato visualizzato nel piè di pagina sotto la chat
avatarUrl	string	sola lettura	URL pubblico completo dell'avatar; per modificarlo, caricalo tramite la parte multipart avatar

Multipart su POST/PATCH: avatar (parte file). I corpi delle risposte GET omettono il contenuto del file - viene trasmesso solo l'URL.

§ humanSupport

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Selettore per il flusso Human Support (supporto umano)
email	string	obbligatorio (create-strict) quando enabled=true	Indirizzo che riceve le email per il supporto umano
dialogMessage	string		Messaggio di incoraggiamento mostrato sopra il modulo
thankYouMessage	string		Conferma visualizzata dopo l'invio
emailMessageSubjectTemplate	string		Template dell'oggetto per l'email inviata all'operatore
emailMessageContentTemplate	string		Template del corpo per l'email inviata all'operatore
emailPlaceholder	string		Segnaposto nel campo dell'email
messagePlaceholder	string		Segnaposto nell'area di testo del messaggio
emailWithConversationContent	boolean		Se impostato su true, include la trascrizione della conversazione nel corpo dell'email
customFormId	long	id di un modulo personalizzato esistente	Sostituisce il modulo di contatto integrato con un modulo personalizzato. null mantiene il modulo integrato
customFormMapping	string	stringa codificata in JSON	Associa i campi del modulo personalizzato ai campi email del supporto umano

requirePolicyAccept si trova in consent.humanSupportRequirePolicyAccept, non qui.

§ leadCollection

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Selettore per il modulo lead
nameEnabled	boolean		Raccoglie il nome
nameLabel	string		Etichetta nel campo del nome
emailEnabled	boolean		Raccoglie l'email
emailLabel	string	obbligatorio (create-strict) quando enabled=true E emailEnabled=true	Etichetta nel campo dell'email
phoneEnabled	boolean		Raccoglie il telefono
phoneLabel	string	obbligatorio (create-strict) quando enabled=true E phoneEnabled=true	Etichetta nel campo del telefono
leaveDetailsMessage	string	obbligatorio (create-strict) quando enabled=true	Messaggio che invita il visitatore a lasciare i propri recapiti
thankYouMessage	string	obbligatorio (create-strict) quando enabled=true	Conferma visualizzata dopo l'invio
requireBeforeNewConversation	boolean		Se true, il modulo deve essere inviato prima dell'avvio della chat; se false, l'IA decide quando mostrare il modulo
emailNotificationEnabled	boolean		Invia un'email al proprietario ogni volta che viene raccolto un lead
emailNotificationAddress	string		Destinatario della notifica (l'impostazione predefinita è l'email dell'account)
emailWithConversationContent	boolean		Se impostato su true, include la trascrizione della conversazione nella notifica

Regola cross-field create-strict: enabled=true richiede almeno uno tra emailEnabled o phoneEnabled. requirePolicyAccept si trova in consent.leadCollectionRequirePolicyAccept, non qui.

| customFormId | long | id di un modulo personalizzato esistente | Sostituisce il modulo lead integrato con un modulo personalizzato. null mantiene il modulo integrato | | customFormMapping | string | stringa codificata in JSON | Associa i campi del modulo personalizzato a nome / email / telefono |

§ liveChat

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Selettore per la funzione Live Chat
infoMessage	string		Messaggio esplicativo prima del passaggio all'operatore
startMessage	string		Messaggio visualizzato all'inizio della sessione live
endMessage	string		Messaggio visualizzato al termine della sessione live
nameLabel	string		Etichetta nel campo del nome nel pre-modulo della chat dal vivo
emailLabel	string		Etichetta nel campo dell'email nel pre-modulo della chat dal vivo
schedule	string	stringa codificata in JSON (selettori dei giorni feriali + from/to + timezone)	Orario di disponibilità della chat dal vivo - vedi "Structured fields and ranges" per la struttura esatta
outOfHoursMessage	string		Messaggio mostrato quando l'orario indica che il servizio non è attivo
closeModalMessage	string		Titolo del modale "chiudere la chat dal vivo?"
closeModalConfirmLabel	string		Etichetta del pulsante di conferma nel modale di chiusura
closeModalCancelLabel	string		Etichetta del pulsante di annullamento nel modale di chiusura
closeModalTooltipText	string		Tooltip sull'elemento per chiudere la chat
operatorHasJoinedLabel	string		Etichetta mostrata quando un operatore partecipa
operatorDidNotJoinInTimeLabel	string		Etichetta mostrata quando nessun operatore risponde entro il tempo limite
waitingForOperatorToJoinLabel	string		Etichetta mostrata durante l'attesa di un operatore
waitingForOperatorSeconds	int		Tempo massimo di attesa prima della presa in carico dell'operatore (secondi)
redirectToHumanSupportForm	boolean		Se impostato su true, reindirizza al modulo Human Support quando nessun operatore risponde
missedEmailEnabled	boolean	predefinito true	Invia un'email al proprietario del bot quando una richiesta di live chat non riceve risposta. Non impostato sui bot meno recenti, che viene interpretato come abilitato

requirePolicyAccept si trova in consent.liveChatRequirePolicyAccept, non qui.

§ consent

Campo	Tipo	Vincolo	Descrizione
newConversationRequirePolicyAccept	boolean		Richiede il consenso all'informativa sulla privacy prima di avviare una nuova conversazione
humanSupportRequirePolicyAccept	boolean		Richiede il consenso all'informativa sulla privacy prima di inviare il modulo di supporto umano
leadCollectionRequirePolicyAccept	boolean		Richiede il consenso all'informativa sulla privacy prima di inviare il modulo di raccolta lead
liveChatRequirePolicyAccept	boolean		Richiede il consenso all'informativa sulla privacy prima di avviare una sessione di chat dal vivo
newConversationConsentDescription	string		Testo introduttivo per la schermata di consenso all'inizio della conversazione
privacyPolicyConsentCheckboxLabel	string		Etichetta accanto alla casella di controllo del consenso (di solito contiene un link all'informativa sulla privacy)

§ whiteLabel

Campo	Tipo	Vincolo	Descrizione
hideRoboAssistLogo	boolean	funzionalità White Label; soggetta ai limiti dell'account	Nasconde il logo predefinito di ChatLab nel piè di pagina
whitelabelLogoLink	string	funzionalità White Label; soggetta ai limiti dell'account	URL a cui punta il logo personalizzato nel piè di pagina
assignToCustomDomain	boolean	vincolato dalla funzionalità CUSTOM_DOMAIN	Ospita la chat sul dominio personalizzato configurato
whitelabelLogoUrl	string	sola lettura	URL pubblico completo del logo white-label; per modificarlo, caricalo tramite la parte multipart whitelabel_logo

Multipart su POST/PATCH: whitelabel_logo (parte file). I corpi delle risposte GET omettono il contenuto del file - viene trasmesso solo l'URL.

§ security

Campo	Tipo	Vincolo	Descrizione
allowedDomains	string		Elenco separato da virgole dei domini autorizzati a incorporare il widget (vuoto = nessuna whitelist)
spamFilterEnabled	boolean		Abilita il filtro antispam per singolo bot sui messaggi in arrivo
countryFilterMode	string	BLACKLIST o WHITELIST	Modalità di interpretazione degli elenchi dei paesi. Gli elenchi stessi rimangono accessibili solo agli amministratori
talkMessagesRateLimit	int	>= 0; 0 disabilita	Numero massimo di messaggi utente consentiti nella finestra del limite di frequenza
talkMessagesRateLimitDurationSeconds	int	>= 0	Durata della finestra del limite di frequenza (secondi)
talkMessagesRateLimitHitMessage	string		Messaggio mostrato al visitatore quando viene raggiunto il limite di frequenza

§ voice

Campo	Tipo	Vincolo	Descrizione
inputEnabled	boolean		Consente al visitatore di dettare i messaggi (da voce a testo)
conversationEnabled	boolean	richiede la funzionalità vocale inclusa nel piano	Abilita conversazioni vocali complete
voiceId	string	id vocale specifico del provider (es. alloy)	Voce sintetica utilizzata per la riproduzione
model	string	es. GPT-REALTIME-MINI, GEMINI-LIVE, ELEVENLABS-*	Modello vocale. Fatturato al minuto, le tariffe variano a seconda del modello
turnDetection	string	specifico del provider	Modalità di gestione dei turni di parola
audioPrompt	string		Prompt di sistema aggiuntivo utilizzato solo per i turni vocali
welcomeMessage	string		Frase di apertura pronunciata a voce
language	string	codice lingua	Lingua principale per la voce
additionalLanguages	string	codici lingua separati da virgole	Lingue aggiuntive accettate dall'agente vocale
maxDurationSeconds	int		Limite massimo per una singola conversazione vocale
maxDurationMessage	string		Messaggio mostrato al raggiungimento del limite massimo

§ multilingual

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Selettore per la modalità multilingue
mode	string	AUTODETECT o una modalità basata su elenco fisso	Modalità di scelta della lingua di risposta da parte del bot
baseLanguage	string	codice lingua	Lingua in cui sono scritti i testi del bot
languages	string	codici lingua separati da virgole	Lingue offerte al visitatore
knowledgeLanguageMode	string		Gestione delle informazioni della knowledge base in altre lingue
knowledgeLanguageFallback	string	codice lingua	Lingua utilizzata quando non viene trovata alcuna corrispondenza

§ advanced

Campo	Tipo	Vincolo	Descrizione
model	string	soggetto ai limiti dell'account; vedi "AI text models" sopra	Identificatore LLM (es. 5-MINI)
temperature	decimal	0.0-1.0	Temperatura di campionamento (corrisponde al cursore nell'interfaccia utente)
chatContextSize	int	∈ {8000, 16000, 32000}; limitato automaticamente alla soglia massima del tuo account	Finestra di token per la cronologia della chat
botMessagesLimit	long	0 o multiplo di 1000 (es. 1000, 2000, 10000)	Numero massimo di risposte del bot per conversazione (0 = nessun limite)
internalLocale	string	codice locale nel formato ll_CC	Locale per le etichette dell'interfaccia del widget (distinto da role.language)
productsViewEnabled	boolean		Se impostato su true, mostra le Offer Cards di e-commerce all'interno della chat
includeProductsInKnowledgeBase	boolean		Se impostato su true, indicizza il catalogo prodotti come parte della knowledge base

Non inclusi nell'ambito dell'API

L'interfaccia utente di amministrazione presenta alcune aree che sono intenzionalmente escluse da questa versione della Management API:

• Scheda Flow (Flusso) - l'editor visivo di Conversation Flow (fasi e transizioni). Non esposto tramite la Management API.
• Scheda Actions (Azioni) - integrazioni gestite per e-commerce / prenotazioni, AI Search e funzioni API personalizzate. Il tool calling non ha mai fatto parte della Management API.
• Il builder dei moduli personalizzati stesso - la creazione e la modifica di moduli personalizzati non sono esposte. Tuttavia, puoi collegare un modulo esistente a un bot tramite leadCollection.customFormId e humanSupport.customFormId.
• Icone personalizzate di apertura / chiusura chat - customLauncherIconVisible, openChatIcon, closeChatIcon. L'API espone solo le parti multipart principali avatar e whitelabel_logo.
• Elenchi di indirizzi IP e paesi - le singole voci rimangono accessibili solo agli amministratori. Viene esposta solo la modalità di interpretazione, tramite security.countryFilterMode.

Endpoints

POST /v1/management/bots

Crea un nuovo bot. Vengono accettati due Content-Type equivalenti; scegli quello più comodo.

Modalità A - plain JSON (consigliata se non devi caricare un avatar / logo nella stessa richiesta):

• Content-Type: application/json
• Il corpo della richiesta è il JSON di configurazione del bot (nessun wrapper data)
• I file (avatar / logo) possono essere caricati in seguito tramite una seconda richiesta PATCH utilizzando la modalità B

Modalità B - multipart/form-data (da usare quando carichi file nella stessa richiesta):

• Content-Type: multipart/form-data; boundary=...
• Parte JSON data (obbligatoria, Content-Type: application/json) - configurazione del bot nella struttura nidificata descritta sopra
• Parte file avatar (facoltativa) - immagine dell'avatar del bot
• Parte file whitelabel_logo (facoltativa) - logo White Label (applicabile solo se il tuo account include la funzionalità White Label)

Nel JSON solo name è obbligatorio; tutti gli altri campi assumono lo stesso valore predefinito impostato dalla procedura guidata dell'interfaccia di amministrazione.

Corpo completo della richiesta

Questo è il JSON data massimale - con ogni sezione compilata. Invia solo le sezioni di tuo interesse; tutto il resto adotterà i valori predefiniti.

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

Regole di validazione con i rispettivi messaggi di errore:

• name - obbligatorio, massimo 150 caratteri
• advanced.temperature - compreso tra 0.0 e 1.0
• chatMemory.summariesToKnowledgeRatio - numero intero compreso tra 10 e 90 (percentuale, passo 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - compresi tra 0 e 500
• appearance.footerMarkdown - massimo 255 caratteri
• humanSupport.enabled=true richiede l'impostazione di humanSupport.email
• leadCollection.enabled=true richiede che almeno uno tra leadCollection.emailEnabled o leadCollection.phoneEnabled sia true; qualsiasi canale sia attivo richiede anche la rispettiva etichetta, oltre a leaveDetailsMessage e thankYouMessage
• I campi soggetti a limiti (advanced.chatContextSize, advanced.botMessagesLimit, ecc.) vengono ridotti automaticamente ai limiti del tuo account senza mostrare errori

I campi il cui valore è null sul server vengono omessi dal corpo JSON: la trasmissione trasporta solo campi con valori non nulli.

Corpo completo della risposta (201)

Stessa struttura della richiesta, più il blocco di sola lettura meta e il valore monouso apiKey al livello principale. Gli URL dei file di sola lettura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) vengono popolati dal server quando sono state caricate le parti multipart corrispondenti.

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

Il campo apiKey compare solo al momento della creazione: è la chiave Bot Talk appena generata e associata al nuovo bot. Il valore in chiaro viene mostrato una sola volta e non può essere recuperato successivamente tramite le API; salvalo immediatamente nei tuoi sistemi.

L'header di risposta Location contiene l'URL del nuovo bot (/v1/management/bots/{id}).

Esempi curl

Modalità A - plain JSON (la più semplice):

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

Modalità B - multipart con 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}

Restituisce la configurazione attuale di un bot di tua proprietà.

Esempio curl

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

Corpo completo della risposta (200)

Stessa struttura della risposta POST, senza il campo monouso apiKey. Il blocco meta è incluso. Restituisce 404 not_found_error se il bot non esiste o non appartiene al tuo account.

L'avatar e il logo White Label correnti vengono forniti come URL completi di sola lettura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl) - basati sullo stesso schema + host + context path che ha servito la richiesta. Recupera i file binari eseguendo direttamente una richiesta GET su tali URL; per sostituire uno dei file, caricane uno nuovo tramite la parte multipart avatar / whitelabel_logo con una richiesta PATCH. Questi campi URL vengono ignorati se inviati nel corpo di una richiesta.

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

Clonare un bot

Il corpo della richiesta di POST /v1/management/bots e il corpo della risposta di GET /v1/management/bots/{bot_id} condividono la stessa struttura, quindi la clonazione è una procedura in tre passaggi: recupera il bot di origine con una GET, rimuovi i campi identificativi gestiti dal server e invia il risultato con una POST.

1. Esegui la GET del bot di origine.

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

2. Rimuovi il blocco meta di primo livello. L'oggetto meta (id, createdAt, updatedAt) è gestito dal server ed è di sola lettura: lasciarlo nel corpo della richiesta POST non crea problemi (il server lo ignora), ma rimuoverlo rende esplicita l'intenzione e mantiene pulito il payload. Se lo desideri, modifica name in modo da distinguere il clone dall'originale.

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

3. Invia con POST il corpo ripulito per creare il clone. Consulta il riferimento a POST /v1/management/bots sopra per la struttura completa del payload e le regole di convalida.

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 risposta contiene il nuovo meta.id del bot e una apiKey appena generata (la chiave Bot Talk per il clone). Il testo in chiaro di apiKey viene restituito solo nella risposta di questa creazione: copialo prima di chiudere o ignorare il corpo della risposta; non potrà essere recuperato in seguito.

Due avvertenze:

• I file non vengono clonati. appearance.avatarUrl e whiteLabel.whitelabelLogoUrl sono di sola lettura e puntano ai file del bot di origine. Se hai bisogno dello stesso avatar o logo White Label sul clone, scarica i byte dagli URL di origine e caricali come parti multipart avatar / whitelabel_logo, tramite la POST di creazione (Modalità B) oppure con una successiva richiesta PATCH.
• Le chiavi Bot Talk non vengono clonate. Ogni bot ha il proprio gruppo dedicato di chiavi Bot Talk. La singola apiKey restituita dalla richiesta POST di creazione è l'unica generata automaticamente; crea eventuali chiavi aggiuntive dalla scheda API del bot, se necessario.

PATCH /v1/management/bots/{bot_id}

Aggiorna uno o più campi di un bot di tua proprietà. Vengono modificate solo le sezioni o i campi presenti nel JSON; tutto ciò che viene omesso (o inviato come null) rimane invariato. La semantica di aggiornamento parziale si applica per singolo campo all'interno di ciascuna sezione inviata.

Sono accettati due tipi equivalenti di Content-Type (come per POST):

Modalità A - JSON normale (consigliata quando si aggiornano solo le impostazioni):

• Content-Type: application/json
• Il corpo della richiesta è il JSON della patch (senza wrapper data)

Modalità B - multipart/form-data (da usare per caricare file):

• parte JSON data (facoltativa) - la patch. Inviala solo se desideri modificare i campi. Omettila del tutto se intendi soltanto caricare un avatar o un logo.
• parte file avatar (facoltativa) - sostituisce l'avatar
• parte file whitelabel_logo (facoltativa) - sostituisce il logo White Label (valido solo se il tuo account include la funzionalità di White Label)

Tutte e tre le parti sono facoltative su PATCH, ma almeno una deve essere presente affinché la chiamata abbia effetto.

Corpo completo della richiesta (struttura massimale)

Qualsiasi campo accettato da POST /v1/management/bots può essere inviato anche qui. L'esempio seguente mostra la struttura completa; in pratica invierai solo le chiavi che desideri modificare (vedi "Aggiornamento parziale minimo" più sotto): ogni chiave omessa (o inviata come null) lascerà invariato il valore già salvato.

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

Aggiornamento parziale minimo

Esegui la PATCH di un singolo campo inviando esattamente le chiavi che desideri modificare: tutto il resto viene preservato.

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

Esempi Curl

Modalità A - JSON normale (la più semplice):

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

Modalità B - multipart (per sostituire avatar / logo):

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

Modalità B - sostituzione del solo avatar (nessuna modifica ai campi):

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

Corpo della risposta (200)

Stessa struttura di GET /v1/management/bots/{bot_id}: la configurazione completa del bot dopo l'applicazione della patch, compreso il blocco meta. Nessun campo apiKey. Restituisce 404 not_found_error se il bot non esiste o non appartiene al tuo account.

L'esempio seguente mostra la risposta dopo aver applicato la patch descritta in Corpo completo della richiesta (struttura massimale) sopra al bot dell'esempio GET: i campi modificati riflettono i nuovi valori, i campi non toccati rimangono preservati e meta.updatedAt si aggiorna.

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

Legge l'utilizzo attuale dell'abbonamento per l'account proprietario della chiave Management.

Corpo della risposta (200)

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

• subscriptionType è l'identificatore in lettere minuscole del piano attuale dell'account (ad es. standard nell'esempio). I piani provengono da un catalogo dinamico, quindi l'elenco esatto degli identificatori può variare nel tempo con l'aggiunta o la rinomina dei piani: trattalo come una stringa opaca, non come un enum fisso.
• messages.used / limit / remaining rappresentano i crediti messaggio del periodo di fatturazione corrente.
• bots.used / limit / remaining conteggiano i bot attivi rispetto al limite di bot del tuo account.

Header di rate limit

Le risposte che raggiungono la fase di rate limit (ovvero superano l'autenticazione e la whitelist IP) includono:

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

• X-RateLimit-Limit - il limite per chiave effettivamente applicato a questa chiamata (10 per impostazione predefinita, oppure il tuo rateLimitPerMinute configurato se inferiore).
• X-RateLimit-Remaining - token rimasti nel bucket subito dopo questa chiamata.
• X-RateLimit-Reset - secondi Unix epoch in cui il prossimo token diventa disponibile (non un reset completo del bucket; il bucket si riempie continuamente). Quando il bucket è pieno, corrisponde all'ora corrente.

Sulle risposte 429 rate_limit_exceeded, viene impostato anche Retry-After, espresso in secondi interi fino a quando non si libera almeno un token.

Gli errori pre-autenticazione (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) e 403 ip_not_whitelisted non contengono gli header X-RateLimit-* - il limitatore viene consultato solo dopo che l'autenticazione e i controlli IP hanno avuto successo.

Formato degli errori

Stessa struttura envelope di Bot Talk API:

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

Gli errori di convalida utilizzano code: "invalid_parameter" e antepongono il percorso del campo non valido al messaggio, in modo che la sezione interessata sia facile da individuare:

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

I valori non validi per campi enum / a set chiuso (ad es. chatMemory.clientSummaryPromptType = "BOGUS") includono il percorso del campo, il valore rifiutato e l'elenco dei valori consentiti:

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

Risorse correlate

Per gli endpoint di conversazione e lo streaming SSE, consulta Bot Talk API.