Необов’язкові перевірки прикладів
Section titled “Необов’язкові перевірки прикладів”- Перевірка коду віджета. Перевірте вставлений код за наданим ID сценарію. Ваш сайт не завантажується.
У сумісному браузері ці перевірки також доступні як інструменти сайту. Посилання відкривають звичайні форми.
Конфігурація віджета
Section titled “Конфігурація віджета”Віджет є інтерфейсом чату, який ви додаєте на сайт. Він з’являється як плаваюча кнопка в куті сторінки; відвідувачі натискають її, щоб почати розмову з AI-агентом. Віджет повністю налаштовується: ви керуєте кольорами, розміром, розташуванням, привітальними повідомленнями й поведінкою.
Ці налаштування також впливають на Embed, повносторінкову або вбудовану версію того самого чату, яку можна розмістити безпосередньо в макеті сторінки замість плаваючої кнопки. Віджет і Embed використовують спільну конфігурацію оформлення, повідомлень і поведінки.
Ці ендпоінти дають змогу налаштувати кольори, розмір, повідомлення та поведінку чату на сайті, зокрема Екран перед чатом. Інструкції зі встановлення наведено в посібнику з каналу сайту.
Отримання конфігурації віджета
Section titled “Отримання конфігурації віджета”GET https://app.quickchat.ai/v1/api/widget/configuration
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 } }}Вміст і повідомлення
Section titled “Вміст і повідомлення”| Поле | Опис |
|---|---|
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 | Текст застереження внизу вікна чату |
Оформлення
Section titled “Оформлення”| Поле | Опис |
|---|---|
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, тобто читабельний колір автоматично визначається за відповідним фоном |
Поведінка
Section titled “Поведінка”| Поле | Опис |
|---|---|
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” із віджета |
Екран перед чатом
Section titled “Екран перед чатом”| Поле | Опис |
|---|---|
prechat_active boolean | Показувати Екран перед чатом до розмови; відвідувачі продовжують за допомогою кнопки початку розмови |
prechat_header_text string or null | Заголовок Екрана перед чатом |
prechat_button_text string or null | Підпис кнопки початку розмови |
prechat_message_text string or null | Повідомлення на Екрані перед чатом (HTML) |
Стандартний віджет сайту показує на цьому екрані заголовок, повідомлення та кнопку початку розмови. Полів електронної пошти чи телефону тут немає, тож зробити ці дані обов’язковими перед початком чату не можна. Розумний збір даних може запитати їх під час розмови. Для обов’язкового збору контактів перед наданням доступу до чату потрібна окрема форма на сайті або власна інтеграція.
Оновлення конфігурації віджета
Section titled “Оновлення конфігурації віджета”PATCH https://app.quickchat.ai/v1/api/widget/configuration
Тіло запиту: усі поля необов’язкові. Додавайте лише ті, які хочете оновити.
Для avatar_image надсилайте зображення в base64 (до 5 МБ). Відповідь повертає URL збереженого зображення. avatar_image: null видаляє аватар (віджет показується без нього), а use_default_avatar: true відновлює типовий Аватар AI-агента.
Об’єднання аватара AI-агента
Section titled “Об’єднання аватара AI-агента”Аватар чату (логотип заголовка) і значок плаваючої кнопки запуску об’єднано в одне зображення, Аватар AI-агента, що зберігається в avatar_image. Значок кнопки завжди повторює його; окремого зображення запуску більше немає. Якщо ви інтегруєте цей ендпоїнт безпосередньо, врахуйте зміни:
- Завантаження через
bubble_icon_imageзастаріло: тепер воно задає спільний Аватар AI-агента й також замінює зображення в заголовку чату. Використовуйтеavatar_image. bubble_icon_image: nullнічого не робить. Раніше це очищувало значок запуску; тепер, оскільки він повторює аватар, видаляйте черезavatar_image: null.- Агенти, для яких аватар ніколи не змінювали, показують типовий Аватар AI-агента (див.
default_avatar_imageу відповіді) і в заголовку, і на кнопці запуску.
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: повертає оновлену конфігурацію віджета (та сама схема, що у відповіді Отримання конфігурації віджета).