Widgetconfiguratie

Lees de configuratie van de websitewidget en werk deze bij via de API.

Optionele voorbeeldcontroles

Controleer een widgetfragment. Controleer geplakte code aan de hand van de opgegeven scenario-ID. Dit haalt je website niet op.

In een geschikte browser zijn deze controles ook beschikbaar als sitetools. De links openen de standaardformulieren.

De widget is een chatinterface die je op je website plaatst. Deze verschijnt als zwevende bubble in een hoek van de pagina, waarop bezoekers kunnen klikken om een gesprek met je AI-agent te openen. De widget is volledig aanpasbaar: je bepaalt kleuren, afmetingen, positie, begroetingsberichten en gedrag.

Deze instellingen gelden ook voor Insluiten, een paginavullende of inline versie van dezelfde chatinterface die je rechtstreeks in de pagina-indeling kunt plaatsen. Zowel de widget als de ingesloten chat delen dezelfde configuratie voor uiterlijk, berichten en gedrag.

Met deze endpoints pas je programmatisch aan hoe Quickchat AI op je website verschijnt: gebruik je merkkleuren, stel formulieren vóór de chat in om bezoekersinformatie te verzamelen, configureer typindicatoren, schakel spraakinvoer in en meer. Zie de handleiding voor het websitekanaal voor installatie-instructies.

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

Antwoord 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 }
  }
}

Inhoud en berichten

Veld	Beschrijving
`welcome_message` string	Primair welkomstbericht dat verschijnt wanneer de widget opent (HTML). Dashboard: Kanalen > Je website > Tekstinhoud > Welkomstbericht
`welcome_message2` string	Secundair welkomstbericht onder de primaire begroeting. Beschikbaar via de API; hiervoor is geen editorveld in het dashboard.
`header` string	Tekst in de kopbalk van de widget. Dashboard: Kanalen > Je website > Tekstinhoud > Koptekst
`subtitle` string	Ondertitel onder de koptekst. Beschikbaar via de API; hiervoor is geen editorveld in het dashboard.
`input_placeholder` string	Tijdelijke aanduiding in het berichtinvoerveld (bijvoorbeeld “Typ je bericht…”)
`conversation_starters` array van strings of null	Voorgestelde openingsvragen die als klikbare knoppen verschijnen wanneer de widget opent. Maximaal 3 items van elk ongeveer 100 tekens
`background_disclaimer_text` string of null	Disclaimertekst onderaan het chatvenster

Uiterlijk

Veld	Beschrijving
`primary_color` string	Accentkleur van de widget als CSS-rgb-waarde (bijvoorbeeld `"rgb(0, 122, 255)"`). Gebruikt voor knoppen, links en berichtbubbles van gebruikers
`header_color` string	Achtergrondkleur van de kop als CSS-rgb-waarde
`header_text_color` boolean	Helderheid van de koptekst. `true` = witte/lichte tekst (voor donkere koppen), `false` = donkere tekst (voor lichte koppen). Let op: ondanks de naam is dit een boolean, geen kleurstring
`size` string	Formaatvoorinstelling voor de startknop: `"small"`, `"medium"` of `"large"` (in het dashboard weergegeven als Klein, Alleen invoerveld en Klassiek)
`location` string	Positie van de widget op de pagina: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` of `"bottom-right"`
`launcher_label` string of null	Tekst op de kleine startknop (`size: "small"`), maximaal 25 tekens. `null` gebruikt de standaardwaarde (`"Ask AI"`); `""` toont een startknop met alleen een pictogram
`launcher_draggable` boolean	Bezoekers toestaan de startknop naar een andere plek op de pagina te slepen
`window_height` integer	Hoogte van de widget in pixels (400-1200)
`window_width` integer	Breedte van de widget in pixels (300-700)
`avatar_image` string of null	URL van de Avatar van AI-agent, zichtbaar in de chatkop en als pictogram van de zwevende bubble. Upload via PATCH als base64. `null` betekent dat de avatar is verwijderd en de widget geen avatar toont
`bubble_icon_image` string of null	Verouderd. Is altijd gelijk aan `avatar_image`: het bubblepictogram en de chatavatar zijn nu één afbeelding (zie Samenvoeging van de avatar van de AI-agent)
`default_avatar_image` string	Alleen lezen. URL van de standaardavatar van de AI-agent die met `use_default_avatar` wordt hersteld
`theme` string	Kleurthemamodus: `"light"` of `"dark"` (vaste voorinstellingen) of `"custom"` (past het palet `widget_theme_custom` toe)
`widget_theme_custom` object	Thema-aanpassing. `colors` (kop, accent, berichtbubble, AI-tekst, `link`, invoer, rand en meer, als hex of `rgb()`/`rgba()`) gelden alleen wanneer `theme` gelijk is aan `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` voor bubbles, invoer en knoppen), `font.size` (`"sm"`/`"base"`/`"lg"`) en `transparency` gelden in elke themamodus. `transparency.style` is `"none"` (ondoorzichtig, standaard) of `"glass"` (doorzichtig met de pagina erachter vervaagd); `transparency.opacity` (40–95, standaard 70) is de Glas-tint in procenten. De widget toont deze nooit transparanter dan de tekst van het thema op een willekeurige website toelaat (50 bij Licht, 65 bij Donker, afgeleid van de kleuren bij Aangepast). Als geen dekkingswaarde de tekst van een aangepast palet leesbaar houdt, wordt de widget ondoorzichtig weergegeven en blijft de opgeslagen `transparency.style` op `"glass"`. De Chatpagina is altijd ondoorzichtig. Stuur bij PATCH het volledige object: ontbrekende sleutels worden op standaardwaarden teruggezet, dus een ouder object zonder `transparency` zet deze terug op `"none"`. `widget_theme_custom` en elke sectie ervan (`colors`, `radius`, `font`, `transparency`) moeten objecten zijn; `null` gebruikt de standaardwaarden van het volledige thema of die sectie en elke andere waarde wordt geweigerd met 422. `colors.link` is standaard `null`, waardoor links de omringende tekstkleur overnemen. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) bepaalt alleen het thema van de zijbalk van de zelfstandige Chatpagina (genegeerd door de bubble en ingesloten weergaven); `text` en `accent_text` zijn standaard `null`, waardoor automatisch een leesbare kleur wordt afgeleid van de bijbehorende achtergrond

Gedrag

Veld	Beschrijving
`popup_active` boolean	Een popup bij de widgetbubble tonen om bezoekers aan te moedigen een gesprek te beginnen
`window_auto_open` boolean	De widget automatisch openen bij het laden van de pagina in plaats van alleen de bubble te tonen
`header_collapse` boolean	Bezoekers toestaan het kopgedeelte in te klappen voor meer chatruimte
`typing` boolean	Een geanimeerde typindicator tonen terwijl de AI een antwoord maakt
`streaming_active` boolean	AI-antwoorden woord voor woord streamen in plaats van het volledige bericht ineens te tonen
`voice_active` boolean	Spraakinvoer inschakelen: bezoekers kunnen berichten sturen via hun microfoon
`attachments_active` boolean	Bezoekers toestaan een afbeelding of document aan een bericht toe te voegen. Standaard `true`; stel in op `false` om de bijlageknop te verbergen en uploads te weigeren
`link_tracking_active` boolean	Bijhouden wanneer bezoekers op links in AI-antwoorden klikken. Klikken verschijnen als gebeurtenissen van het type `tracked_link` in Gespreksgebeurtenissen
`white_label` boolean	De vermelding “Powered by Quickchat” uit de widget verwijderen

Formulier vóór de chat

Veld	Beschrijving
`prechat_active` boolean	Het formulier vóór de chat inschakelen. Als dit actief is, moeten bezoekers het formulier invullen voordat ze chatten
`prechat_header_text` string of null	Koptekst voor het formulier vóór de chat
`prechat_button_text` string of null	Label voor de verzendknop van het formulier vóór de chat
`prechat_message_text` string of null	Hoofdtekst of instructies in het formulier vóór de chat (HTML)

Bereik: write_all

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

Requestbody: alle velden zijn optioneel. Neem alleen de velden op die je wilt bijwerken.

Stuur voor avatar_image base64-gecodeerde afbeeldingsgegevens (maximaal 5 MB). Het antwoord retourneert de opgeslagen afbeeldings-URL. Met avatar_image: null verwijder je de avatar (de widget toont dan geen avatar) en met use_default_avatar: true herstel je de standaardavatar van de AI-agent.

Samenvoeging van de avatar van de AI-agent

De chatavatar (het logo in de kop) en het pictogram van de zwevende bubble (de startknop) zijn samengevoegd tot één afbeelding, de Avatar van AI-agent, opgeslagen in avatar_image. Het bubblepictogram is altijd gelijk daaraan; er is geen afzonderlijke afbeelding voor de startknop meer. Als je rechtstreeks met dit endpoint integreert, houd dan rekening met deze gedragswijzigingen:

Uploaden via bubble_icon_image is verouderd: hiermee stel je nu de gezamenlijke avatar van de AI-agent in, die ook de afbeelding in de chatkop vervangt. Gebruik in plaats daarvan avatar_image.
bubble_icon_image: null doet niets. Dit wiste vroeger het startpictogram. Omdat de startknop de avatar volgt, verwijder je deze nu via avatar_image: null.
Agenten waarvan de avatar nooit is aangepast, tonen de standaardavatar van de AI-agent (zie default_avatar_image in het antwoord) in zowel de kop als de startknop.

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

Antwoord 200 OK: retourneert de bijgewerkte widgetconfiguratie (hetzelfde schema als het antwoord van Widgetconfiguratie ophalen).

Widgetconfiguratie

Optionele voorbeeldcontroles