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

Кратко

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

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

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

1. В списке типов канала выберите «Виджет».
2. Укажите понятное название виджета, например название сайта или раздела.
3. В поле разрешенные домены сайта введите домен, на котором будет работать чат.
4. Нажмите кнопку добавления с плюсом, чтобы добавить введённый домен в список. Если ошиблись, удалите лишний домен.
5. В завершение создайте канал-виджет кнопкой «Создать виджет».

Домены

Разрешённый домен определяет, на каком сайте можно запустить код этого канала. Это защита от использования виджета на посторонних сайтах. Указывайте адрес без протокола и пути, например example.com; для поддоменов можно использовать маску *.example.com.

При создании канала домен добавляется прямо в форму: введите его и нажмите кнопку с плюсом. Позже список можно изменить в настройках созданного канала.

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

На странице настроек канала в блоке виджета нажмите редактирование названия, измените название или иконку, затем нажмите «Сохранить». Кнопка «Отмена» закрывает редактирование без сохранения.

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

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

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

После создания кабинет открывает настройки нового канала. Сначала пройдите их сверху вниз, настройте внешний вид и функции чата, затем нажмите «Сохранить». Готовый фрагмент для сайта находится ниже, в блоке «Код для встраивания». Скопируйте его целиком и вставьте на сайт перед закрывающим тегом </body>.

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

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

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

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

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

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

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

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

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

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

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

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

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

В блоке «Кнопки на приветственном экране» выберите вкладку RU или EN и добавьте варианты первого вопроса. В русском поле и английском поле можно сохранить до 8 уникальных кнопок длиной не более 120 символов каждая. В виджете показывается только набор текущего языка; если для него список пуст, кнопок не будет.

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

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

Положение кнопки

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

Цвета кнопки

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

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

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

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

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

Функции чата

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

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

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

Лимит кредитов посетителя

Если для этого канала действует персональный лимит:

1. В настройках канала найдите блок «Лимиты кредитов». Он показывает правила, которые фактически применяются к виджету: общие периоды проекта или собственные периоды канала.
2. Нажмите «Настроить лимиты проекта», чтобы изменить периоды, отключить ограничение для этого канала или назначить ему собственные правила.
3. При необходимости включите «Предлагать оплатить лимит». Этот переключатель добавляет кнопку пополнения на экран исчерпания.

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

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

После исчерпания владелец виджета может предложить посетителю один или оба варианта продолжения:

• «Пополнить» — кнопка передаёт запрос сайту, а владелец сайта открывает свою форму оплаты и после успешной операции начисляет лиду дополнительные кредиты. Настройка события и проверка его источника описаны в разделе «Запрос на пополнение лимита».
• «Подключить свой ИИ» — кнопка открывает инструкции по подключению выбранного MCP-сервера проекта к совместимому ИИ-клиенту. Настройка и способы подключения описаны в разделе «Работа через MCP».

Это независимые варианты: подключение MCP позволяет работать с сервисом из собственного ИИ-клиента и само по себе не начисляет дополнительные кредиты для продолжения диалога в виджете.

Работа через MCP

Включите «Показывать кнопку Работать через MCP» и выберите активный MCP-сервер проекта. Кнопка «Управлять» открывает настройки MCP-серверов проекта. Без выбранного активного сервера включённую функцию сохранить нельзя.

Чтобы показать готовые команды для приложения ChatGPT и Codex CLI, включите «Показывать установку для ChatGPT», укажите HTTPS URL Git-маркетплейса без параметров запроса и ID плагина в формате plugin@marketplace. Вкладка ChatGPT появится только при заполненных и корректных URL и ID; остальные способы подключения доступны независимо от неё.

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

Способы подключения

• «Универсально»: скопируйте адрес MCP и добавьте его как удалённый MCP-сервер в совместимом AI-клиенте;
• ChatGPT: скопируйте две команды установки, выполните их в терминале и откройте новую задачу Codex в приложении ChatGPT или CLI;
• Claude: скопируйте адрес MCP, затем добавьте пользовательский коннектор в Customize → Connectors. Кнопка «Открыть Claude» ведёт сразу к коннекторам. В Team и Enterprise сервер сначала добавляет владелец организации;
• VS Code: скопируйте адрес MCP, запустите команду MCP: Add Server, выберите удалённый HTTP-сервер и область установки Global или Workspace;
• Cursor: нажмите «Добавить в Cursor». В установку передаются адрес и название выбранного MCP-сервера. Если Cursor не открылся, скопируйте адрес и добавьте сервер вручную через настройки MCP.

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

Авторизация

Обычное подключение использует OAuth: вход, выбор аккаунта и смену подключения выполняет AI-клиент или страница подключения Senler. Агент не получает отдельных инструментов для ввода токена, отключения аккаунта или смены проекта. Если нужно выбрать другой аккаунт, откройте управление подключением в AI-клиенте и пройдите авторизацию заново.

Ключ доступа для клиента без OAuth

Если AI-клиент умеет отправлять Bearer token, но не умеет проходить OAuth, используйте блок «Для клиентов без OAuth». Этот способ доступен для выбранного управляемого MCP-сервера Senler; для произвольного MCP URL используйте способ авторизации самого сервера.

1. Нажмите «Войти и создать ключ».
2. Во всплывающем окне войдите в подключаемый сервис и завершите авторизацию.
3. Сразу скопируйте созданный ключ: полностью он показывается только один раз.
4. Оставьте тот же адрес MCP, а в AI-клиенте передайте ключ как Authorization: Bearer <ключ>.

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

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

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

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

После изменения настройки предпросмотр пытается применить её сразу. Статус «Превью синхронизировано» означает, что изменение применилось во всех частях предпросмотра, которые нужны выбранному режиму: в popup это окно и кнопка, в embedded — только окно. Это не означает, что настройка уже сохранена в канале. При статичном коде после сохранения скопируйте новый код и обновите его на сайте. При динамическом коде сохранённые изменения применяются с сервера автоматически.

Если предпросмотр завершился ошибкой, откройте его статус. В нём можно скопировать диагностику для поддержки или нажать «Повторить». Повтор относится только к предпросмотру и не отправляет сообщение посетителю.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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