Встраивание Виджета чата (руководство разработчика)

Руководство по встраиванию виджета

Виджет представляет собой Web Component (<web-chat-agent>), который загружается асинхронно и работает на любом сайте, без фреймворков и сборки. Скрипт отображает плавающую кнопку чата, при клике на которую посетители открывают окно чата.

Код для встраивания

Вставьте этот фрагмент непосредственно перед закрывающим тегом </body>:

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
></web-chat-agent>

Замените YOUR_CHATBOT_ID на ваш ID чат-бота. Готовый код для встраивания находится в разделе Панель управления → ваш ассистент → Каналы → Виджет чата → Показать сведения об установке, скопируйте его оттуда, чтобы избежать опечаток.

Виджет обращается к API на том же источнике, откуда был загружен. Если скрипт загружен с webchatagent.com, запросы чата автоматически отправляются на webchatagent.com/api/..., вручную настраивать URL для API не требуется.

Как это работает

1. Скрипт с атрибутом async загружается в фоновом режиме и не блокирует отрисовку страницы.
2. Элемент <web-chat-agent> отображает плавающую кнопку чата.
3. Виджет запрашивает ваши настройки из панели управления (цвета, тексты, инструменты, приветственное сообщение) и применяет их. Дополнительные атрибуты не требуются.
4. Посетитель нажимает на кнопку, открывается окно чата, и сообщения отправляются вашему AI-чат-боту.

HTML-атрибуты

Все визуальные параметры из раздела Каналы → Виджет чата применяются автоматически. HTML-атрибуты элемента служат необязательными переопределениями, используйте их только для точечной настройки отдельных страниц (например, чтобы изменить позиционирование на посадочной странице). Имена атрибутов указываются в kebab-case (виджет внутри преобразует theme-color в свойство themeColor).

Ниже указаны встроенные значения по умолчанию для виджета. На практике большинство атрибутов оставляют пустыми, и они наследуют значения, настроенные в панели управления.

Основные настройки

Цвета

Все цветовые атрибуты принимают любые допустимые значения цвета в CSS (HEX, например #2563eb, rgb(), hsl()). Если значение не задано, виджет использует параметр из панели управления или встроенное резервное значение (фирменный синий цвет по умолчанию, #2563eb).

Изображения

Позиционирование

Контент и поведение

Обновление согласия во время выполнения

window.dispatchEvent(
  new CustomEvent('webchatagent:consent', {
    detail: { tracking: 'granted' }
  })
)

Передавайте denied, когда согласие отклонено или отозвано. Анонимные локальные триггеры остаются доступными. Матрица триггеров и адаптеры CMP описаны в руководстве Согласие на использование файлов cookie.

Кнопки подсказок

Кнопки быстрых действий, отображаемые под списком сообщений. У каждой кнопки есть видимый заголовок title и действие action (текст, отправляемый как сообщение пользователя при нажатии). Передайте массив JSON в качестве значения атрибута:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  prompt-buttons='[{"title":"Talk to support","action":"I need help with my order"},{"title":"Pricing","action":"What does it cost?"}]'
></web-chat-agent>

Session Context Data

Когда виджет работает внутри системы, которая уже знает посетителя, например CRM, личный кабинет или закрытый раздел сайта, страница встраивания может передать эти данные чат-боту. ИИ видит значения, ссылается на них в ответах и использует их для заполнения соответствующих аргументов при вызовах API коннекторов и инструментов MCP. Посетителю, чей номер обращения уже отображается на экране, больше не придется вводить его заново.

Контекстные данные отправляются с каждым запросом чата в рамках сессии, внедряются в системный промпт ИИ только для этого запроса и не сохраняются как отдельная запись.

Передача контекста через HTML-атрибут

Поддерживаются два формата. Простой формат не требует знаний JSON, это пары Ключ=Значение, разделенные точкой с запятой:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data="Customer=Jane Doe;Company=Acme GmbH;OrderID=A-1023"
></web-chat-agent>

Только первый символ = в каждой паре разделяет ключ и значение, поэтому значения, содержащие = (например, токены base64), остаются неповрежденными. Значение в этом формате не может содержать точку с запятой, для таких случаев используйте JSON:

<web-chat-agent
  chatbot-id="YOUR_CHATBOT_ID"
  context-data='{"Customer":"Jane Doe","Note":"VIP; priority support","OrderID":"A-1023"}'
></web-chat-agent>

При использовании JSON оборачивайте значение атрибута в одинарные кавычки, чтобы сохранить двойные кавычки внутри.

Передача контекста через JavaScript

Если вы предпочитаете JavaScript вместо атрибута (или он необходим, например в WordPress), установите глобальную переменную window.webchatagentContext. Ее можно безопасно задать до загрузки скрипта виджета, виджет считает ее при инициализации, поэтому порядок загрузки скриптов не имеет значения:

<script>
  window.webchatagentContext = {
    Customer: 'Jane Doe',
    OrderID: 'A-1023',
    userToken: 'opaque-token-validated-by-your-backend'
  }
</script>
<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>

Обновление контекста во время выполнения

Если данные изменились во время работы виджета (авторизация, переключение на другое обращение), отправьте событие webchatagent:context с простым объектом:

window.dispatchEvent(
  new CustomEvent('webchatagent:context', {
    detail: {
      Topic: 'billing',
      OrderID: 'A-1023'
    }
  })
)

Каждое событие заменяет весь контекст полностью; detail: null или {} очищает его. Приоритет при загрузке: сначала применяется атрибут context-data, затем window.webchatagentContext (если задан), а после них любые события. Контекст живет на странице, поэтому после перезагрузки страницы его нужно задать снова.

White-label решения: нейтральные к бренду псевдонимы window.chatWidgetContext (глобальная переменная) и chat-widget:context (событие) работают точно так же, поэтому страницам встраивания не требуется ссылаться на название платформы.

Ограничения

Не более 20 ключей, длина имени ключа до 64 символов, длина значения до 500 символов (числа и логические значения преобразуются в строки), 4 000 символов всего. Переносы строк и символы < > удаляются из ключей и значений. Ответы на запросы, содержащие контекстные данные, никогда не отдаются из кэша ответов.

Безопасность: контекстные данные не являются аутентификацией

Значения приходят из браузера посетителя. Любой пользователь может открыть DevTools и отправить произвольный контекст, поэтому ИИ настроен воспринимать его как неподтвержденные фоновые данные, никогда не стройте авторизацию на их основе.

Два правила для рабочей среды:

1. Ограничьте allowedDomains для вашего чат-бота в панели управления. Без этого любая страница сможет встроить вашего бота и передавать ему контекст.
2. Для поиска персональных данных передавайте скрытый токен вместо прямых идентификаторов. Сгенерируйте короткоживущий токен для авторизованного пользователя на стороне сервера, передайте его как значение контекста (например, userToken=...) и настройте эндпоинт API коннектора так, чтобы он валидировал токен перед возвратом данных пользователя. ИИ передаст токен в вызове API, а ваш бэкенд определит, к чему он дает доступ. Поддельный токен в таком случае ничего не вернет.

WordPress

Плагин для WordPress (начиная со следующего релиза) поддерживает контекстные данные на стороне сервера: фильтр webchatagent_context_data передает их для плавающего виджета (и по умолчанию для инлайн-встраиваний), а шорткод инлайн-виджета принимает атрибут context-data:

add_filter('webchatagent_context_data', function () {
    $user = wp_get_current_user();
    return $user->exists() ? 'Customer=' . $user->display_name : '';
});

[webchatagent_inline context-data="Topic=Support;OrderID=A-1023"]

В старых версиях плагина задавайте window.webchatagentContext или отправляйте событие webchatagent:context, оба варианта работают на любой платформе.

Пример: полная кастомизация

<script src="https://webchatagent.com/widget/web-chat-agent.js" async></script>
<web-chat-agent
  chatbot-id="abc-123-def"
  theme="modern"
  title="Support Chat"
  theme-color="#4f46e5"
  theme-text-color="#ffffff"
  user-message-color="#4f46e5"
  bubble-color="#4f46e5"
  font-family="Inter"
  initially-open="false"
  offset-x="30"
  offset-y="30"
></web-chat-agent>

Панель управления и HTML-атрибуты

Настройки из панели управления сохраняются на сервере и загружаются при инициализации виджета. HTML-атрибуты переопределяют их только для текущей страницы.

Рекомендация: Выполняйте всю визуальную настройку в панели управления. Используйте HTML-атрибуты только тогда, когда отдельная страница требует отличий, например другого позиционирования, принудительной темы или специфических кнопок подсказок для конкретной страницы.

Пользовательский CSS

Для изменений, выходящих за рамки описанных выше атрибутов, применяйте собственный CSS к внутренним элементам виджета. Каждый доступный для стилизации элемент имеет постоянный класс .wca-* (например, .wca-header, .wca-message, .wca-bubble), поэтому ваши селекторы продолжат работать после обновлений виджета и не требуют !important. Вы добавляете CSS в панели управления, и он внедряется в shadow DOM виджета. См. Пользовательский CSS.

Встроенный чат

Чтобы отобразить чат внутри макета страницы, а не в виде плавающей кнопки, используйте инлайн-вариант. Он загружает другой скрипт и другой элемент (<web-chat-agent-inline>):

<script src="https://webchatagent.com/widget/chat-widget-inline.js" async></script>
<web-chat-agent-inline chatbot-id="YOUR_CHATBOT_ID"></web-chat-agent-inline>

Инлайн-элемент принимает chatbot-id, необязательный container-height, а также tracking-consent и context-data (см. Session Context Data, атрибут и событие во время выполнения работают здесь аналогично); все остальные настройки берутся из раздела Каналы → Встроенный чат. Разместите элемент там, где должен отображаться чат, и задайте его размер с помощью родительского контейнера. Подробности см. в разделе Встроенный чат.

WordPress

В WordPress используйте официальный плагин WebChatAgent WordPress Plugin вместо ручной вставки скрипта. Он берет на себя встраивание и обновления. См. WordPress Plugin.

Одностраничные приложения (SPA)

Виджет работает с React, Vue, Angular и другими SPA без дополнительной настройки. Добавьте тег скрипта в index.html и поместите элемент <web-chat-agent> в основной каркас приложения (например, в корневой макет). Виджет сохраняет состояние при переходах по клиентским маршрутам, повторно монтировать его при навигации не требуется.