Management API

Panoramica della Management API

La Management API serve per le operazioni di back-office che non comportano l'invio di messaggi di chat:

• creare un bot a livello di programmazione 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 di gestione sono associate al tuo account, non a un bot specifico. Vengono tenute deliberatamente separate dalle chiavi Bot Talk, in modo che una chiave di chat compromessa non possa modificare i tuoi bot né leggere i tuoi dati di fatturazione.

URL di base

https://api.chatlab.com/aichat

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

Primi passi

1. Apri l'app di amministrazione e vai su Account Settings > Management API (Impostazioni account > Management API).
2. Fai clic su Create Management Key (Crea chiave di gestione), assegna un nome, imposta facoltativamente la whitelist degli IP e il limite di frequenza, quindi conferma.
3. Seleziona solo le autorizzazioni necessarie per la tua integrazione e copia la chiave completa dalla finestra modale di conferma. Il testo in chiaro viene mostrato una sola volta.
4. Salvala sul tuo server, non nel codice del browser o in un repository pubblico. Effettua una richiesta di sola lettura come GET /v1/usage con l'autorizzazione usage per verificare l'accesso.
5. Revoca le chiavi inutilizzate o compromesse dalla pagina Management API.

Una chiave si presenta nel formato 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 progressiva di circa 1 token ogni 6 secondi). Configurabile al ribasso al momento della creazione: impostando un valore rateLimitPerMinute inferiore, il limite massimo diminuisce e la frequenza di ricarica si adatta di conseguenza.

Autorizzazioni

Ogni chiave di gestione include un sottoinsieme delle tre autorizzazioni seguenti. Al momento della creazione è necessario selezionarne almeno una; in caso contrario, la richiesta viene rifiutata con 400 invalid_request_error. La chiamata a un endpoint con una chiave priva dell'autorizzazione richiesta 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 body: sezioni nidificate che riflettono le schede dell'interfaccia di amministrazione

POST e PATCH accettano un body JSON suddiviso in 13 sezioni. Ciascuna sezione corrisponde a una scheda secondaria nella barra laterale Bot Settings dell'app di amministrazione, in modo che le chiavi JSON e le schede visibili coincidano: modificando consent.humanSupportRequirePolicyAccept tramite l'API, vedrai attivarsi lo stesso interruttore nella scheda Consent & Privacy (Consenso e privacy) dell'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 delle query, continuità della conversazione, selettore di valutazione + tooltip, contenuto delle domande suggerite + follow-up dinamici (scheda Chat Conversation [Conversazione in chat])
• chatMemory - selettore della memoria della chat, prompt di riepilogo, 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 [Raccolta lead])
• liveChat - passaggio alla chat dal vivo (scheda Live Chat)
• consent - tutti e quattro i selettori di consenso dell'informativa sulla privacy oltre al testo della schermata di consenso (scheda Consent & Privacy)
• whiteLabel - opzione per nascondere il logo, link al logo personalizzato, hosting su dominio personalizzato (scheda Whitelabel [White Label])
• security - domini consentiti, filtro antispam, limiti di frequenza per le conversazioni (scheda Security [Sicurezza])
• voice - input vocale e conversazioni vocali: modello, voce, lingue, prompt, durata massima (scheda Voice Conversation [Conversazione vocale])
• multilingual - modalità multilingue, lingua di base, lingue offerte, gestione della lingua della conoscenza (scheda Languages [Lingue])
• advanced - modello LLM, temperatura, dimensione del contesto, limite dei messaggi del bot, impostazioni internazionali interne, Offer Cards (scheda Model & Advanced [Modello e avanzate])

Tra le impostazioni modificabili, solo name si trova al livello principale, poiché identifica il bot anziché appartenere a una singola scheda.

La barra laterale Bot Settings include attualmente 16 schede secondarie, e 13 di queste corrispondono alle sezioni indicate sopra. Le tre schede secondarie senza una sezione corrispondente sono Flow, Actions e Forms, tutte e tre trattate nella sezione "Fuori dall'ambito dell'API" più avanti. Le 13 associate 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 body della richiesta e il body della risposta condividono la stessa struttura. La risposta aggiunge due elementi supplementari:

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

Due campi all'interno della struttura condivisa sono di sola lettura: vengono restituiti nella risposta ma vengono ignorati se si tenta 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). Effettua una richiesta GET diretta per scaricare i byte. Per modificarlo, carica un nuovo file tramite la parte multipart avatar (vedi PATCH).
• whiteLabel.whitelabelLogoUrl - URL pubblico completo del logo di intestazione in white-label. Segue lo stesso schema 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 white-label, vengono restituiti con la radice su quel dominio (ad es. https://api.acme.com/aichat/content/...).

Invia null per una sezione per saltarla in PATCH; invia null per un campo all'interno di una sezione per saltare quel singolo campo. Il valore null a livello di campo non cancella mai un valore memorizzato: significa solo "non modificare".

Ruolo e costruzione del prompt

Il prompt di sistema effettivamente ricevuto dall'LLM viene creato in uno di due modi a seconda 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 (guidato da modelli)

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

• 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 - associato a un conteggio parole indicativo: Concise ≈ 50 parole, Normal ≈ 100, Detailed ≈ 200
• role.websiteAddress - facoltativo; quando non è vuoto, viene aggiunto come "for the users of the website {url}"
• role.companyDescription - facoltativo; quando non è vuoto, viene inserito 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 linee guida di sicurezza già pronte.

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

Il backend utilizza role.rawPrompt come prompt del ruolo e aggiunge le indicazioni fisse della piattaforma sulla lunghezza della risposta. Questa impostazione è separata da role.responseLength: l'opzione Concise/Normal/Detailed non viene inserita per un ruolo CUSTOM. Allo stesso modo, language, websiteAddress e companyDescription vengono memorizzati ma non inseriti nel prompt di questo ruolo. Includi tu stesso in rawPrompt la lingua desiderata, l'obiettivo di lunghezza della risposta o il contesto aziendale. È anche possibile fornire istruzioni aggiuntive a runtime e contesto recuperato, perciò rawPrompt non costituisce l'intero input per il modello. Le istruzioni sul tono del ruolo predefinito non vengono aggiunte, ma la scelta di CUSTOM non rimuove tutte le istruzioni della piattaforma.

Usa CUSTOM solo quando il prompt basato su modelli non si adatta al tuo caso d'uso (ad es. se hai bisogno di una persona molto specifica per un determinato settore, di vincoli di sicurezza personalizzati o di un formato di output non standard).

Campi enum / a valori definiti

I campi enum e con vincoli rifiutano i valori non validi con 400 invalid_parameter. Gli altri campi sono stringhe semplici, anche nei casi in cui l'interfaccia utente propone un elenco predefinito. Usa la grafia documentata e convalida il tuo payload invece di dare per scontato che ogni stringa non supportata venga rifiutata.

• role.role - CUSTOMER_SUPPORT, SALES, LEAD_COLLECTION_AGENT, CUSTOM
• role.responseLength - Concise, Normal, Detailed
• role.language - nome completo della lingua in inglese dal menu a discesa dell'amministratore, 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 esattamente come indicato e inserito nel modello di prompt, perciò i codici ISO a due lettere (en, pl) e altri valori non presenti nell'elenco non vengono rifiutati dall'API, ma generano un'istruzione poco chiara come "Output in en, unless...". Il valore predefinito è Auto Detect se omesso in fase di creazione.
• advanced.model - vedi "Modelli di testo AI" di seguito. Si tratta di una stringa, non di un enum convalidato nello schema della richiesta; usa un valore supportato, non il nome arbitrario di un modello.
• advanced.chatContextSize - usa 8000, 16000 o 32000, come nell'interfaccia utente. I valori superiori al massimo dell'account vengono limitati automaticamente; il DTO non impone questo insieme di tre valori.
• chatMemory.clientSummaryPromptType - DEFAULT, CUSTOM
• chatMemory.conversationSummaryPromptType - DEFAULT, CUSTOM
• appearance.chatAlignment - left, right
• appearance.minimizedDisplayMode - icon, minified, pill
• appearance.chatMessageLinkTarget - _blank, _self
• leadCollection.requireBeforeNewConversation - selettore booleano. true obbliga l'utente a compilare il modulo per i lead prima di avviare una conversazione; false lascia che l'IA decida quando mostrare il modulo (impostazione predefinita).

Campi strutturati e intervalli

Campi che sembrano semplici stringhe o numeri, ma che presentano formati specifici, intervalli o particolarità dell'interfaccia utente di amministrazione da conoscere.

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

• chatMemory.summariesToKnowledgeRatio - percentuale intera, 10-90; l'interfaccia utente usa intervalli di 10, ma l'API accetta qualsiasi numero intero all'interno dell'intervallo. Valore predefinito: 50. Con la memoria abilitata e un contesto superiore a 8k, suddivide il budget tra conoscenza e memoria dopo aver riservato lo spazio per il prompt e la conversazione recente, senza considerare l'intero contesto del modello. A 8k questa impostazione non assegna alcun budget per i riepiloghi.

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

  • ogni chiave del giorno della settimana (monday-sunday) punta a {enabled: boolean, from: "H:MM", to: "H:MM"} in formato 24 ore
  • timezone è il nome di una zona IANA (ad es. "Europe/Warsaw", "America/New_York")

  Esempio di valore (nota le virgolette esterne e le virgolette interne con caratteri di escape: è un singolo campo stringa, non 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 avviene solo lato client nell'interfaccia di amministrazione: un JSON non valido o chiavi non riconosciute vengono accettati dall'API come semplice stringa e causeranno un errore di rendering quando un operatore aprirà successivamente il bot nel pannello di amministrazione. Convalida la struttura da parte tua prima dell'invio.

• conversation.positiveRatingTooltip / conversation.negativeRatingTooltip - brevi etichette mostrate sui controlli di valutazione della conversazione 👍 / 👎 quando conversation.conversationRatingEnabled=true. Il testo predefinito è "Mi piace la risposta" / "Non mi piace la risposta". Visibili agli utenti finali.

• whiteLabel.hideRoboAssistLogo - funzionalità White Label, soggetta ai limiti del tuo account. Nasconde la dicitura a piè di pagina "Powered by ChatLab". Se il tuo account non include l'opzione 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 ed è stato caricato un file di logo personalizzato tramite la parte multipart whitelabel_logo.

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

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

• advanced.internalLocale - codice IETF per lingua e regione 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 internazionali: 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 molte altre. L'invio di un solo codice a due lettere ("en") o nel formato BCP-47 ("en-US") non è consentito. Valore predefinito: en_US. Questa è la configurazione internazionale usata per la formattazione di date e numeri nell'interfaccia del widget, distinta da role.language (la lingua con cui il bot risponde nelle conversazioni).

• security.talkMessagesRateLimit / security.talkMessagesRateLimitDurationSeconds - numeri interi (da inviare come numeri JSON, ad es. 30, non "30"). Imposta il limite dei messaggi su 0 per disattivare questo limite basato sulla sessione. Se lo abiliti, specifica una durata positiva. Il backend applica un limite di N messaggi per sessione nell'arco della durata espressa in secondi prima di mostrare security.talkMessagesRateLimitHitMessage al visitatore.

• advanced.botMessagesLimit - numero intero (numero JSON, ad es. 1000). 0 indica che non è presente alcun limite aggiuntivo per il singolo bot, ferma restando l'applicazione del limite di crediti dell'account; in caso contrario, deve essere un multiplo di 1000 (1000, 2000, 10000, ...). Valori come 100 o 1500 vengono rifiutati con 400 invalid_parameter. Si tratta di un limite mensile di crediti per il bot, non di un conteggio di messaggi per conversazione. Il mapper non adatta questo valore al budget dell'account; l'utilizzo effettivo resta comunque vincolato dal budget totale dell'account.

Modelli di testo AI (advanced.model)

Usa l'identificatore esatto del modello restituito in advanced.model quando leggi un bot configurato con il modello desiderato in Settings > Model & Advanced (Impostazioni > Modello e avanzate). Il valore predefinito attuale in fase di creazione è 5.6-LUNA. Gli identificatori fanno distinzione tra maiuscole e minuscole e differiscono dai nomi visualizzati; ad esempio, 5.6-LUNA viene visualizzato come GPT 5.6-luna.

Il catalogo dei modelli cambia nel tempo. Non presumere che una stringa arbitraria o l'ID pubblico del modello di un fornitore sia supportato solo perché lo schema della richiesta accetta una stringa. Rileggi la configurazione salvata ed esegui i test sul chatbot ottenuto prima di pubblicarlo.

Riferimento dei campi (schema completo della richiesta)

Le sezioni e i campi supportati, con i relativi tipi e vincoli importanti. Semantica PATCH: qualsiasi campo omesso (o inviato come null) lascia inalterato il valore memorizzato. La stessa struttura viene utilizzata per la risposta (al netto dei contenuti binari multipart; con in più il blocco di sola lettura meta in ogni risposta e apiKey unicamente 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 personaggio; seleziona il modello di prompt (vedi "Role and prompt construction")
language	string	nome completo della lingua in inglese (English, Polish, ...) o Auto Detect	Lingua principale inserita nel modello di prompt
responseLength	string	∈ {Concise, Normal, Detailed}	Lunghezza desiderata della risposta dell'IA
websiteAddress	string		Sito web utilizzato per il contesto del prompt
companyDescription	string		Descrizione dell'azienda utilizzata per il contesto del prompt
rawPrompt	string		Prompt di sistema personalizzato - usato letteralmente solo quando role=CUSTOM

§ conversation

Campo	Tipo	Vincolo	Descrizione
welcomeMessage	string		Primo messaggio mostrato al visitatore all'apertura
queryRefinementEnabled	boolean		Se true, perfeziona la domanda del visitatore prima del recupero RAG
conversationContinuityEnabled	boolean		Se true, i visitatori che ritornano riprendono l'ultima conversazione
conversationRatingEnabled	boolean		Se true, mostra i comandi pollice su/giù per valutare la conversazione
positiveRatingTooltip	string		Descrizione comando (tooltip) sul pulsante di valutazione positiva
negativeRatingTooltip	string		Descrizione comando sul pulsante di valutazione negativa
suggestedQuestions	string		Domande suggerite / spunti di conversazione separati da a capo
dynamicSuggestedFollowups	boolean		Se true, l'IA suggerisce domande di approfondimento dopo ogni risposta
positiveRatingMessage	string		Messaggio mostrato dopo un feedback positivo
negativeRatingMessage	string		Messaggio mostrato dopo un feedback negativo
hideSuggestedQuestionsAfterFirstUse	boolean		Nascondi i suggerimenti statici dopo il loro utilizzo
dynamicFollowupsAutoIcons	boolean		Se true, l'IA assegna automaticamente icone emoji ai follow-up dinamici

§ chatMemory

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Interruttore generale per la funzione di memoria chat
summaryConversationsEnabled	boolean		Memorizza i riepiloghi per singola conversazione
conversationSummaryPrompt	string		Prompt personalizzato utilizzato per riepilogare ciascuna conversazione
conversationSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Specifica se utilizzare il prompt di riepilogo predefinito o personalizzato
clientSummaryPrompt	string		Prompt personalizzato utilizzato per creare il profilo del cliente tra le varie conversazioni
clientSummaryPromptType	string (enum)	∈ {DEFAULT, CUSTOM}	Prompt del profilo cliente predefinito vs personalizzato
summariesToKnowledgeRatio	int	10-90 (passo UI 10)	% del budget di conoscenza/memoria disponibile allocata ai riepiloghi per contesti superiori a 8k

§ appearance

Campo	Tipo	Vincolo	Descrizione
launcherLabelLine1	string	max 60	Prima riga di testo del launcher
launcherLabelLine2	string	max 60	Seconda riga di testo del launcher
launcherTextColor	string		Colore del testo del launcher
launcherDismissEnabled	boolean		Consenti la chiusura del launcher
widgetFontFamily	string	inter, system, nunito, lato, montserrat, poppins, source-serif, jetbrains-mono	Famiglia di caratteri del widget
chatDrawerEnabled	boolean		Abilita la presentazione a cassetto (drawer)
launcherColor	string (hex)		Colore di sfondo del launcher (icona chat)
headerColor	string (hex)		Colore di sfondo dell'intestazione della chat
titleColor	string (hex)		Colore del titolo nell'intestazione della chat
subtitleColor	string (hex)		Colore del sottotitolo nell'intestazione della chat
clientMessageBubbleColor	string (hex)		Colore del fumetto dei messaggi del visitatore
clientMessageTextColor	string (hex)		Colore del testo dei messaggi del visitatore
responseMessageBubbleColor	string (hex)		Colore del fumetto delle risposte del bot
responseMessageTextColor	string (hex)		Colore del testo delle risposte del bot
chatSubheader	string		Slogan mostrato sotto il titolo della chat
senderPlaceholder	string		Testo segnaposto nel campo di inserimento del messaggio
resetConversationTooltip	string		Descrizione comando sul pulsante "reset conversation" (reimposta conversazione)
chatAlignment	string (enum)	∈ {left, right}	Lato dello schermo a cui si ancora 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 iniettato 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, pill}	Stato ridotto a icona: icona del launcher, barra di invio compatta o pillola
chatDesktopWidthPx	int		Larghezza del widget su desktop
chatDesktopHeightPx	int		Altezza del widget su desktop
chatMobileSizePercent	int		Dimensione del widget su dispositivi mobili come % della viewport
messageFontSize	int		Dimensione del carattere del testo dei messaggi (px)
showChatbotBubblesDesktop	boolean		Mostra i fumetti fluttuanti di anteprima su desktop
showChatbotBubblesMobile	boolean		Mostra i fumetti fluttuanti di anteprima su dispositivi mobili
chatbotBubblesDelaySeconds	int		Ritardo prima della comparsa dei fumetti di anteprima (secondi)
launcherIconFullSize	boolean		Renderizza l'icona personalizzata del launcher a tutto campo anziché rientrata
welcomeScreenEnabled	boolean		Mostra la Welcome Screen (schermata di benvenuto) invece di entrare direttamente nella chat
welcomeScreenQuestionsLabel	string		Etichetta sopra le domande suggerite nella schermata di benvenuto
welcomeScreenHideHumanContactForm	boolean		Nascondi l'azione per il modulo di contatto umano nell'intestazione durante la visualizzazione della Welcome Screen. Riappare dopo il primo messaggio del visitatore. Per i bot creati prima del 2026-09-02 il valore predefinito è true
welcomeScreenHideLiveChat	boolean		Nascondi l'azione Live Chat nell'intestazione durante la visualizzazione della Welcome Screen. Riappare dopo il primo messaggio del visitatore. Per i bot creati prima del 2026-09-02 il valore predefinito è true
headerActionsLayout	string	ICONS o DROPDOWN	Modalità di presentazione di Live Chat e del modulo di contatto umano 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		Disponi le domande suggerite in verticale (anziché affiancate)
suggestedQuestionsFontSize	int		Dimensione del carattere dei chip delle domande suggerite (px)
suggestedQuestionsTextColor	string (hex)		Colore del testo dei chip delle domande suggerite
suggestedQuestionsBackgroundColor	string (hex)		Colore di sfondo dei chip delle domande suggerite
autoOpenChat	boolean		Apri automaticamente la chat su desktop
autoOpenChatOnMobiles	boolean		Apri automaticamente la chat su dispositivi mobili
autoOpenChatDelay	boolean		Applica un ritardo prima dell'apertura automatica
autoOpenChatDelaySeconds	int		Ritardo di apertura automatica (secondi)
simulateHumanTyping	boolean		Suddividi la risposta del bot in più fumetti con animazione di digitazione
simulateHumanTypingDelay	int	0-200	Ritardo tra i messaggi a fumetto (secondi)
footerMarkdown	string	max 255	Markdown personalizzato per il piè di pagina visualizzato sotto la chat
avatarUrl	string	sola lettura	URL pubblico completo dell'avatar; per modificarlo, caricalo tramite la parte multipart avatar

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

§ humanSupport

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Interruttore del flusso Human Support
email	string	obbligatorio (in creazione rigorosa) quando enabled=true	Indirizzo che riceve le email di assistenza umana
dialogMessage	string		Messaggio di incoraggiamento mostrato sopra il modulo
thankYouMessage	string		Messaggio di ringraziamento mostrato dopo l'invio
emailMessageSubjectTemplate	string		Modello per l'oggetto dell'email inviata all'agente
emailMessageContentTemplate	string		Modello per il corpo dell'email inviata all'agente
emailPlaceholder	string		Testo segnaposto nel campo email
messagePlaceholder	string		Testo segnaposto nell'area di testo del messaggio
emailWithConversationContent	boolean		Se 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. In fase di creazione, se omesso viene usato il modulo integrato; su PATCH, null mantiene inalterata la selezione attuale
customFormMapping	string	stringa codificata in JSON	Mappa i campi del modulo personalizzato sui campi email dell'assistenza umana

requirePolicyAccept si trova in consent.humanSupportRequirePolicyAccept, non qui.

§ leadCollection

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Interruttore del modulo di acquisizione contatti
nameEnabled	boolean		Raccogli il nome
nameLabel	string		Etichetta nel campo del nome
emailEnabled	boolean		Raccogli l'email
emailLabel	string	obbligatorio (in creazione rigorosa) quando enabled=true E emailEnabled=true	Etichetta nel campo dell'email
phoneEnabled	boolean		Raccogli il telefono
phoneLabel	string	obbligatorio (in creazione rigorosa) quando enabled=true E phoneEnabled=true	Etichetta nel campo del telefono
leaveDetailsMessage	string	obbligatorio (in creazione rigorosa) quando enabled=true	Messaggio che invita il visitatore a lasciare i propri recapiti
thankYouMessage	string	obbligatorio (in creazione rigorosa) quando enabled=true	Messaggio di ringraziamento mostrato dopo l'invio
requireBeforeNewConversation	boolean		Se true, il modulo deve essere inviato prima di iniziare la chat; se false, l'IA decide quando proporre il modulo
emailNotificationEnabled	boolean		Invia un'email al proprietario ogni volta che viene acquisito un lead
emailNotificationAddress	string		Destinatario delle notifiche (il valore predefinito è l'email dell'account)
emailWithConversationContent	boolean		Se true, include la trascrizione della conversazione nella notifica

| customFormId | long | id di un modulo personalizzato esistente | Sostituisce il modulo lead integrato con un modulo personalizzato. In fase di creazione, se omesso viene usato il modulo integrato; su PATCH, null mantiene inalterata la selezione attuale | | customFormMapping | string | stringa codificata in JSON | Mappa i campi del modulo personalizzato su nome / email / telefono |

Regola di creazione rigorosa tra campi: enabled=true richiede almeno uno tra emailEnabled o phoneEnabled. requirePolicyAccept si trova in consent.leadCollectionRequirePolicyAccept, non qui.

§ liveChat

Campo	Tipo	Vincolo	Descrizione
enabled	boolean		Interruttore della funzione Live Chat
infoMessage	string		Messaggio informativo visualizzato prima del passaggio a un operatore
startMessage	string		Messaggio mostrato all'avvio della sessione live
endMessage	string		Messaggio mostrato al termine della sessione live
nameLabel	string		Etichetta nel campo del nome nel modulo preliminare di Live Chat
emailLabel	string		Etichetta nel campo dell'email nel modulo preliminare di Live Chat
schedule	string	stringa codificata in JSON (giorni abilitati + from/to + timezone)	Orari operativi di Live Chat - vedi "Structured fields and ranges" per la struttura esatta
outOfHoursMessage	string		Messaggio mostrato al di fuori degli orari previsti
closeModalMessage	string		Titolo della finestra modale per la chiusura della chat
closeModalConfirmLabel	string		Etichetta del pulsante di conferma nella modale di chiusura
closeModalCancelLabel	string		Etichetta del pulsante di annullamento nella modale di chiusura
closeModalTooltipText	string		Descrizione comando sul controllo di chiusura della chat
operatorHasJoinedLabel	string		Etichetta mostrata quando un operatore entra nella chat
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 per la presa in carico da parte di un operatore (secondi)
redirectToHumanSupportForm	boolean		Se true, reindirizza al modulo Human Support se nessun operatore risponde
requireAdminOnline	boolean		Richiedi che un operatore sia disponibile in base alle impostazioni di presenza
presenceMode	string		Modalità di presenza; usa il valore di un bot configurato nell'interfaccia utente
hideHumanSupportWhenLiveChatAvailable	boolean		Nascondi il modulo di contatto quando la chat dal vivo è disponibile
missedEmailEnabled	boolean	predefinito true	Invia un'email al proprietario del bot quando una richiesta di live chat non riceve risposta. Lasciato non impostato sui bot legacy, viene interpretato come abilitato

requirePolicyAccept si trova in consent.liveChatRequirePolicyAccept, non qui.

§ consent

Campo	Tipo	Vincolo	Descrizione
newConversationRequirePolicyAccept	boolean		Richiedi il consenso all'informativa sulla privacy prima di iniziare una nuova conversazione
humanSupportRequirePolicyAccept	boolean		Richiedi il consenso all'informativa sulla privacy prima di inviare il modulo di assistenza umana
leadCollectionRequirePolicyAccept	boolean		Richiedi il consenso all'informativa sulla privacy prima di inviare il modulo per l'acquisizione di contatti
liveChatRequirePolicyAccept	boolean		Richiedi il consenso all'informativa sulla privacy prima di avviare una sessione di live chat
newConversationConsentDescription	string		Testo introduttivo per la schermata di consenso all'inizio della conversazione
privacyPolicyConsentCheckboxLabel	string		Etichetta accanto alla casella di spunta per il 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	Nascondi il logo ChatLab predefinito nel piè di pagina
whitelabelLogoLink	string	funzionalità White Label; soggetta ai limiti dell'account	URL a cui reindirizza 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 in POST/PATCH: whitelabel_logo (parte file). I corpi delle risposte / richieste 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 veri e propri restano 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		Consenti al visitatore di dettare i messaggi (da voce a testo)
conversationEnabled	boolean	richiede la funzionalità vocale attiva sul piano	Abilita conversazioni vocali complete
voiceId	string	id voce 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 alternanza dei turni di conversazione
audioPrompt	string		Prompt di sistema aggiuntivo utilizzato esclusivamente per i turni vocali
welcomeMessage	string		Frase iniziale pronunciata dal bot
language	string	codice lingua	Lingua vocale principale
additionalLanguages	string	codici lingua separati da virgole	Ulteriori lingue 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		Interruttore della modalità multilingue
mode	string	AUTODETECT o FIXED_LIST	Criterio con cui il bot sceglie la lingua di risposta
baseLanguage	string	codice lingua	Lingua con cui sono stati redatti i testi del bot
languages	string	codici lingua separati da virgole	Lingue proposte al visitatore
knowledgeLanguageMode	string	NONE, MAIN, o DYNAMIC	Criterio di gestione della knowledge base redatta in altre lingue
knowledgeLanguageFallback	string	codice lingua	Lingua utilizzata come fallback 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.6-LUNA)
temperature	decimal	0.0-1.0	Temperatura di campionamento (corrisponde al cursore nell'interfaccia)
chatContextSize	int	∈ {8000, 16000, 32000}; limitato automaticamente alla soglia dell'account	Budget di contesto configurato, inclusi istruzioni, cronologia e conoscenza
botMessagesLimit	long	0 o multiplo di 1000 (es. 1000, 2000, 10000)	Tetto mensile di crediti messaggio del bot (0 = nessun tetto specifico per il bot; si applica il budget dell'account)
internalLocale	string	codice locale nel formato ll_CC	Locale per le etichette dell'interfaccia del widget (distinto da role.language)
productsViewEnabled	boolean		Se true, mostra le Offer Cards di e-commerce all'interno della chat
includeProductsInKnowledgeBase	boolean		Se true, indicizza il catalogo prodotti come parte della knowledge base

Funzionalità non coperte dalle API

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

• Training ed eliminazione - questi endpoint non consentono di elencare tutti i bot, gestire i dataset di training o eliminare bot. Per questi flussi di lavoro usa l'applicazione.
• Scheda Flow - l'editor visuale per il flusso di conversazione (stadi e transizioni). Non esposto tramite la Management API.
• Scheda Actions - integrazioni gestite per e-commerce / prenotazioni, AI Search e funzioni API personalizzate. Il tool calling non ha mai fatto parte della Management API.
• Il generatore di moduli personalizzati - 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 sono riservate agli amministratori. Viene esposta unicamente 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 - JSON normale (consigliata quando non devi caricare un avatar / logo nella stessa richiesta):

• Content-Type: application/json
• Il corpo della richiesta è il JSON di configurazione del bot (senza il 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)

Solo name è obbligatorio nel JSON; ogni altro campo assume lo stesso valore predefinito impostato dalla procedura guidata dell'interfaccia di amministrazione.

Esempio di corpo della richiesta

Questo è il JSON data massimale - con ogni sezione compilata. Invia solo le sezioni di tuo interesse; tutto il resto assume 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.6-LUNA",
    "temperature": 0.4,
    "chatContextSize": 16000,
    "botMessagesLimit": 1000,
    "internalLocale": "en_US",
    "productsViewEnabled": false
  }
}

Regole di validazione con i rispettivi messaggi di errore:

• name - obbligatorio, max 150 caratteri
• advanced.temperature - tra 0.0 e 1.0
• chatMemory.summariesToKnowledgeRatio - intero tra 10 e 90 (percentuale, incremento di 10)
• appearance.launcherBottomMargin, appearance.launcherSideMargin - tra 0 e 500
• appearance.footerMarkdown - max 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 relativa etichetta, oltre a leaveDetailsMessage e thankYouMessage
• advanced.chatContextSize viene limitato alla dimensione massima del contesto supportata dall'account. Non dare per scontato che gli altri campi numerici vengano limitati automaticamente.

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

Esempio di corpo della risposta (201)

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

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

Il campo apiKey compare solo al momento della creazione: è la chiave Bot Talk appena generata e associata al nuovo bot. Il testo in chiaro viene mostrato una sola volta e non può essere recuperato successivamente dall'API; salvalo subito sul tuo lato.

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

Esempi Curl

Modalità A - JSON normale (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_..."

Esempio di corpo della risposta (200)

Stessa struttura della risposta POST, tranne per l'apiKey monouso. 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 attuali vengono esposti come URL completi di sola lettura (appearance.avatarUrl, whiteLabel.whitelabelLogoUrl), basati sullo stesso schema + host + context path che ha gestito questa richiesta. Recupera i byte effettuando una richiesta GET direttamente a questi URL; per sostituire uno dei file, caricane uno nuovo tramite la parte multipart avatar / whitelabel_logo su 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.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"
  }
}

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 l'origine con GET, rimuovi i campi di identità gestiti dal server, invia il risultato con 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 di primo livello meta. L'oggetto meta (id, createdAt, updatedAt) è gestito dal server ed è di sola lettura - lasciarlo nel corpo della richiesta POST non causa problemi (il server lo ignora), ma rimuoverlo rende l'intento esplicito e mantiene pulito il payload. Facoltativamente, modifica name in modo da distinguere il clone dall'origine.

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 la documentazione di POST /v1/management/bots sopra per la struttura completa del payload e le regole di validazione.

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

Questa operazione copia le impostazioni supportate, non un chatbot completamente addestrato. I contenuti di addestramento, la cronologia delle conversazioni, le integrazioni/azioni, il Flow e le definizioni dei moduli non vengono clonati da questi endpoint. Configurali separatamente nell'app.

Ulteriori 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 - durante la POST di creazione (Modalità B) oppure con una successiva richiesta PATCH.
• Le chiavi Bot Talk non vengono clonate. Ogni bot ha il proprio set di chiavi Bot Talk. La singola apiKey restituita dalla POST di creazione è l'unica generata automaticamente; crea chiavi aggiuntive dalla scheda API (API tab) 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 / i campi presenti nel JSON; tutto ciò che viene omesso (o inviato come null) rimane invariato. All'interno di una sezione inviata si applica la logica di aggiornamento parziale per singolo campo.

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

Modalità A - plain JSON (consigliata per l'aggiornamento delle sole impostazioni):

• Content-Type: application/json
• Il corpo della richiesta è il JSON di 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 dei campi. Omettila del tutto se vuoi caricare solo 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à White Label)

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

Esempio di corpo della richiesta (più sezioni)

È possibile inviare qualsiasi campo accettato da POST /v1/management/bots. L'esempio seguente illustra diverse sezioni, non tutti i campi supportati; in pratica invii solo le chiavi che desideri modificare (vedi "Aggiornamento parziale minimo" più sotto) - ogni chiave omessa (o inviata come null) lascia invariato il valore memorizzato.

{
  "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 richiesta PATCH su un singolo campo inviando esattamente le chiavi che desideri modificare - tutto il resto viene mantenuto.

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

Esempi con curl

Modalità A - plain JSON (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 (quando sostituisci l'avatar / il 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 - sostituisci solo l'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} - l'intera configurazione 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 del Corpo completo della richiesta (più sezioni) sopra al bot dell'esempio GET: i campi modificati riflettono i nuovi valori, i campi non toccati vengono preservati e meta.updatedAt viene aggiornato.

{
  "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": "your-plan-id",
  "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 (your-plan-id è un segnaposto a scopo illustrativo). I piani provengono da un catalogo dinamico, pertanto l'insieme esatto degli identificatori può cambiare nel tempo man mano che i piani vengono rinominati o aggiunti - trattalo come una stringa opaca, non come un enum fisso.
• messages.used / limit / remaining rappresentano i crediti messaggio del mese solare corrente, che si azzerano il primo giorno del mese e non il giorno di rinnovo dell'abbonamento. Sono conteggiati in base ai crediti e non come semplice conteggio delle risposte.
• bots.used / limit / remaining conteggiano i bot posseduti, inclusi quelli in pausa, rispetto al limite totale di bot del tuo account.

Intestazioni di rate limit

Le risposte che raggiungono la fase di rate limit (ovvero dopo aver superato 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 valore configurato in rateLimitPerMinute se inferiore).
• X-RateLimit-Remaining - token rimasti nel bucket subito dopo questa chiamata.
• X-RateLimit-Reset - secondi Unix epoch in cui diventa disponibile il token successivo (non un ripristino completo del bucket; il bucket si riempie continuamente). Quando il bucket è pieno, corrisponde all'ora corrente.

Nelle risposte 429 rate_limit_exceeded, viene impostata anche l'intestazione Retry-After, espressa in secondi interi fino a quando non si libera almeno un token.

Gli errori precedenti all'autenticazione (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) e 403 ip_not_whitelisted non contengono le intestazioni X-RateLimit-* - il limitatore viene consultato solo dopo il superamento dell'autenticazione e dei controlli IP.

Formato degli errori

Stesso contenitore 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 da individuare facilmente la sezione interessata:

{
  "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 i campi enum / con set chiuso di valori (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"
  }
}

Contenuti correlati

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