Configurazione del widget

Leggi e aggiorna la configurazione del widget del sito web tramite API.

Verifiche facoltative degli esempi

Verifica uno snippet del Widget. Controlla il codice incollato rispetto allo Scenario ID fornito. Non recupera il tuo sito web.

In un browser compatibile, questi controlli sono disponibili anche come strumenti del sito. I link aprono i moduli standard.

Il widget è un’interfaccia di chat incorporata nel sito web: compare come una bubble mobile nell’angolo della pagina, su cui i visitatori possono fare clic per aprire una conversazione con l’agente AI. È completamente personalizzabile: puoi controllare colori, dimensioni, posizione, messaggi di saluto e comportamento.

Queste impostazioni influenzano anche l’embed, una versione a pagina intera o in linea della stessa interfaccia di chat, inseribile direttamente nel layout della pagina anziché come bubble mobile. Widget ed embed condividono la configurazione di aspetto, messaggi e comportamento.

Con questi endpoint puoi personalizzare programmaticamente l’aspetto di Quickchat AI sul sito: abbinare i colori del brand, impostare moduli pre-chat per raccogliere informazioni sui visitatori, configurare indicatori di digitazione, attivare l’input vocale e altro. Per le istruzioni di configurazione, vedi la guida al canale Sito web.

Ambito: read_all

GET https://app.quickchat.ai/v1/api/widget/configuration

Shell
Python

curl https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>'

import requests

response = requests.get(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
)
data = response.json()

Risposta 200 OK

{
  "welcome_message": "<p>Hello! How can I help?</p>",
  "welcome_message2": "",
  "header": "Support",
  "subtitle": "We typically reply within minutes",
  "conversation_starters": ["What are your opening hours?", "How do I track my order?", "Talk to a human"],
  "popup_active": true,
  "input_placeholder": "Type your message...",
  "primary_color": "rgb(0, 122, 255)",
  "voice_active": false,
  "attachments_active": true,
  "header_color": "rgb(0, 122, 255)",
  "header_collapse": false,
  "header_text_color": true,
  "typing": true,
  "window_auto_open": false,
  "white_label": false,
  "prechat_active": false,
  "prechat_header_text": null,
  "prechat_button_text": null,
  "prechat_message_text": null,
  "background_disclaimer_text": null,
  "streaming_active": true,
  "link_tracking_active": false,
  "window_height": 600,
  "window_width": 400,
  "size": "medium",
  "location": "bottom-right",
  "launcher_label": "Ask AI",
  "launcher_draggable": false,
  "avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "bubble_icon_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "default_avatar_image": "https://storage.googleapis.com/quickchat-files/appquickchat/media/chat_avatars/default_bubble.png",
  "theme": "light",
  "widget_theme_custom": {
    "colors": {
      "background": "#ffffff",
      "header": "#ffffff",
      "header_text": "#030712",
      "accent": "#27272a",
      "accent_hover": "#374151",
      "accent_text": "#ffffff",
      "bubble": "#27272a",
      "bubble_text": "#ffffff",
      "ai_bubble_text": "#030712",
      "tertiary": "#afafb2",
      "link": null,
      "input_background": "#ffffff",
      "input_text": "#030712",
      "input_placeholder": "#9ca3af",
      "border": "#e5e7eb",
      "sidebar": {
        "background": "#f5f5f5",
        "text": null,
        "accent": "#e5e5e5",
        "accent_text": null
      }
    },
    "radius": { "bubble": "full", "input": "full", "button": "full" },
    "font": { "size": "base" },
    "transparency": { "style": "none", "opacity": 70 }
  }
}

Contenuti e messaggi

Campo	Descrizione
`welcome_message` stringa	Messaggio di benvenuto principale mostrato all’apertura del widget (HTML). Dashboard: Canali > Il tuo sito web > Contenuto testuale > Messaggio di benvenuto
`welcome_message2` stringa	Messaggio di benvenuto secondario mostrato sotto il saluto principale. Disponibile tramite API; non ha un campo di modifica nella dashboard.
`header` stringa	Testo mostrato nella barra d’intestazione del widget. Dashboard: Canali > Il tuo sito web > Contenuto testuale > Testo dell’intestazione
`subtitle` stringa	Sottotitolo mostrato sotto l’intestazione. Disponibile tramite API; non ha un campo di modifica nella dashboard.
`input_placeholder` stringa	Testo segnaposto nel campo del messaggio, per esempio “Scrivi il tuo messaggio…”
`conversation_starters` array di stringhe o null	Suggerimenti iniziali mostrati come pulsanti cliccabili all’apertura del widget. Fino a 3 voci, ognuna di circa 100 caratteri al massimo
`background_disclaimer_text` stringa o null	Testo dell’avvertenza mostrato in fondo alla finestra di chat

Aspetto

Campo	Descrizione
`primary_color` stringa	Colore principale del widget come valore CSS rgb, per esempio `"rgb(0, 122, 255)"`. Usato per pulsanti, link e bubble dei messaggi dell’utente
`header_color` stringa	Colore di sfondo dell’intestazione come valore CSS rgb
`header_text_color` booleano	Luminosità del testo dell’intestazione. `true` = testo bianco/chiaro (per intestazioni scure), `false` = testo scuro (per intestazioni chiare). Nota: nonostante il nome, è un booleano, non una stringa colore
`size` stringa	Dimensione predefinita del pulsante di avvio: `"small"`, `"medium"` o `"large"` (nella dashboard: Piccolo, Solo campo di input e Classico)
`location` stringa	Posizione del widget nella pagina: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` o `"bottom-right"`
`launcher_label` stringa o null	Testo sul pulsante di avvio piccolo (`size: "small"`), massimo 25 caratteri. `null` usa il valore predefinito (`"Ask AI"`); `""` mostra un pulsante con la sola icona
`launcher_draggable` booleano	Permette ai visitatori di trascinare il pulsante di avvio in un’altra posizione nella pagina
`window_height` intero	Altezza del widget in pixel (400-1200)
`window_width` intero	Larghezza del widget in pixel (300-700)
`avatar_image` stringa o null	URL dell’Avatar dell’agente AI, mostrato nell’intestazione della chat e come icona della bubble mobile. Caricalo tramite PATCH come base64. `null` indica che l’avatar è stato eliminato e il widget non ne mostra alcuno
`bubble_icon_image` stringa o null	Deprecato. Rispecchia sempre `avatar_image`: l’icona della bubble e l’avatar della chat sono ora una sola immagine (vedi Unificazione dell’avatar dell’agente AI)
`default_avatar_image` stringa	Sola lettura. URL dell’avatar predefinito dell’agente AI ripristinato da `use_default_avatar`
`theme` stringa	Modalità del tema: `"light"` o `"dark"` (preimpostazioni fisse) oppure `"custom"` (applica la palette `widget_theme_custom`)
`widget_theme_custom` oggetto	Personalizzazione del tema. `colors` (intestazione, accento, bubble dei messaggi, testo AI, `link`, input, bordo e altro, come hex o `rgb()`/`rgba()`) si applica solo quando `theme` è `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` per bubble, input e pulsanti), `font.size` (`"sm"`/`"base"`/`"lg"`) e `transparency` si applicano in ogni modalità. `transparency.style` è `"none"` (opaco, predefinito) oppure `"glass"` (trasparente, con la pagina retrostante sfocata); `transparency.opacity` (40–95, predefinito 70) è la tinta Vetro in percentuale. Il widget non la rende mai più tenue di quanto richiesto dal testo del tema su qualsiasi sito (50 in Chiaro, 65 in Scuro, ricavato dai colori in Personalizzato). Se nessuna opacità mantiene leggibile il testo di una palette personalizzata, il widget appare opaco e il valore salvato di `transparency.style` resta `"glass"`. La Pagina chat appare sempre opaca. Con PATCH invia l’intero oggetto: le chiavi mancanti tornano ai valori predefiniti, quindi un oggetto precedente senza `transparency` lo riporta a `"none"`. `widget_theme_custom` e ciascuna sezione (`colors`, `radius`, `font`, `transparency`) devono essere oggetti; `null` usa i valori predefiniti dell’intero tema o della sezione, mentre ogni altro valore viene rifiutato con 422. `colors.link` è `null` per impostazione predefinita: i link ereditano il colore del testo circostante. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) imposta solo il tema della barra laterale della Pagina chat autonoma (ignorato nelle viste bubble ed embed); `text` e `accent_text` sono `null` per impostazione predefinita, quindi un colore leggibile viene ricavato automaticamente dallo sfondo corrispondente

Comportamento

Campo	Descrizione
`popup_active` booleano	Mostra un invito popup accanto alla bubble del widget per incoraggiare i visitatori a iniziare una conversazione
`window_auto_open` booleano	Apre automaticamente il widget al caricamento della pagina, anziché mostrare solo la bubble
`header_collapse` booleano	Permette ai visitatori di comprimere l’intestazione per avere più spazio per la chat
`typing` booleano	Mostra un’animazione di digitazione mentre l’AI genera una risposta
`streaming_active` booleano	Trasmette le risposte AI parola per parola anziché mostrare l’intero messaggio in una volta
`voice_active` booleano	Attiva l’input vocale: i visitatori possono inviare messaggi usando il microfono
`attachments_active` booleano	Permette ai visitatori di allegare immagini o documenti ai messaggi. Predefinito: `true`; impostalo su `false` per nascondere il pulsante degli allegati e rifiutare i caricamenti
`link_tracking_active` booleano	Monitora i clic dei visitatori sui link nelle risposte AI. I clic compaiono come eventi `tracked_link` in Eventi della conversazione
`white_label` booleano	Rimuove il marchio “Powered by Quickchat” dal widget

Modulo pre-chat

Campo	Descrizione
`prechat_active` booleano	Attiva il modulo pre-chat. Quando è attivo, i visitatori devono compilarlo prima di chattare
`prechat_header_text` stringa o null	Testo dell’intestazione del modulo pre-chat
`prechat_button_text` stringa o null	Etichetta del pulsante di invio del modulo pre-chat
`prechat_message_text` stringa o null	Corpo del testo/istruzioni mostrate nel modulo pre-chat (HTML)

Ambito: write_all

PATCH https://app.quickchat.ai/v1/api/widget/configuration

Corpo della richiesta: tutti i campi sono facoltativi. Includi solo quelli da aggiornare.

Per avatar_image, invia dati immagine codificati in base64 (massimo 5 MB). La risposta restituisce l’URL dell’immagine salvata. Inviare avatar_image: null elimina l’avatar (il widget non ne mostra più alcuno); inviare use_default_avatar: true ripristina l’avatar predefinito dell’agente AI.

Unificazione dell’avatar dell’agente AI

L’avatar della chat (logo nell’intestazione) e l’icona della bubble mobile (pulsante di avvio) sono stati unificati nell’Avatar dell’agente AI, salvato in avatar_image. L’icona della bubble lo rispecchia sempre: non esiste più un’immagine indipendente per il pulsante di avvio. Se integri direttamente questo endpoint, considera questi cambiamenti:

Il caricamento tramite bubble_icon_image è deprecato: ora imposta l’avatar unificato dell’agente AI, sostituendo anche l’immagine nell’intestazione della chat. Usa invece avatar_image.
bubble_icon_image: null non esegue alcuna operazione. In precedenza cancellava l’icona del pulsante di avvio; ora che il pulsante rispecchia l’avatar, elimina l’immagine tramite avatar_image: null.
Gli agenti che non hanno mai personalizzato l’avatar mostrano quello predefinito (vedi default_avatar_image nella risposta) sia nell’intestazione sia nel pulsante di avvio.

Shell
Python

curl -X PATCH https://app.quickchat.ai/v1/api/widget/configuration \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "primary_color": "rgb(255, 87, 34)",
  "header": "Sales Assistant",
  "window_auto_open": true
}'

import requests

response = requests.patch(
    url="https://app.quickchat.ai/v1/api/widget/configuration",
    headers={"Authorization": "Bearer <API_TOKEN>"},
    json={
        "primary_color": "rgb(255, 87, 34)",
        "header": "Sales Assistant",
        "window_auto_open": True,
    },
)
data = response.json()

Risposta 200 OK: restituisce la configurazione aggiornata del widget, con lo stesso schema della risposta di Recuperare la configurazione del widget.

Configurazione del widget

Verifiche facoltative degli esempi