uHamkorДокументация
Руководство пользователя

UI-виджеты

Интерактивные карточки, которые агент показывает прямо в чате: зачем они нужны, как виджет попадает в диалог, ключевые понятия и приоритет данных.

🧩 UI-виджеты

UI-виджеты — это интерактивные карточки, которые агент показывает прямо в диалоге вместо обычного текста: формы, списки заказов, тарифы, графики, карточки бронирования. Посетитель нажимает кнопки и заполняет формы, не покидая чат.

Виджеты создаются в разделе Конструктор → Виджеты проекта и подключаются к агенту через Конструктор → Функции.

🎯 Зачем они нужны

  • Сбор структурированных данных — лид-формы, заявки, детали брони.
  • Показ информации — статус заказа, список товаров, небольшой график.
  • Действия — вызов API, отправка сообщения, открытие ссылки по кнопке.
  • Условный контент — один виджет с состояниями «предложение» и «подтверждено».
  • Обмен — экспорт виджета в файл .widget и импорт в другой проект.

🔄 Как виджет попадает в чат

Виджет никогда не появляется сам — его всегда показывает функция агента:

  • 1. Создайте и сохраните виджет на странице Виджеты.
  • 2. На странице Функции создайте функцию и в поле Действие выберите Показать виджет или Вызов API + виджет, затем укажите виджет.
  • 3. Посетитель задаёт вопрос, агент вызывает эту функцию.
  • 4. Агент заполняет данные виджета по его схеме (или используется ответ API).
  • 5. Виджет отображается внутри диалога — и в песочнице, и в чат-виджете на сайте.
  • 6. При нажатии кнопки запускаются собственные функции виджета.

🧱 Ключевые понятия

  • Code — разметка виджета. Пишется как JSX, хранится как JSON-дерево.
  • Schema — контракт данных. Агент заполняет именно эти поля.
  • Default — пример данных только для предпросмотра в редакторе.
  • Примеры — дополнительные наборы данных для проверки разных состояний.
  • Functions — реакции на действия: вызов API, запись переменных, отправка сообщения, ссылка, закрытие.
  • States — показ или скрытие части дерева по условиям.

📊 Приоритет данных

При отрисовке данные берутся в таком порядке:

ответ API  >  данные функции (действия)  >  пример Default  >  пустые значения из схемы

То есть Default никогда не перекрывает живые данные — он нужен только редактору.

📂 Импорт и экспорт

Кнопка Экспорт в редакторе скачивает файл .widget с деревом, схемой, примерами, функциями и состояниями. Импорт на странице «Виджеты» загружает его обратно. Импортированный виджет нужно заново привязать к функции в новом проекте.

🚧 Пока недоступно

  • Компонент Map.
  • Client function на основе iframe.
  • AI-билдер, создающий виджет по описанию.

➡️ Дальше