Параметры инициализации виджета

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

С чего начать

Определите две вещи:

Где должен находиться чат: поверх страницы (popup) или внутри вашего блока (embedded).
Откуда брать оформление и функции: из сохранённых настроек канала (remote) или из кода сайта (local).

Для большинства сайтов подходит popup с config_source: "remote": изменения, сохранённые в кабинете, появляются без замены кода. local выбирайте, если версию настроек контролирует сам сайт.

Режим размещения

popup открывается поверх страницы по плавающей кнопке;
embedded занимает переданный container и не показывает плавающую кнопку.

Для embedded передайте существующий CSS-селектор или DOM Element. Если контейнер не найден, инициализация завершится ошибкой. Методы open(), close() и toggle() работают в обоих режимах.

button_only: true создаёт только внешний вид плавающей кнопки без iframe чата. Кнопка не реагирует на нажатие, open(), close() и toggle() ничего не открывают, а isOpen() возвращает false. Этот режим подходит для отдельного предпросмотра кнопки и несовместим с embedded. Поскольку iframe не создаётся и удалённые настройки канала не загружаются, вид кнопки задавайте через theme.button в коде.

Источник настроек

«Динамический» в кабинете соответствует config_source: "remote": тема и функции загружаются из сохранённых настроек канала. Язык и способ размещения остаются в коде сайта. Постоянные настройки theme и features меняйте в кабинете; из переданного объекта theme при первом запуске учитывается только theme_mode как переопределение светлой, тёмной или системной темы.
«Статичный» соответствует config_source: "local": theme и features входят в код. После изменения постоянных настроек скопируйте новый код и обновите его на сайте.

Выберите режим в блоке «Код для встраивания». На снимке цифрой 1 отмечен «Статичный» режим, цифрой 2 — «Динамический», цифрой 3 — привязка лида к авторизации на сайте. Готовый код находится ниже этого переключателя.

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

Встройте виджет в контейнер

Этот шаг нужен только для режима embedded. У контейнера должны быть реальные размеры: виджет занимает 100% его ширины и высоты. Параметры theme.width и theme.height задают размер popup-окна и не заменяют размеры контейнера.

<div id="senler-widget" style="width: 100%; height: 600px"></div>

<!-- Перед этим кодом подключите скрипт-загрузчик из готового кода канала. -->
<script>
  SenlerWidget.init({
    channel_id: "xxx",
    config_source: "local",
    display_mode: "embedded",
    container: "#senler-widget",
    theme: {
      border_radius: 18,
    },
    features: {
      element_selection: true,
    },
  });
</script>

Этот пример размещает чат в #senler-widget и включает выбор элементов страницы. URL скрипта-загрузчика и настоящий channel_id возьмите из готового кода в кабинете. Данные авторизованного посетителя добавляйте только вместе с серверной подписью, как описано ниже.

Данные пользователя

В user передаются данные, с которыми Senler создаёт или обновляет лида виджета. Передавайте только сведения о текущем посетителе, разрешённые вашей политикой обработки данных.

Поле	Что передавать и как оно используется
`external_id`	Стабильный ID авторизованного пользователя в вашей системе. Если поле задано, `user_hash` обязателен.
`user_hash`	HMAC-SHA256-подпись `external_id`, вычисленная на сервере сайта с секретом канала и переданная как 64 шестнадцатеричных символа.
`email`	Email лида. Непустое значение сохраняется при создании и обновляет существующего лида.
`phone`	Скрипт-загрузчик и API принимают строку, но текущая версия не сохраняет её в профиль лида. Не рассчитывайте на это поле до изменения серверного контракта.
`first_name`, `last_name`	Имя и фамилия лида. Непустые значения сохраняются при создании и обновлении.
`avatar_url`	Публичный HTTPS URL без логина и пароля. Явно переданное пустое, некорректное или локальное значение означает отсутствие аватара и удаляет ранее сохранённый аватар существующего лида.
`data`	Обычный JSON-совместимый объект дополнительных данных. При повторной инициализации непустой объект поверхностно объединяется с сохранёнными данными: отсутствующие ключи не удаляются.

external_id всегда передавайте вместе с user_hash: без подписи инициализация отклоняется. Переключатель привязки к авторизации в кабинете добавляет эти поля в сгенерированный код и открывает секрет и серверные примеры, но не включает и не отключает саму проверку. Секрет нельзя помещать в HTML, конфигурацию загрузчика или другой браузерный код. Подробная настройка показана в разделе «Привязка к авторизованному пользователю».

Например, на сервере Node.js подпись формируется по точному значению external_id:

import { createHmac } from "node:crypto";

const userHash = createHmac("sha256", channelSecret)
  .update(externalId)
  .digest("hex");

В браузер передайте только значения externalId и готового userHash в полях external_id и user_hash; channelSecret должен остаться на сервере.

При подписанной привязке история относится к одному аккаунту на разных устройствах. Без external_id Senler создаёт анонимную браузерную сессию, поэтому после смены браузера или устройства прежняя история недоступна.

Чтобы не собирать объект user вручную, нажмите кнопку с шестерёнкой рядом с готовым кодом. На снимке она отмечена цифрой 1 и открывает «Пример формирования кода».

В открывшемся окне отметьте нужные поля и скопируйте результат. Для user.data укажите ключ (9) и значение (10); новая строка добавляется кнопкой 11, строка удаляется кнопкой 12, а готовый пример копируется кнопкой 13. Конструктор показывает допустимый формат данных, но не меняет основной код канала. Поле phone в нём присутствует, хотя текущая серверная часть его не сохраняет.

Оформление

theme поддерживает:

Ключ	Что видит посетитель
`chat_title`	Заголовок чата.
`default_dialog_title`	Название нового диалога.
`theme_mode`	Светлая, тёмная или системная тема: `light`, `dark`, `auto`.
`position`	Положение popup-окна: `bottom-right`, `bottom-left`, `top-right`, `top-left`.
`width`, `height`	Размер окна: ширина `200–800`, высота `300–1000` пикселей.
`border_radius`	Скругление от `0` до `50` пикселей.
`shadow_enabled`	Тень окна.
`welcome_message`	Текст-подсказка в поле ввода. Техническое имя ключа сохранено для совместимости.
`empty_state_message`	Приветственный текст в пустом новом диалоге.
`welcome_buttons`	Быстрые вопросы до начала переписки.
`button`	Положение и цвета плавающей кнопки.

Локализованные тексты принимают объект { ru?: string, en?: string }. В каждом массиве welcome_buttons может быть до 8 непустых уникальных строк длиной до 120 символов. Нажатие сразу отправляет текст кнопки.

SenlerWidget.init({
  channel_id: "xxx",
  config_source: "local",
  theme: {
    empty_state_message: {
      ru: "Здравствуйте! Чем помочь?",
      en: "Hello! How can I help?",
    },
    welcome_buttons: {
      ru: ["Узнать цену", "Связаться с оператором"],
      en: ["Check the price", "Contact an operator"],
    },
  },
});

theme.button.position принимает те же четыре позиции и hidden. Чтобы скрыть плавающую кнопку, задайте theme.button.position: "hidden"; значение theme.position: "hidden" недопустимо. Цвета theme.button.light.background, theme.button.light.icon, theme.button.dark.background и theme.button.dark.icon задаются в формате #RRGGBB.

welcome_buttons нельзя изменить через updateRuntime. В режиме remote сохраните их в кабинете; в режиме local обновите код и заново инициализируйте виджет.

Функции чата

Ключ `features`	Что включает	Значение по умолчанию
`file_upload`	Прикрепление файлов.	`true`
`voice_messages`	Запись голосовых сообщений.	`false`
`emoji`	Выбор эмодзи.	`true`
`split_view`	На ширине от 640 пикселей показывает список диалогов и текущий чат рядом.	`true`
`element_selection`	Выбор элемента основной страницы для вопроса.	`false`

Для element_selection одной настройки недостаточно: чтобы агент получал устойчивые названия и мог находить элементы снова, добавьте разметку data-ai-*.

Справочник параметров init

Скрипт-загрузчик принимает только перечисленные параметры верхнего уровня:

Ключ	Тип	Обязательность / значение по умолчанию	Назначение
`channel_id`	`string`	Обязательный	ID канала типа «Виджет» из готового кода.
`user`	`object`	Необязательный	Данные посетителя. Если передан `external_id`, рядом обязательна серверная подпись `user_hash`.
`theme`	`object`	Необязательный	Оформление, popup-размеры, тексты и плавающая кнопка при `config_source: "local"`. При `remote` из объекта учитывается только начальный `theme_mode`.
`features`	`object`	Необязательный	Функции чата при `config_source: "local"`.
`lang`	`"ru" \| "en" \| "auto"`	`"auto"`	Язык интерфейса.
`config_source`	`"local" \| "remote"`	`"remote"`	Настройки в коде или сохранённые настройки канала.
`display_mode`	`"popup" \| "embedded"`	`"popup"`	Способ размещения чата.
`button_only`	`boolean`	`false`	Только неинтерактивная плавающая кнопка без iframe. Не совместим с `embedded`.
`container`	CSS-селектор или DOM `Element`	Обязательный для `embedded`	Контейнер embedded-виджета. Передайте его и при старте в `popup`, если позже переключите режим через Public API.
`shell`	`object`	Пустой объект	`collapse_button` и `mobile_edge_swipe`; оба выключены, пока не передано `true`.
`onCollapse`	`function`	Необязательный	Функция, вызываемая при запросе на сворачивание embedded-виджета.
`contextProvider`	`function`	Необязательный	Синхронный поставщик постоянного контекста страницы.
`customActions`	`object`	Пустой набор	Кнопки и действия сайта, доступные в чате.
`customActionsLanguage`	`"ru" \| "en"`	Не задан	Язык описаний `customActions`.
`debug`	`boolean`	`false`	Дополнительные сообщения скрипта-загрузчика в консоли.

Другие top-level ключи считаются ошибкой. Повторный SenlerWidget.init(...) удаляет текущий экземпляр и создаёт новый, поэтому для временных изменений используйте методы Public API.

Если загрузка задержалась

Индикатор появляется, если загрузка занимает больше 4 секунд. После 10 секунд скрипт-загрузчик показывает сообщение «Загрузка задерживается. Продолжаем попытки.» и кнопку «Скопировать для поддержки». Это информационное состояние: повторные попытки продолжаются автоматически.

Отчёт содержит версии загрузчика и протокола, номер попытки, длительность и этап сбоя, состояние сети и проверку ресурсов. Параметры URL, содержимое запросов, ID канала и пользователя и токены не копируются.

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

Что настраивать дальше

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