Установка виджета

Получите код подключения в настройках канала и установите виджет на свой сайт.

Основной раздел: Виджет.

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

Оформление и функции загружаются из настроек канала. Сохраните изменения: они появятся на сайте при следующей инициализации виджета без замены кода. Разработчик может переопределить отдельные поля через theme и features в init; такие значения имеют приоритет, а остальные берутся из настроек канала. Например, theme: { height: 700 } закрепляет только высоту popup-окна.

Готовый код содержит параметры подключения, язык и режим размещения, но не полный снимок оформления и функций. Если меняются язык, режим размещения или привязка к авторизации, обновите код на сайте. Подробнее о наследовании — в справочнике настроек.

Привязку лида к авторизации на сайте включайте, только если сервер сайта будет передавать подписанные данные пользователя. Готовый код для встраивания доступен только для просмотра. Измените параметры выше, дождитесь обновления кода, при необходимости откройте пример с данными пользователя, затем нажмите кнопку копирования.

Для получения кода и секретного ключа нужно право управления каналом. Доступа только на просмотр недостаточно; участник с правом управления может скопировать код для разработчика сайта.

Пример формирования кода

В блоке «Поля пользователя» отметьте данные, которые сайт будет передавать виджету.

Поле предпросмотра примера обновляется сразу после каждого выбора.

В примере формирования кода можно включить email, телефон, имя, фамилию, URL аватара и дополнительные параметры user.data. Текущая серверная часть принимает phone, но не сохраняет его в профиль лида; точное назначение каждого поля приведено в справочнике параметров.

Выбор полей в примере не меняет основной сгенерированный код в настройках. В дополнительном параметре заполните ключ и значение; новую пару создаёт кнопка «Добавить», а ненужную можно удалить. Такие данные используют для персонализации и контекста: тариф, город, текущий раздел сайта, источник перехода или другие сведения, которые помогают оператору и агенту лучше понимать пользователя.

Проверьте выбранные данные и нажмите отдельную кнопку копирования.

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

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

После установки кода разработчик может использовать дополнительные возможности виджета:

• инициализировать виджет на сайте один раз после установки кода;
• открывать, закрывать или переключать видимость виджета в popup- и embedded-режиме по событию на сайте;
• показывать крестик сворачивания во встроенном виджете и обрабатывать запрос на сворачивание на стороне сайта;
• выбирать существующий диалог без отправки нового сообщения;
• открывать виджет сразу с текстом сообщения или контекстом следующего вопроса;
• передавать постоянный контекст текущей страницы, карточки, заказа или проекта;
• обновлять контекст, сообщение или доступные действия без переустановки виджета;
• временно менять theme_mode, border_radius, display_mode и параметры shell через updateRuntime;
• объявлять действия сайта через customActions, чтобы агент мог показать в чате кнопку, а сайт выполнил действие на своей стороне;
• подключать сценарий AI-правки текста в поле сайта: сайт показывает свой интерфейс, а виджет создает диалог и возвращает вариант правки;
• задавать язык описаний действий сайта через customActionsLanguage, если они написаны только на русском или только на английском;
• удалять виджет со страницы, если сайт сам управляет жизненным циклом виджета;
• привязать чат к авторизованному пользователю сайта через external_id и user_hash.

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

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

Что важно помнить

• скрывать можно плавающую кнопку, а не само окно виджета;
• если нужно убрать кнопку с сайта, выберите позицию кнопки "Скрыта";
• во встроенном режиме плавающая кнопка не используется;
• close() скрывает виджет, сохраняя его экземпляр и состояние диалога, а destroy() полностью удаляет виджет;
• кнопка shell.collapse_button только запрашивает сворачивание, поэтому сайт должен обработать onCollapse или senler-widget:collapse-request.

Привязка к авторизованному пользователю

• нужна для привязки пользователя сайта к авторизованному аккаунту;
• включает секретный ключ;
• секрет можно показать, скопировать или регенерировать;
• регенерация секрета опасна: старый ключ сразу перестанет работать;
• если сайт передаёт external_id, подпись user_hash обязательна независимо от переключателя привязки;
• в примере кода можно указать email, телефон, имя, фамилию, аватар и дополнительные data-поля.

Переключатель «Привязка лида к авторизации на сайте» нужен, если пользователь должен видеть историю переписки после входа с другого устройства или браузера. Для включения понадобится разработчик сайта: сайт должен передавать внешний ID пользователя и подпись user_hash.

Секретный ключ храните только на сервере сайта. Его можно показать или скрыть, скопировать либо перегенерировать. Перегенерация сразу отключает старый ключ, поэтому сначала подготовьте обновление на сервере. В окне подтверждения можно отменить замену или подтвердить её.

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

Если агент должен вызывать установленный MCP от имени авторизованного посетителя, разработчик сайта может передать его токен с backend и связать с лидом при инициализации. Для этого есть отдельная инструкция «Авторизация пользователя сайта в MCP». Подпись user_hash и токен внешнего сервиса выполняют разные задачи.

Выбор элемента

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

Если виджет не отображается на сайте

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