Widget Configuration

Lesen und aktualisieren Sie die Konfiguration des Website-Widgets über die API.

Das Widget ist eine Chat-Oberfläche, die Sie auf Ihrer Website einbetten — es erscheint als schwebende Bubble in der Ecke der Seite, die Besucher anklicken können, um eine Konversation mit Ihrem KI-Agenten zu starten. Das Widget ist vollständig anpassbar: Sie steuern Farben, Größe, Position, Begrüßungsnachrichten und Verhalten.

Diese Einstellungen wirken sich auch auf das Embed aus, eine ganzseitige oder Inline-Version derselben Chat-Oberfläche, die Sie direkt in das Layout Ihrer Webseite einfügen können (im Gegensatz zur schwebenden Bubble). Sowohl das Widget als auch das Embed teilen sich dieselbe Konfiguration für Erscheinungsbild, Nachrichten und Verhalten.

Mit diesen Endpunkten können Sie programmatisch anpassen, wie Quickchat AI auf Ihrer Website erscheint — Ihre Markenfarben übernehmen, Pre-Chat-Formulare zum Erfassen von Besucherinformationen einrichten, Tippindikatoren konfigurieren, Spracheingabe aktivieren und mehr. Eine Anleitung zur Einrichtung finden Sie im Leitfaden zum Website-Kanal.

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

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

Inhalt & Nachrichten

Field	Description
`welcome_message` string	Primäre Willkommensnachricht, die beim Öffnen des Widgets angezeigt wird (HTML). Dashboard: Website > Greeting
`welcome_message2` string	Sekundäre Willkommensnachricht, die unter der primären Begrüßung angezeigt wird
`header` string	Text, der in der Kopfleiste des Widgets angezeigt wird. Dashboard: Website > Header
`subtitle` string	Untertiteltext, der unter der Kopfzeile angezeigt wird. Dashboard: Website > Subtitle
`input_placeholder` string	Platzhaltertext im Nachrichten-Eingabefeld (z. B. “Type your message…”)
`conversation_starters` array of strings or null	Vorgeschlagene Einstiegs-Prompts, die beim Öffnen des Widgets als anklickbare Schaltflächen angezeigt werden. Bis zu 3 Einträge, jeweils bis zu ~100 Zeichen
`background_disclaimer_text` string or null	Disclaimer-Text, der am unteren Rand des Chat-Fensters angezeigt wird

Erscheinungsbild

Field	Description
`primary_color` string	Akzentfarbe des Widgets als CSS-rgb-Wert (z. B. `"rgb(0, 122, 255)"`). Wird für Schaltflächen, Links und Bubbles der Nutzernachrichten verwendet
`header_color` string	Hintergrundfarbe der Kopfzeile als CSS-rgb-Wert
`header_text_color` boolean	Helligkeit des Kopfzeilentexts. `true` = weißer/heller Text (für dunkle Kopfzeilen), `false` = dunkler Text (für helle Kopfzeilen). Hinweis: Trotz des Namens ist dies ein boolescher Wert, keine Farbzeichenkette
`size` string	Größen-Preset des Launchers: `"small"`, `"medium"` oder `"large"` (im Dashboard als Small, Input Only und Classic angezeigt)
`location` string	Position des Widgets auf der Seite: `"top-left"`, `"top-right"`, `"bottom-left"` oder `"bottom-right"`
`launcher_label` string or null	Text auf der kleinen Launcher-Schaltfläche (`size: "small"`), max. 25 Zeichen. `null` verwendet den Standard (`"Ask AI"`); `""` zeigt einen Launcher nur mit Icon
`launcher_draggable` boolean	Besuchern erlauben, den Launcher an eine andere Position auf der Seite zu ziehen
`window_height` integer	Höhe des Widgets in Pixeln (400-1200)
`window_width` integer	Breite des Widgets in Pixeln (300-700)
`avatar_image` string or null	URL des AI Agent Avatar, der sowohl in der Chat-Kopfzeile als auch als Symbol der schwebenden Bubble angezeigt wird. Upload via PATCH als base64. `null` bedeutet, dass der Avatar gelöscht wurde und das Widget keinen Avatar anzeigt
`bubble_icon_image` string or null	Veraltet. Spiegelt immer `avatar_image` — das Bubble-Symbol und der Chat-Avatar sind nun ein einziges Bild (siehe Vereinheitlichung des AI Agent Avatar)
`default_avatar_image` string	Read-only. URL des standardmäßigen AI Agent Avatar, den `use_default_avatar` wiederherstellt
`theme` string	Modus des Farbthemas: `"light"` oder `"dark"` (feste Presets) oder `"custom"` (wendet die Palette `widget_theme_custom` an)
`widget_theme_custom` object	Benutzerdefinierte Palette, die angewendet wird, wenn `theme` `"custom"` ist. Enthält `colors` (Kopfzeile, Akzent, Nachrichten-Bubble, KI-Text, `link`, Eingabe, Rahmen und mehr, als Hex oder `rgb()`/`rgba()`), `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` für Bubbles, Eingabe und Schaltflächen) und `font.size` (`"sm"`/`"base"`/`"lg"`). Beim PATCH das gesamte Objekt senden — fehlende Schlüssel werden auf die Standardwerte zurückgesetzt. `colors.link` ist standardmäßig `null`, was bedeutet, dass Links die umgebende Textfarbe übernehmen. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) thematisiert nur die Seitenleiste der eigenständigen Chat Page (von der Bubble- und Embed-Ansicht ignoriert); `text` und `accent_text` sind standardmäßig `null`, was bedeutet, dass eine lesbare Farbe automatisch aus dem passenden Hintergrund abgeleitet wird

Verhalten

Field	Description
`popup_active` boolean	Einen Popup-Hinweis nahe der Widget-Bubble anzeigen, um Besucher zum Starten einer Konversation zu animieren
`window_auto_open` boolean	Das Widget beim Laden der Seite automatisch öffnen (statt nur die Bubble anzuzeigen)
`header_collapse` boolean	Besuchern erlauben, den Kopfzeilenbereich für mehr Chat-Platz einzuklappen
`typing` boolean	Eine Tippindikator-Animation anzeigen, während die KI eine Antwort generiert
`streaming_active` boolean	KI-Antworten Wort für Wort streamen, statt die vollständige Nachricht auf einmal anzuzeigen
`voice_active` boolean	Spracheingabe aktivieren — Besucher können Nachrichten über ihr Mikrofon senden
`link_tracking_active` boolean	Erfassen, wenn Besucher Links in KI-Antworten anklicken. Erfasste Klicks erscheinen als `tracked_link`-Events in Conversation Events
`white_label` boolean	Das “Powered by Quickchat”-Branding aus dem Widget entfernen

Pre-Chat-Formular

Field	Description
`prechat_active` boolean	Das Pre-Chat-Formular aktivieren. Wenn aktiv, müssen Besucher das Formular vor dem Chatten ausfüllen
`prechat_header_text` string or null	Kopfzeilentext für das Pre-Chat-Formular
`prechat_button_text` string or null	Beschriftung der Absende-Schaltfläche im Pre-Chat-Formular
`prechat_message_text` string or null	Fließtext/Anweisungen, die im Pre-Chat-Formular angezeigt werden (HTML)

Scope: write_all

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

Request-Body — Alle Felder sind optional. Geben Sie nur die Felder an, die Sie aktualisieren möchten.

Vereinheitlichung des AI Agent Avatar

Der Chat-Avatar (Header-Logo) und das Symbol der schwebenden Bubble (Launcher) wurden zu einem einzigen Bild zusammengeführt, dem AI Agent Avatar, gespeichert in avatar_image. Das Bubble-Symbol spiegelt es immer — es gibt kein eigenständiges Launcher-Bild mehr. Wenn Sie direkt mit diesem Endpunkt integrieren, beachten Sie die folgenden Verhaltensänderungen:

Der Upload über bubble_icon_image ist veraltet: Er setzt nun den vereinheitlichten AI Agent Avatar, der auch das in der Chat-Kopfzeile angezeigte Bild ersetzt. Verwenden Sie stattdessen avatar_image.
bubble_icon_image: null ist ein No-op. Es löschte früher das Launcher-Symbol; da der Launcher den Avatar spiegelt, löschen Sie stattdessen über avatar_image: null.
Agenten, die ihren Avatar nie angepasst haben, zeigen den standardmäßigen AI Agent Avatar (siehe default_avatar_image in der Antwort) sowohl in der Kopfzeile als auch im 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()

Antwort 200 OK — Gibt die aktualisierte Widget Configuration zurück (gleiches Schema wie die Antwort von Widget Configuration abrufen).

Widget Configuration