Конфігурація віджета

Читайте й оновлюйте конфігурацію віджета сайту через API.

Необов’язкові перевірки прикладів

Перевірка коду віджета. Перевірте вставлений код за наданим ID сценарію. Ваш сайт не завантажується.

У сумісному браузері ці перевірки також доступні як інструменти сайту. Посилання відкривають звичайні форми.

Віджет є інтерфейсом чату, який ви додаєте на сайт. Він з’являється як плаваюча кнопка в куті сторінки; відвідувачі натискають її, щоб почати розмову з AI-агентом. Віджет повністю налаштовується: ви керуєте кольорами, розміром, розташуванням, привітальними повідомленнями й поведінкою.

Ці налаштування також впливають на Embed, повносторінкову або вбудовану версію того самого чату, яку можна розмістити безпосередньо в макеті сторінки замість плаваючої кнопки. Віджет і Embed використовують спільну конфігурацію оформлення, повідомлень і поведінки.

Ці ендпоїнти дають змогу програмно налаштувати вигляд Quickchat AI на сайті: кольори бренду, форми перед чатом для збору даних відвідувачів, індикатори набору тексту, голосове введення тощо. Інструкції наведено в посібнику каналу Ваш сайт.

Область доступу: 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()

Відповідь 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 }
  }
}

Вміст і повідомлення

Поле	Опис
`welcome_message` string	Основне привітальне повідомлення під час відкриття віджета (HTML). Панель керування: Канали > Ваш сайт > Текстовий вміст > Привітальне повідомлення
`welcome_message2` string	Додаткове привітальне повідомлення під основним. Доступне через API; поля редактора в панелі керування немає.
`header` string	Текст у заголовку віджета. Панель керування: Канали > Ваш сайт > Текстовий вміст > Текст заголовка
`subtitle` string	Підзаголовок під заголовком. Доступний через API; поля редактора в панелі керування немає.
`input_placeholder` string	Текст-підказка в полі повідомлення (наприклад, «Введіть повідомлення…»)
`conversation_starters` array of strings or null	Початкові запитання у вигляді кнопок під час відкриття віджета. До 3 записів, кожен приблизно до 100 символів
`background_disclaimer_text` string or null	Текст застереження внизу вікна чату

Оформлення

Поле	Опис
`primary_color` string	Акцентний колір віджета як значення CSS rgb (наприклад, `"rgb(0, 122, 255)"`). Використовується для кнопок, посилань і бульбашок повідомлень користувача
`header_color` string	Колір фону заголовка як значення CSS rgb
`header_text_color` boolean	Яскравість тексту заголовка. `true` = білий/світлий текст (для темного фону), `false` = темний текст (для світлого фону). Попри назву, це булеве значення, а не рядок кольору
`size` string	Розмір кнопки запуску: `"small"`, `"medium"` або `"large"` (у панелі: Малий, Лише поле введення та Класичний)
`location` string	Розташування віджета на сторінці: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` або `"bottom-right"`
`launcher_label` string or null	Текст на малій кнопці запуску (`size: "small"`), до 25 символів. `null` використовує типовий текст (`"Ask AI"`); `""` показує лише значок
`launcher_draggable` boolean	Дозволити відвідувачам перетягувати кнопку запуску в інше місце сторінки
`window_height` integer	Висота віджета в пікселях (400-1200)
`window_width` integer	Ширина віджета в пікселях (300-700)
`avatar_image` string or null	URL Аватара AI-агента, який показується в заголовку чату й на плаваючій кнопці. Завантажується через PATCH у base64. `null` означає видалений аватар, і віджет його не показує
`bubble_icon_image` string or null	Застаріле. Завжди повторює `avatar_image`: значок кнопки й аватар чату тепер є одним зображенням (див. Об’єднання аватара AI-агента)
`default_avatar_image` string	Лише читання. URL типового Аватара AI-агента, який відновлює `use_default_avatar`
`theme` string	Режим кольорової теми: `"light"` або `"dark"` (фіксовані варіанти) чи `"custom"` (застосовує палітру `widget_theme_custom`)
`widget_theme_custom` object	Налаштування теми. `colors` (заголовок, акцент, бульбашка повідомлення, текст AI, `link`, поле введення, межі тощо, у hex або `rgb()`/`rgba()`) застосовуються лише коли `theme` дорівнює `"custom"`; `radius` (`"sm"`/`"base"`/`"lg"`/`"full"` для бульбашок, поля введення й кнопок), `font.size` (`"sm"`/`"base"`/`"lg"`) і `transparency` застосовуються в усіх режимах теми. `transparency.style` має значення `"none"` (суцільний фон, типово) або `"glass"` (прозорість із розмитою сторінкою позаду); `transparency.opacity` (40–95, типово 70) задає відсоток тонування Скла, а віджет не робить його прозорішим, ніж потрібно для читабельності тексту на будь-якому сайті (50 для Світлої теми, 65 для Темної, розраховане значення з кольорів для Власного варіанта). Якщо жодна непрозорість не забезпечує читабельність власної палітри, віджет показує суцільний фон, а збережене `transparency.style` залишається `"glass"`. Сторінка чату завжди має суцільний фон. У PATCH надсилайте весь об’єкт: відсутні ключі скидаються до типових значень, тому старий об’єкт без `transparency` повертає `"none"`. `widget_theme_custom` і кожен його розділ (`colors`, `radius`, `font`, `transparency`) мають бути об’єктами; `null` застосовує типові значення всієї теми або відповідного розділу, а інші значення відхиляються з 422. `colors.link` типово дорівнює `null`, тобто посилання успадковують колір навколишнього тексту. `colors.sidebar` (`background`, `text`, `accent`, `accent_text`) оформлює лише бічну панель окремої Сторінки чату (ігнорується кнопкою й Embed); `text` та `accent_text` типово дорівнюють `null`, тобто читабельний колір автоматично визначається за відповідним фоном

Поведінка

Поле	Опис
`popup_active` boolean	Показувати підказку біля кнопки віджета, щоб заохотити відвідувачів почати розмову
`window_auto_open` boolean	Автоматично відкривати віджет під час завантаження сторінки замість показу лише кнопки
`header_collapse` boolean	Дозволити згортати заголовок, щоб збільшити місце для чату
`typing` boolean	Показувати анімацію набору тексту, поки AI генерує відповідь
`streaming_active` boolean	Показувати відповідь AI поступово, слово за словом, замість усього повідомлення відразу
`voice_active` boolean	Увімкнути голосове введення: відвідувачі можуть надсилати повідомлення через мікрофон
`attachments_active` boolean	Дозволити додавати зображення чи документ до повідомлення. Типово `true`; задайте `false`, щоб приховати кнопку вкладень і відхиляти завантаження
`link_tracking_active` boolean	Відстежувати натискання посилань у відповідях AI. Переходи з’являються як події `tracked_link` у Подіях розмови
`white_label` boolean	Прибрати брендинг “Powered by Quickchat” із віджета

Форма перед чатом

Поле	Опис
`prechat_active` boolean	Увімкнути форму перед чатом. Відвідувачі мають заповнити її перед початком розмови
`prechat_header_text` string or null	Заголовок форми перед чатом
`prechat_button_text` string or null	Текст кнопки надсилання форми перед чатом
`prechat_message_text` string or null	Основний текст/інструкції форми перед чатом (HTML)

Область доступу: write_all

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

Тіло запиту: усі поля необов’язкові. Додавайте лише ті, які хочете оновити.

Для avatar_image надсилайте зображення в base64 (до 5 МБ). Відповідь повертає URL збереженого зображення. avatar_image: null видаляє аватар (віджет показується без нього), а use_default_avatar: true відновлює типовий Аватар AI-агента.

Об’єднання аватара AI-агента

Аватар чату (логотип заголовка) і значок плаваючої кнопки запуску об’єднано в одне зображення, Аватар AI-агента, що зберігається в avatar_image. Значок кнопки завжди повторює його; окремого зображення запуску більше немає. Якщо ви інтегруєте цей ендпоїнт безпосередньо, врахуйте зміни:

Завантаження через bubble_icon_image застаріло: тепер воно задає спільний Аватар AI-агента й також замінює зображення в заголовку чату. Використовуйте avatar_image.
bubble_icon_image: null нічого не робить. Раніше це очищувало значок запуску; тепер, оскільки він повторює аватар, видаляйте через avatar_image: null.
Агенти, для яких аватар ніколи не змінювали, показують типовий Аватар AI-агента (див. default_avatar_image у відповіді) і в заголовку, і на кнопці запуску.

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

Відповідь 200 OK: повертає оновлену конфігурацію віджета (та сама схема, що у відповіді Отримання конфігурації віджета).

Конфігурація віджета

Необов’язкові перевірки прикладів