Настройки виджета

Читайте и обновляйте настройки виджета сайта через API.

Необязательные проверки примеров

Проверка кода виджета. Проверьте вставленный код на соответствие указанному Scenario ID. Это не загружает ваш сайт.

В совместимом браузере эти проверки также доступны как инструменты сайта. Ссылки открывают обычные формы.

Виджет является интерфейсом чата, который вы встраиваете на сайт. Он появляется как плавающий пузырёк в углу страницы: посетитель нажимает его и начинает разговор с AI-агентом. Виджет полностью настраивается: цвета, размер, положение, приветственные сообщения и поведение.

Эти настройки также влияют на встраивание: полноэкранную или встроенную версию того же чата, которую можно разместить непосредственно в макете страницы вместо плавающего пузырька. Виджет и встраивание используют общие настройки оформления, сообщений и поведения.

Эти endpoints позволяют программно настроить внешний вид 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` строка	Основное приветствие при открытии виджета (HTML). В панели: Каналы > Ваш сайт > Текстовое содержимое > Приветственное сообщение
`welcome_message2` строка	Дополнительное приветствие под основным. Доступно через API; отдельного поля в панели управления нет.
`header` строка	Текст в заголовке виджета. В панели: Каналы > Ваш сайт > Текстовое содержимое > Текст заголовка
`subtitle` строка	Подзаголовок под заголовком. Доступен через API; отдельного поля в панели управления нет.
`input_placeholder` строка	Подсказка в поле сообщения (например, «Введите сообщение…» )
`conversation_starters` массив строк или null	Предлагаемые начальные вопросы в виде кнопок при открытии виджета. До 3 вариантов примерно по 100 символов
`background_disclaimer_text` строка или null	Текст примечания внизу окна чата

Оформление

Поле	Описание
`primary_color` строка	Акцентный цвет виджета в CSS rgb (например, `"rgb(0, 122, 255)"`). Используется для кнопок, ссылок и сообщений пользователя
`header_color` строка	Фоновый цвет заголовка в CSS rgb
`header_text_color` логическое значение	Яркость текста заголовка. `true` = белый/светлый текст (для тёмного фона), `false` = тёмный текст (для светлого). Несмотря на название, это логическое значение, а не строка цвета
`size` строка	Размер кнопки запуска: `"small"`, `"medium"` или `"large"` (в панели: Маленький, Только поле ввода, Классический)
`location` строка	Положение виджета: `"top-left"`, `"top-right"`, `"bottom-left"`, `"bottom-middle"` или `"bottom-right"`
`launcher_label` строка или null	Текст маленькой кнопки запуска (`size: "small"`), до 25 символов. `null` использует значение по умолчанию (`"Ask AI"`); `""` оставляет только значок
`launcher_draggable` логическое значение	Разрешить посетителю перетаскивать кнопку запуска по странице
`window_height` целое число	Высота виджета в пикселях (400-1200)
`window_width` целое число	Ширина виджета в пикселях (300-700)
`avatar_image` строка или null	URL Аватара AI-агента, который показывается в заголовке чата и на плавающей кнопке. Загрузка через PATCH в base64. `null` означает, что аватар удалён и виджет его не показывает
`bubble_icon_image` строка или null	Устарело. Всегда повторяет `avatar_image`: значок кнопки и аватар чата теперь являются одним изображением (см. Объединение аватара AI-агента)
`default_avatar_image` строка	Только чтение. URL стандартного Аватара AI-агента, восстанавливаемого через `use_default_avatar`
`theme` строка	Цветовая тема: `"light"` или `"dark"` (фиксированные варианты) либо `"custom"` (палитра `widget_theme_custom`)
`widget_theme_custom` объект	Настройка темы. `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`) оформляет только боковую панель отдельной Страницы чата (игнорируется пузырьком и встраиванием); его `text` и `accent_text` по умолчанию равны `null`, то есть читаемый цвет вычисляется автоматически из соответствующего фона

Поведение

Поле	Описание
`popup_active` логическое значение	Показывать рядом с кнопкой виджета предложение начать разговор
`window_auto_open` логическое значение	Автоматически открывать виджет при загрузке страницы вместо одной кнопки
`header_collapse` логическое значение	Разрешить сворачивать заголовок для увеличения пространства чата
`typing` логическое значение	Показывать анимацию набора, пока AI создаёт ответ
`streaming_active` логическое значение	Передавать ответы AI по словам вместо показа целого сообщения сразу
`voice_active` логическое значение	Включить голосовой ввод: посетители могут отправлять сообщения через микрофон
`attachments_active` логическое значение	Разрешить прикреплять изображение или документ к сообщению. По умолчанию `true`; `false` скрывает кнопку вложений и запрещает загрузку
`link_tracking_active` логическое значение	Отслеживать переходы посетителей по ссылкам в ответах AI. Переходы появляются как события `tracked_link` в Событиях разговора
`white_label` логическое значение	Убрать подпись «Powered by Quickchat» из виджета

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

Поле	Описание
`prechat_active` логическое значение	Включить форму перед чатом. Посетитель должен заполнить её до начала общения
`prechat_header_text` строка или null	Заголовок формы перед чатом
`prechat_button_text` строка или null	Подпись кнопки отправки формы
`prechat_message_text` строка или 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. Значок кнопки всегда повторяет его; отдельного изображения кнопки больше нет. Если вы напрямую интегрируетесь с этим endpoint, учитывайте следующие изменения:

Загрузка через 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: возвращает обновлённые настройки виджета (схема как в ответе Получения настроек виджета).

Настройки виджета

Необязательные проверки примеров