Widget Configuration

Odczytuj i aktualizuj konfigurację widgetu na stronie internetowej za pomocą API.

Opcjonalne sprawdzenie przykładu

Sprawdź fragment kodu Widget. Sprawdź wklejony kod względem podanego Scenario ID. Narzędzie nie pobiera Twojej witryny.

W zgodnej przeglądarce te funkcje są też dostępne jako narzędzia strony. Linki otwierają standardowe formularze. Formularz jest po angielsku.

Widget to interfejs czatu, który osadzasz na swojej stronie internetowej — pojawia się jako pływająca bańka w rogu strony, którą odwiedzający mogą kliknąć, aby otworzyć rozmowę z Twoim AI Agentem. Widget jest w pełni konfigurowalny: kontrolujesz jego kolory, rozmiar, pozycję, wiadomości powitalne i zachowanie.

Te ustawienia wpływają również na embed, czyli pełnoekranową lub osadzoną wersję tego samego interfejsu czatu, którą możesz umieścić bezpośrednio w układzie swojej strony (w przeciwieństwie do pływającej bańki). Zarówno widget, jak i embed współdzielą tę samą konfigurację wyglądu, komunikatów i zachowania.

Dzięki tym endpointom możesz programistycznie dostosować sposób, w jaki Quickchat AI pojawia się na Twojej stronie — dopasować kolory marki, skonfigurować formularze pre-chat do zbierania informacji o odwiedzających, skonfigurować wskaźniki pisania, włączyć wprowadzanie głosowe i więcej. Instrukcje konfiguracji znajdziesz w przewodniku po kanale Website.

Zakres: 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,
  "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 }
  }
}

Content & Messaging

Field	Description
`welcome_message` string	Główna wiadomość powitalna wyświetlana po otwarciu widgetu (HTML). Panel: Kanały > Twoja strona > Treść tekstowa > Wiadomość powitalna
`welcome_message2` string	Dodatkowa wiadomość powitalna wyświetlana pod głównym powitaniem. Dostępna przez API; w panelu nie ma pola do jej edycji.
`header` string	Tekst wyświetlany na pasku nagłówka widgetu. Panel: Kanały > Twoja strona > Treść tekstowa > Tekst nagłówka
`subtitle` string	Tekst podtytułu wyświetlany pod nagłówkiem. Dostępny przez API; w panelu nie ma pola do jego edycji.
`input_placeholder` string	Tekst placeholdera w polu wprowadzania wiadomości (np. “Type your message…”)
`conversation_starters` array of strings or null	Sugerowane wstępne prompty wyświetlane jako klikalne przyciski po otwarciu widgetu. Do 3 wpisów, każdy do ok. 100 znaków
`background_disclaimer_text` string or null	Tekst zastrzeżenia wyświetlany na dole okna czatu

Appearance

Field	Description
`primary_color` string	Kolor akcentu widgetu jako wartość CSS rgb (np. `"rgb(0, 122, 255)"`). Używany dla przycisków, linków i bańek wiadomości użytkownika
`header_color` string	Kolor tła nagłówka jako wartość CSS rgb
`header_text_color` boolean	Jasność tekstu nagłówka. `true` = biały/jasny tekst (dla ciemnych nagłówków), `false` = ciemny tekst (dla jasnych nagłówków). Uwaga: mimo nazwy to wartość boolean, a nie ciąg z kolorem
`size` string	Preset rozmiaru launchera: `"small"`, `"medium"` lub `"large"` (wyświetlane w dashboardzie jako Small, Input Only i Classic)
`location` string	Pozycja widgetu na stronie: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` lub `"bottom-right"`
`launcher_label` string or null	Tekst na małym przycisku launchera (`size: "small"`), maks. 25 znaków. `null` używa wartości domyślnej (`"Ask AI"`); `""` wyświetla launcher tylko z ikoną
`launcher_draggable` boolean	Pozwala odwiedzającym przeciągnąć launcher w inne miejsce na stronie
`window_height` integer	Wysokość widgetu w pikselach (400-1200)
`window_width` integer	Szerokość widgetu w pikselach (300-700)
`avatar_image` string or null	URL AI Agent Avatar, wyświetlanego zarówno w nagłówku czatu, jak i jako ikona pływającej bańki. Przesyłaj przez PATCH jako base64. `null` oznacza, że avatar został usunięty i widget nie wyświetla avatara
`bubble_icon_image` string or null	Deprecated. Zawsze odzwierciedla `avatar_image` — ikona bańki i avatar czatu to teraz jeden obraz (zobacz AI Agent Avatar unification)
`default_avatar_image` string	Tylko do odczytu. URL domyślnego AI Agent Avatar, który przywraca `use_default_avatar`
`theme` string	Tryb motywu kolorystycznego: `"light"` lub `"dark"` (stałe presety) albo `"custom"` (stosuje paletę `widget_theme_custom`)
`widget_theme_custom` object	Dostosowanie motywu. `colors` (header, accent, bańka wiadomości, tekst AI, `link`, input, border i więcej, jako hex lub `rgb()`/`rgba()`) działają tylko, gdy `theme` ma wartość `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` dla bańek, inputu i przycisków), `font.size` (`"sm"`/`"base"`/`"lg"`) oraz `transparency` działają w każdym trybie motywu. `transparency.style` ma wartość `"none"` (jednolite, domyślnie) lub `"glass"` (półprzezroczyste, z rozmytą stroną w tle); `transparency.opacity` (40–95, domyślnie 70) to odcień Szkła w procentach, a widget nigdy nie wyświetla go słabiej, niż wymaga tego tekst motywu na dowolnej stronie (50 w trybie Jasny, 65 w trybie Ciemny, w trybie Własny wyliczane z kolorów). Jeśli w trybie Własny żaden poziom krycia nie zapewnia czytelności tekstu, widget ma jednolite tło, a zapisany `transparency.style` pozostaje `"glass"`. Chat Page zawsze ma jednolite tło. Przy PATCH wyślij cały obiekt: brakujące klucze resetują się do wartości domyślnych, więc starszy obiekt bez `transparency` przywraca wartość `"none"`. `widget_theme_custom` i każda jego sekcja (`colors`, `radius`, `font`, `transparency`) muszą być obiektami; `null` przyjmuje wartości domyślne całego motywu lub tej sekcji, a każda inna wartość jest odrzucana z kodem 422. `colors.link` domyślnie ma wartość `null`, co oznacza, że linki dziedziczą kolor otaczającego tekstu. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) nadaje motyw wyłącznie sidebarowi samodzielnej Chat Page (ignorowany przez widoki bańki i embedu); jego `text` i `accent_text` domyślnie mają wartość `null`, co oznacza, że czytelny kolor jest automatycznie wyprowadzany z pasującego tła

Behavior

Field	Description
`popup_active` boolean	Pokazuje popup w pobliżu bańki widgetu, aby zachęcić odwiedzających do rozpoczęcia rozmowy
`window_auto_open` boolean	Automatycznie otwiera widget po załadowaniu strony (zamiast pokazywać tylko bańkę)
`header_collapse` boolean	Pozwala odwiedzającym zwinąć obszar nagłówka, aby zyskać więcej miejsca na czat
`typing` boolean	Pokazuje animację wskaźnika pisania, gdy AI generuje odpowiedź
`streaming_active` boolean	Strumieniuje odpowiedzi AI słowo po słowie zamiast pokazywać całą wiadomość naraz
`voice_active` boolean	Włącza wprowadzanie głosowe — odwiedzający mogą wysyłać wiadomości za pomocą mikrofonu
`attachments_active` boolean	Pozwala odwiedzającym dołączyć obraz lub dokument. Wartość domyślna to `true`. Gdy ma wartość `false`, przycisk Załączniki jest ukryty, a przesyłane pliki są odrzucane
`link_tracking_active` boolean	Śledzi kliknięcia odwiedzających w linki w odpowiedziach AI. Śledzone kliknięcia pojawiają się jako zdarzenia `tracked_link` w Conversation Events
`white_label` boolean	Usuwa branding “Powered by Quickchat” z widgetu

Pre-chat Form

Field	Description
`prechat_active` boolean	Włącza formularz pre-chat. Gdy aktywny, odwiedzający muszą wypełnić formularz przed rozpoczęciem czatu
`prechat_header_text` string or null	Tekst nagłówka formularza pre-chat
`prechat_button_text` string or null	Etykieta przycisku zatwierdzania w formularzu pre-chat
`prechat_message_text` string or null	Tekst treści/instrukcji wyświetlany w formularzu pre-chat (HTML)

Zakres: write_all

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

Request Body — Wszystkie pola są opcjonalne. Dołącz tylko te pola, które chcesz zaktualizować.

W przypadku avatar_image wyślij dane obrazu zakodowane w base64 (maks. 5 MB). Odpowiedź zwraca URL zapisanego obrazu. Wysłanie avatar_image: null usuwa avatar (widget nie wyświetla wtedy żadnego avatara), a wysłanie use_default_avatar: true przywraca domyślny AI Agent Avatar.

AI Agent Avatar unification

Avatar czatu (logo nagłówka) i ikona pływającej bańki (launcher) zostały połączone w jeden obraz, AI Agent Avatar, przechowywany w avatar_image. Ikona bańki zawsze go odzwierciedla — nie istnieje już niezależny obraz launchera. Jeśli integrujesz się bezpośrednio z tym endpointem, zwróć uwagę na następujące zmiany zachowania:

Przesyłanie przez bubble_icon_image jest deprecated: teraz ustawia ujednolicony AI Agent Avatar, który zastępuje także obraz wyświetlany w nagłówku czatu. Zamiast tego użyj avatar_image.
bubble_icon_image: null to no-op. Wcześniej czyściło ikonę launchera; ponieważ launcher odzwierciedla avatar, usuwaj przez avatar_image: null.
Agenci, którzy nigdy nie dostosowali swojego avatara, wyświetlają domyślny AI Agent Avatar (zobacz default_avatar_image w odpowiedzi) zarówno w nagłówku, jak i w launcherze.

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 — Zwraca zaktualizowaną konfigurację widgetu (ten sam schemat co odpowiedź Get Widget Configuration).

Widget Configuration

Opcjonalne sprawdzenie przykładu