Подключение виджета сайта

Кратко

Путь: пункт «Каналы» в боковом меню -> "Добавить канал" -> Виджет.

Форма создания

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

Домены

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

Название, иконка и домены

В настройках канала-виджета можно изменить название канала, иконку виджета и список разрешенных доменов.

Название и иконка влияют на то, как канал выглядит в кабинете и в списках. Для изменения иконки сначала включите редактирование названия: после этого область иконки становится доступной для загрузки файла.

Разрешенные домены определяют, на каких сайтах может работать код виджета. Если сайт открыт на домене, которого нет в списке, виджет может не запуститься или не принять соединение.

После создания

• кабинет показывает код виджета;
• код нужно вставить на сайт перед закрывающим тегом </body>;
• затем можно открыть настройки виджета и настроить внешний вид.

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

• название канала;
• иконка;
• разрешенные домены;
• цветовая схема: светлая, темная или авто;
• язык: русский, английский или авто;
• режим отображения: всплывающее окно или встроенный виджет;
• позиция всплывающего окна: сверху слева, сверху справа, снизу слева или снизу справа;
• ширина окна от 200 до 800;
• высота окна от 300 до 1000;
• радиус скругления от 0 до 50;
• тень;
• тексты на русском и английском;
• настройки кнопки;
• настройки функций чата;
• код для встраивания.

Окно и оформление

Режим отображения определяет, как виджет появляется на сайте:

• "Всплывающее окно" - виджет открывается по плавающей кнопке и показывает окно поверх страницы;
• "Встроенный" - виджет встраивается в контейнер страницы без плавающей кнопки.

Для всплывающего окна можно выбрать позицию окна, ширину и высоту. Ширина ограничена диапазоном 200-800 px, высота - 300-1000 px. Точное значение можно ввести в числовом поле, а ползунок ширины и ползунок высоты удобны для визуальной настройки. Скругление углов задается отдельно и работает для всплывающего и встроенного режима; его также можно менять ползунком. Переключатель "Тень" включает или выключает тень вокруг окна.

Цветовая схема задает светлый, темный или автоматический режим. В автоматическом режиме виджет ориентируется на настройки браузера пользователя. Язык виджета можно выбрать явно или оставить "Авто".

Скругление в предпросмотре меняется сразу, но сохраняется только после нажатия кнопки сохранения. При динамическом коде сохранённый border_radius загружается с сервера. При статичном коде после сохранения нужно заменить код на сайте. Для временного изменения уже работающего экземпляра разработчик может вызвать SenlerWidget.updateRuntime({ border_radius: 18 }); это значение не записывается в настройки канала.

Тексты виджета

• заголовок чата;
• стандартный заголовок диалога;
• подсказка в поле ввода;
• приветственное сообщение.

Тексты настраиваются отдельно для русского и английского языков. Вкладка языка в блоке "Тексты виджета" меняет только редактируемую версию текста, а не общий язык виджета.

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

Кнопка виджета

• позиция;
• цвет фона для светлой/темной темы;
• цвет иконки для светлой/темной темы.

Кнопка виджета есть только в режиме "Всплывающее окно". Ее можно поставить в один из четырех углов или скрыть. Если кнопка скрыта, виджет можно открыть только программно с сайта.

Цвета кнопки задаются отдельно для светлой и темной темы: фон кнопки и цвет иконки. Цвет можно выбрать в палитре или ввести точное HEX-значение в соседнее поле.

Закрытие и сворачивание

Во всплывающем режиме крестик закрытия уже есть в шапке виджета, отдельно добавлять его не нужно. SenlerWidget.close() скрывает окно, а SenlerWidget.open() показывает его снова.

Во встроенном режиме обычный крестик скрыт. Разработчик может включить крестик сворачивания внутри шапки через shell.collapse_button: true. Нажатие вызывает onCollapse(detail) и событие senler-widget:collapse-request, но не скрывает виджет автоматически. Сайт выбирает один обработчик и вызывает SenlerWidget.close() либо закрывает свою внешнюю панель. SenlerWidget.open() снова показывает скрытый wrapper. Готовый пример приведён в инструкции по Public API.

SenlerWidget.destroy() нужен не для сворачивания: он полностью удаляет экземпляр, после чего требуется повторная инициализация.

Функции чата

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

Переключатели в блоке "Функции чата" управляют тем, что видит пользователь сайта:

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

Предпросмотр и сохранение

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

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

История чатов в виджете

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

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

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

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

Режим изменения оформления выбирает, как сайт получает настройки:

• "Статичный" - настройки встроены прямо в код. После изменения оформления скопируйте новый код и обновите его на сайте;
• "Динамический" - сайт загружает настройки с сервера. Изменения применяются без замены кода, если сам код уже установлен правильно.

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

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

В примере формирования кода можно добавить данные пользователя: email, телефон, имя, фамилию, URL аватара и дополнительные параметры user.data.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Где это в интерфейсе

Основные элементы раздела:

• список каналов
• пункт «Каналы» в боковом меню
• кнопка добавления канала
• кнопка выбора платформы Виджет
• страница настроек канала
• область настроек виджета
• кнопка редактирования названия виджета
• поле названия виджета
• кнопка сохранения названия виджета
• кнопка отмены редактирования названия
• иконка виджета
• кнопка добавления разрешенного домена
• поле разрешенного домена
• кнопка подтверждения добавления домена
• кнопка отмены добавления домена
• кнопка удаления разрешенного домена
• позиция кнопки виджета: снизу слева
• позиция кнопки виджета: снизу справа
• позиция кнопки виджета: скрыта
• позиция кнопки виджета: сверху слева
• позиция кнопки виджета: сверху справа
• фон кнопки виджета в светлой теме
• палитра фона кнопки в светлой теме
• цвет иконки кнопки в светлой теме
• палитра иконки кнопки в светлой теме
• фон кнопки виджета в темной теме
• палитра фона кнопки в темной теме
• цвет иконки кнопки в темной теме
• палитра иконки кнопки в темной теме
• вкладка предпросмотра окна виджета
• вкладка предпросмотра кнопки на сайте
• мобильная вкладка окна виджета
• мобильная вкладка кнопки на сайте
• мобильная вкладка настроек виджета
• режим отображения: всплывающее окно
• режим отображения: встроенный
• язык виджета: авто
• язык виджета: английский
• язык виджета: русский
• тема виджета: авто
• тема виджета: темная
• тема виджета: светлая
• позиция окна виджета: снизу слева
• позиция окна виджета: снизу справа
• позиция окна виджета: сверху слева
• позиция окна виджета: сверху справа
• ширина окна виджета
• ползунок ширины окна
• высота окна виджета
• ползунок высоты окна
• скругление углов виджета
• ползунок скругления углов
• переключатель тени окна виджета
• вкладка русских текстов виджета
• вкладка английских текстов виджета
• название чата на русском
• название чата на английском
• название диалога по умолчанию на русском
• название диалога по умолчанию на английском
• текст в поле ввода на русском
• текст в поле ввода на английском
• приветственное сообщение на русском
• приветственное сообщение на английском
• переключатель загрузки файлов
• переключатель голосовых сообщений
• переключатель emoji
• переключатель раздельного вида списка диалогов и чата
• переключатель выбора элемента страницы
• кнопка сохранения настроек виджета
• статичный режим кода виджета
• динамический режим кода виджета
• переключатель привязки лида к авторизации
• готовый код для встраивания
• кнопка открытия примера формирования кода
• кнопка копирования кода виджета
• кнопка показа или скрытия секретного ключа
• кнопка копирования секретного ключа
• кнопка перегенерации секретного ключа
• кнопка отмены перегенерации секретного ключа
• кнопка подтверждения перегенерации секретного ключа
• вкладка серверного примера подписи
• кнопка копирования серверного примера подписи
• поле email в примере формирования кода
• поле телефона в примере формирования кода
• поле имени в примере формирования кода
• поле фамилии в примере формирования кода
• поле URL аватара в примере формирования кода
• дополнительные параметры user.data в примере формирования кода
• ключ дополнительного параметра user.data
• значение дополнительного параметра user.data
• кнопка добавления дополнительного параметра user.data
• кнопка удаления дополнительного параметра user.data
• поле предпросмотра примера кода
• кнопка копирования примера формирования кода