Перейти до вмісту

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

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

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

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

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

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

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

Отримання конфігурації віджета

Section titled “Отримання конфігурації віджета”
Область доступу: read_all

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

Terminal window
curl https://app.quickchat.ai/v1/api/widget/configuration \
-H 'Authorization: Bearer <API_TOKEN>'

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

Стандартний віджет сайту показує на цьому екрані заголовок, повідомлення та кнопку початку розмови. Полів електронної пошти чи телефону тут немає, тож зробити ці дані обов’язковими перед початком чату не можна. Розумний збір даних може запитати їх під час розмови. Для обов’язкового збору контактів перед наданням доступу до чату потрібна окрема форма на сайті або власна інтеграція.

Оновлення конфігурації віджета

Section titled “Оновлення конфігурації віджета”
Область доступу: 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-агента

Section titled “Об’єднання аватара AI-агента”

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

  • Завантаження через bubble_icon_image застаріло: тепер воно задає спільний Аватар AI-агента й також замінює зображення в заголовку чату. Використовуйте avatar_image.
  • bubble_icon_image: null нічого не робить. Раніше це очищувало значок запуску; тепер, оскільки він повторює аватар, видаляйте через avatar_image: null.
  • Агенти, для яких аватар ніколи не змінювали, показують типовий Аватар AI-агента (див. default_avatar_image у відповіді) і в заголовку, і на кнопці запуску.
Terminal window
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
}'

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