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

Кратко

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

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

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

Домены

• можно указывать домен вида 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, затем так же задайте цвет иконки в палитре и в поле 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;
• «Разделять окно на список диалогов и диалог» показывает список диалогов рядом с выбранным чатом на достаточно широком экране;
• «Выбор элемента страницы» показывает кнопку выбора элемента и передает выбранное место сайта вместе с вопросом пользователя.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В примере формирования кода можно включить 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.

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

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

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

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

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

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