Widget Configuration

Lisez et mettez à jour la configuration du widget de site web via l'API.

Le widget est une interface de chat que vous intégrez sur votre site web : il apparaît sous forme de bulle flottante dans le coin de la page, sur laquelle les visiteurs peuvent cliquer pour ouvrir une conversation avec votre AI Agent. Le widget est entièrement personnalisable : vous contrôlez ses couleurs, sa taille, sa position, ses messages d’accueil et son comportement.

Ces paramètres affectent également l’embed, qui est une version pleine page ou intégrée de la même interface de chat que vous pouvez placer directement dans la mise en page de votre site (par opposition à la bulle flottante). Le widget et l’embed partagent la même configuration pour l’apparence, les messages et le comportement.

Avec ces endpoints, vous pouvez personnaliser par programmation l’apparence de Quickchat AI sur votre site web : accorder les couleurs de votre marque, configurer des formulaires de pré-chat pour collecter les informations des visiteurs, configurer les indicateurs de frappe, activer la saisie vocale, et bien plus. Pour les instructions de configuration, consultez le guide du canal Website.

Scope: 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()

Response 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,
  "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" }
  }
}

Content & Messaging

Field	Description
`welcome_message` string	Message de bienvenue principal affiché à l’ouverture du widget (HTML). Dashboard : Website > Greeting
`welcome_message2` string	Message de bienvenue secondaire affiché sous le message principal
`header` string	Texte affiché dans la barre d’en-tête du widget. Dashboard : Website > Header
`subtitle` string	Texte de sous-titre affiché sous l’en-tête. Dashboard : Website > Subtitle
`input_placeholder` string	Texte indicatif dans le champ de saisie du message (p. ex. “Type your message…”)
`conversation_starters` array of strings or null	Suggestions d’ouverture affichées sous forme de boutons cliquables à l’ouverture du widget. Jusqu’à 3 entrées, chacune jusqu’à ~100 caractères
`background_disclaimer_text` string or null	Texte d’avertissement affiché en bas de la fenêtre de chat

Appearance

Field	Description
`primary_color` string	Couleur d’accentuation du widget sous forme de valeur CSS rgb (p. ex. `"rgb(0, 122, 255)"`). Utilisée pour les boutons, les liens et les bulles de message de l’utilisateur
`header_color` string	Couleur de fond de l’en-tête sous forme de valeur CSS rgb
`header_text_color` boolean	Luminosité du texte de l’en-tête. `true` = texte blanc/clair (pour les en-têtes sombres), `false` = texte sombre (pour les en-têtes clairs). Note : malgré son nom, il s’agit d’un booléen, pas d’une chaîne de couleur
`size` string	Preset de taille du launcher : `"small"`, `"medium"`, ou `"large"` (affichés dans le dashboard comme Small, Input Only et Classic)
`location` string	Position du widget sur la page : `"top-left"`, `"top-right"`, `"bottom-left"`, ou `"bottom-right"`
`launcher_label` string or null	Texte sur le bouton de launcher small (`size: "small"`), max 25 caractères. `null` utilise la valeur par défaut (`"Ask AI"`) ; `""` affiche un launcher avec icône uniquement
`launcher_draggable` boolean	Autorise les visiteurs à déplacer le launcher vers une autre position sur la page
`window_height` integer	Hauteur du widget en pixels (400-1200)
`window_width` integer	Largeur du widget en pixels (300-700)
`avatar_image` string or null	URL de l’AI Agent Avatar, affiché à la fois dans l’en-tête du chat et comme icône de la bulle flottante. À téléverser via PATCH en base64. `null` signifie que l’avatar a été supprimé et que le widget n’affiche aucun avatar
`bubble_icon_image` string or null	Déprécié. Reflète toujours `avatar_image` — l’icône de la bulle et l’avatar du chat ne forment désormais qu’une seule image (voir Unification de l’AI Agent Avatar)
`default_avatar_image` string	Lecture seule. URL de l’AI Agent Avatar par défaut que `use_default_avatar` restaure
`theme` string	Mode du thème de couleurs : `"light"` ou `"dark"` (presets fixes) ou `"custom"` (applique la palette `widget_theme_custom`)
`widget_theme_custom` object	Palette personnalisée appliquée lorsque `theme` vaut `"custom"`. Contient `colors` (en-tête, accent, bulle de message, texte de l’IA, `link`, champ de saisie, bordure, et plus, sous forme hex ou `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` pour les bulles, le champ de saisie et les boutons), et `font.size` (`"sm"`/`"base"`/`"lg"`). Sur PATCH, envoyez l’objet complet — les clés manquantes sont réinitialisées aux valeurs par défaut. `colors.link` vaut `null` par défaut, ce qui signifie que les liens héritent de la couleur du texte environnant. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) ne thématise que la sidebar de la Chat Page autonome (ignorée par les vues bulle et embed) ; ses valeurs `text` et `accent_text` valent `null` par défaut, ce qui signifie qu’une couleur lisible est déduite automatiquement à partir de l’arrière-plan correspondant

Behavior

Field	Description
`popup_active` boolean	Affiche une invite popup près de la bulle du widget pour encourager les visiteurs à démarrer une conversation
`window_auto_open` boolean	Ouvre automatiquement le widget au chargement de la page (au lieu de n’afficher que la bulle)
`header_collapse` boolean	Autorise les visiteurs à réduire la zone d’en-tête pour plus d’espace de chat
`typing` boolean	Affiche une animation d’indicateur de frappe pendant que l’IA génère une réponse
`streaming_active` boolean	Diffuse les réponses de l’IA mot par mot au lieu d’afficher le message complet d’un coup
`voice_active` boolean	Active la saisie vocale — les visiteurs peuvent envoyer des messages à l’aide de leur microphone
`link_tracking_active` boolean	Suit les clics des visiteurs sur les liens des réponses de l’IA. Les clics suivis apparaissent comme des événements `tracked_link` dans Conversation Events
`white_label` boolean	Retire la mention “Powered by Quickchat” du widget

Pre-chat Form

Field	Description
`prechat_active` boolean	Active le formulaire de pré-chat. Lorsqu’il est actif, les visiteurs doivent remplir le formulaire avant de discuter
`prechat_header_text` string or null	Texte d’en-tête du formulaire de pré-chat
`prechat_button_text` string or null	Libellé du bouton de soumission du formulaire de pré-chat
`prechat_message_text` string or null	Texte/instructions affichés dans le formulaire de pré-chat (HTML)

Scope: write_all

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

Request Body — Tous les champs sont optionnels. N’incluez que les champs que vous souhaitez mettre à jour.

Unification de l’AI Agent Avatar

L’avatar du chat (logo de l’en-tête) et l’icône de la bulle flottante (launcher) ont été fusionnés en une seule image, l’AI Agent Avatar, stockée dans avatar_image. L’icône de la bulle la reflète toujours — il n’existe plus d’image de launcher indépendante. Si vous intégrez directement ce endpoint, notez les changements de comportement suivants :

Le téléversement via bubble_icon_image est déprécié : il définit désormais l’AI Agent Avatar unifié, qui remplace également l’image affichée dans l’en-tête du chat. Utilisez avatar_image à la place.
bubble_icon_image: null est un no-op. Cela effaçait auparavant l’icône du launcher ; comme le launcher reflète l’avatar, supprimez plutôt via avatar_image: null.
Les agents qui n’ont jamais personnalisé leur avatar affichent l’AI Agent Avatar par défaut (voir default_avatar_image dans la réponse) à la fois dans l’en-tête et dans le launcher.

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()

Response 200 OK — Retourne la configuration du widget mise à jour (même schéma que la réponse de Get Widget Configuration).

Widget Configuration