Виджет на сайте
Как добавить чат на сайт, настроить приветствие и проверить доставку сообщений. Код установки, разрешённые сайты и поиск ошибок.
На этой странице
Виджет представляет собой кнопку чата и окно переписки на вашем сайте. Посетитель задаёт вопрос, бот отвечает по реакциям, а оператор может продолжить разговор в кабинете.
Для первой установки используйте быстрый старт. Ниже приведены подробные настройки и техническая справка для установки на сайт. Если код добавляет разработчик, передайте ему разделы о разрешённых сайтах, фрагменте установки и диагностике.
Выберите пресет
В разделе «Виджет» выберите набор начальных настроек, пресет: «Онлайн-школа» или «Интернет-магазин». Вы сможете изменить его тексты, цвета и поведение. Обновление самого пресета в будущем не изменит вашу опубликованную конфигурацию. Применение пресета сейчас может заменить текущие правки, поэтому сначала просмотрите изменения.
Что можно настроить
Студия виджета разбита на семь вкладок: «Поведение», «Приветствие и автоответы», «Рабочее время», «Контакты и приватность», «Диалоги», «Внешний вид» и «Установка». На них настраиваются бренд, кнопка запуска, панель, приветствие, тизер, видимость по адресам, уведомления посетителю, быстрые действия, форма перед чатом, рабочее время и поведение. Полное описание каждого поля на каждой вкладке – в «Настройках виджета». Быстрое действие отправляет в диалог заданный текст и сразу запускает выбранную для него реакцию. Привяжите реакцию к каждой кнопке, чтобы посетитель получил ответ.
Форма может собирать имя, email, телефон или номер заказа. Email и телефон лишь неподтверждённо дополняют профиль: они не подтверждают личность, не объединяют людей и не создают согласие на маркетинговые рассылки. Рабочие часы используют часовой пояс, недельные интервалы и исключения. Они описывают расписание, а не присутствие оператора в реальном времени.
Короткое приглашение рядом с кнопкой можно расположить сбоку от неё или над ней.
Вне рабочих часов виджет умеет сам отправлять автоответ с вашим текстом. Это обычное сообщение диалога, а не подпись в шапке: его видит посетитель, его видит оператор в своей папке входящих, и оно остаётся в истории переписки. Отправляется один раз за нерабочий период, а не на каждое сообщение посетителя.
Предпросмотр перед публикацией
Предпросмотр показывает виджет на компьютере и телефоне, на светлом и тёмном фоне. Проверьте кнопку, приглашение рядом с ней (тизер), приветствие, форму перед чатом и сообщение вне рабочего времени. На узком экране окно размещается снизу с учётом доступного места.
Разрешённые origin
В «Разрешённые сайты» добавьте адреса сайтов, на которых нужен чат. Адрес состоит из https://, домена и порта, если он нестандартный. Путь к конкретной странице не нужен. Такой адрес называется origin. Например, для https://example.com/catalog укажите https://example.com:
https://example.com
https://www.example.com
https://shop.example.com
http://localhost:3000
Адрес должен совпадать точно. Варианты с www и без него, http и https, а также разные поддомены считаются разными адресами. Для опубликованного сайта нужен HTTPS. HTTP допустим только при разработке на собственном компьютере, например для localhost. Если адрес страницы не сохранён в списке, виджет не запустится.
Этот список ограничивает встраивание в браузере. Он не заменяет авторизацию на сервере или защиту от злоупотреблений.
Установите фрагмент кода
Откройте «Виджет» → «Установка», скопируйте весь фрагмент и добавьте его один раз в общий шаблон каждой страницы, где нужен виджет, лучше перед </body>:
<script>
window.mybot = window.mybot || {}; window.mybot.key = "eu-1a2b3c4d-...";
</script>
<script async src="https://getmybot.dev/loader.js"></script>
Присваивание ключа должно идти до загрузчика, а async нужно сохранить. Не разделяйте фрагмент. Дублировать его не нужно, но и не страшно: виджет монтируется один раз, а window.mybot = window.mybot || {} не затирает уже установленные track/identify. Подойдёт поле footer-скриптов CMS или контейнер диспетчера тегов, если он подключается один раз на странице.
Ключ установки: публичный идентификатор, а не пароль. Он может быть виден в исходном коде страницы и не позволяет войти в кабинет, читать диалоги, экспортировать людей или менять настройки бота. Если ключ нужно заменить, обратитесь в поддержку: старый фрагмент перестанет работать, и его нужно будет обновить.
Автоматическая диагностика
Выберите разрешённый сайт и страницу на нём, затем нажмите «Проверить установку». Сначала система проверит, открывается ли страница и есть ли в её исходном коде загрузчик виджета и ключ. На этом этапе она не выполняет JavaScript. Поэтому, если код добавляет диспетчер тегов или одностраничный сайт (SPA), результат первого этапа может быть неопределённым.
Затем диагностика открывает страницу в браузере и проверяет загрузку виджета. Только статус готовности виджета подтверждает успешную установку. Если время ожидания истекло, виджет не сообщил о готовности. Причину нужно искать в подробностях проверки и консоли браузера: это может быть настройка сайта, сети или ограничение браузера.
CSP, диспетчеры тегов и блокировщики
Если на сайте настроен Content Security Policy, разрешите указанному рядом с фрагментом хосту загружать скрипты и выполнять сетевые запросы виджета. Возможности CSP зависят от браузера, поэтому статические признаки могут остаться неопределёнными. Сопоставляйте результат выполнения с консолью браузера.
Диспетчеры тегов и SPA могут добавить фрагмент уже после отдачи исходного HTML. В таком случае статическая проверка останется неопределённой, даже если проверка в реальном браузере успешна. Также проверьте сайт в приватном окне с отключёнными расширениями: блокировщики контента могут удалить или заблокировать виджет.
Посетители, черновики и история
При первом запуске виджет сохраняет в этом браузере анонимный идентификатор посетителя. При повторном посещении восстанавливаются та же привязанная к боту личность, безопасная история диалога, локальный черновик, состояние формы и скрытия. Другой браузер, устройство или очищенные данные сайта создают нового анонимного посетителя.
Виджет изолирован от страницы в закрытом Shadow DOM. Его стили не попадают на сайт, а CSS сайта не меняет виджет. Контейнер не перехватывает клики по странице вне кнопки запуска и панели.
Связывание с VK
Если связывание VK доступно для вашего проекта, подключите канал сообщества VK и добавьте его включённую ссылку https://vk.me/имя_сообщества или https://vk.me/club<ID> в настройках виджета. Ссылка должна соответствовать подключённому сообществу; допускается один параметр ref_source. Подробнее о кнопках каналов – в настройках виджета.
- Посетитель нажимает VK в виджете, открывает сообщество и отправляет ему сообщение. Затем он возвращается в виджет.
- Когда аккаунт найден, виджет показывает его замаскированное обозначение и последствия объединения. Посетитель сам нажимает «Связать». После подтверждения история и уже связанные каналы сохраняются.
- Если подтверждение не появилось или срок попытки истёк, посетитель может повторить связывание. Обычный переход в VK сам по себе не объединяет профили.
Если виджет не может подтвердить право посетителя на прежний диалог, он предложит подтвердить ранее подтверждённую почту, если она доступна, либо начать новый чат. Новый чат не переносит прежнюю историю. Можно также открыть VK без связывания. Если функция связывания недоступна или ссылка не соответствует подключённому каналу, кнопка остаётся обычной ссылкой.
Связывание с Instagram
Для доступности привязки Meta должна подтвердить подписку подключённой страницы на события перехода и нажатий. Если аккаунт подключён ранее, может потребоваться повторно выбрать его или переподключить, чтобы проверить подписку.
Если функция доступна для проекта, добавьте в настройках виджета ссылку https://instagram.com/имя_аккаунта на подключённый аккаунт Instagram. Посетитель открывает Instagram из виджета и возвращается в него. Если аккаунт найден, виджет показывает его замаскированное обозначение и последствия объединения; связывание происходит только после явного нажатия «Связать».
Для нового диалога Meta требует настроить варианты начала диалога (icebreakers) и нажать один из них. Доставка данных для связывания не гарантируется, в том числе в существующих диалогах. Если функция недоступна или попытка не удалась, посетитель может открыть обычную ссылку без связывания. Обычный переход сам по себе не объединяет профили.
Связывание с Facebook Messenger
Если функция доступна, добавьте в настройках виджета ссылку https://facebook.com/school.page на подключённую страницу. Для новых диалогов в настройках Messenger должна быть настроена кнопка «Начать» (Get Started). Посетитель открывает Messenger из виджета. В новом диалоге он нажимает «Начать», затем возвращается в виджет. Найденный аккаунт показывается с замаскированным обозначением и последствиями объединения. Связывание происходит только после явного подтверждения.
Meta предупреждает, что данные перехода могут не передаваться некоторым пользователям Messenger для Android или страницам с географическими ограничениями. Если связывание недоступно или попытка не удалась, обычная ссылка остаётся доступной и сама по себе не объединяет профили. Подробнее: документация Meta о ссылках m.me.
Всплеск новых посетителей
У появления нового посетителя есть ограничение по скорости, отдельное на каждый аккаунт: примерно два новых посетителя в секунду в среднем, с запасом на всплеск около 500 подряд. Обычному сайту этого хватает с большим избытком: речь о порядке 170 000 новых посетителей в сутки.
Если запас исчерпан, инициализация виджета для нового посетителя отвечает 429 с заголовком Retry-After: 60, и виджет пробует снова позже. Уже известные посетители не затрагиваются: их диалоги, история и ответы операторов продолжают работать как обычно. Ограничение сознательно устроено так, чтобы всплеск замедлял приток новых собеседников, а не выключал общение с теми, кто уже пишет.
Почему ограничение на аккаунт, а не на IP-адрес: появление посетителя: единственное действие анонимного браузера, которое создаёт у вас реальную работу и расходует ваш лимит уникальных посетителей. Тот, кто хочет накрутить его, легко меняет IP-адреса, а счёт приходит вам. См. Тарифы про подсчёт уникальных посетителей.
Если при обычной работе сайта новые посетители получают ответ 429, проверьте, сохраняется ли их идентификатор между переходами по страницам. Например, сайт может очищать хранилище браузера при каждой загрузке и представлять одного человека как множество новых посетителей. Если причина неясна, напишите в поддержку: порог настраивается на стороне платформы.
Связывание посетителя с вашим пользователем
Когда посетитель авторизован на вашем сайте, дождитесь доступности mybot.identify() и только затем вызывайте его. Загрузчик и пакет виджета работают асинхронно, а очереди команд до загрузки нет. Запускайте этот код после того, как станет известен авторизованный пользователь вашего сайта:
async function identifySignedInVisitor() {
const deadline = Date.now() + 3_000;
while (Date.now() < deadline) {
const identify = window.mybot?.identify;
if (typeof identify === "function") {
identify(async (visitorId) => {
const response = await fetch("/mybot-sign", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ userId: currentUser.id, visitorId }),
});
return response.json(); // { userId, signature, expiresAt }
});
return;
}
await new Promise((resolve) => window.setTimeout(resolve, 50));
}
console.warn("GetMyBot identify() не готов; посетитель останется анонимным.");
}
void identifySignedInVisitor();
Код опрашивает API не больше трёх секунд, затем останавливается, а не вызывает отсутствующий API и не повторяет попытки бесконечно. При тайм-ауте, ошибке функции или подписи посетитель продолжит общаться анонимно. Функция получает асинхронно созданный visitorId. Передавайте его только на свой авторизованный сервер, не логируйте, не пересылайте и не добавляйте в клиентскую аналитику. Сервер возвращает { userId, signature, expiresAt } и вычисляет подпись, но не браузер:
signature = hex(HMAC-SHA256(key: secret, message: userId + "\n" + visitorId + "\n" + expiresAt)).slice(0, 32)
Разделители: настоящие переводы строки. expiresAt: Unix-время в секундах: оно не должно быть в прошлом и не может быть больше чем на 24 часа вперёд. Привязывайте подпись к конкретному посетителю и создавайте её непосредственно перед возвратом.
Показ и смена секрета
Секрет identify() появляется в настройках виджета после подключения веб-канала. Показ не делает секрет недействительным. Показывайте его только когда он нужен серверу, затем убирайте с экрана и очищайте буфер обмена вручную: платформа не может надёжно очистить буфер браузера.
Меняйте секрет, только когда готовы обновить сервер: смена сразу делает старый секрет недействительным, без периода перекрытия. Она влияет лишь на связывание личностей. Текущие чаты, фрагмент установки и разрешённые origin продолжают работать.
Поп-апы и формы заявок
В разделе Поп-апы настраиваются всплывающие окна для сайта. Есть пять вариантов размещения: небольшой блок, большой блок, встроенный блок, полноэкранное окно и полоса. Один и тот же контент могут показывать виджет на сайте и клиентский SDK в приложении. Правила показа определяют, кто увидит окно. Например, если мобильные устройства исключены, в приложении окно не появится. Если для варианта выбран неподдерживаемый способ показа, активировать его нельзя.
Галерея шаблонов даёт готовую заготовку: по одной на каждую раскладку плюс Сбор заявок (большой блок с полем email, флажком согласия и кнопкой отправки) и Приглашение в чат (небольшой блок с кнопкой «открыть чат»).
Контент. Вариант поп-апа либо использует свои текущие блоки, либо ссылается на опубликованный документ типа Попап из Студии контента. Ссылка фиксирует точную версию, поэтому повторная публикация документа не изменит уже работающий поп-ап. Существующие поп-апы продолжают работать на своих блоках, ничего не переписывается автоматически.
Таргетинг, или правила показа, определяет, когда появляется поп-ап. Посетитель должен одновременно подходить по странице, поведению, аудитории и устройству.
- Страницы. До 20 шаблонов включения и 20 исключения. Шаблон: абсолютная ссылка
http(s), точная или заканчивающаяся одной*для совпадения по префиксу; строка запроса игнорируется. Пустой список включения означает любую страницу, а совпадение с исключением всегда сильнее совпадения с включением. - Поведение. Задержка в секундах, глубина прокрутки от 0 до 100 %, намерение уйти и минимальный номер визита.
- Аудитория. До 20 сегментов; посетитель должен входить хотя бы в один из них, а не во все. Сегменты вычисляются на сервере, поэтому браузер никогда не узнаёт определение сегмента: тому, кто не подходит, правило просто не отправляется.
- Устройство. Десктоп, мобильный, планшет; если ничего не выбрано: любое устройство.
Правила по страницам и поведению проверяются в браузере, уже на том правиле, которое сервер решил отправить.
Частота ограничивает, как часто один посетитель видит поп-ап: задайте максимальное число показов, паузу в часах и остановку после целевого действия (конверсии). Для нового поп-апа по умолчанию установлены 3 показа, пауза 24 часа и остановка после конверсии. Ноль в поле «показывать не больше» снимает ограничение по числу показов. Чтобы полностью остановить поп-ап, выключите его. Браузер хранит отметку, чтобы не показать окно, которое сервер уже отклонит; окончательное решение о частоте принимает сервер.
Если на странице подходят несколько поп-апов, выигрывает тот, у кого меньше номер приоритета.
Если у поп-апа от двух до пяти вариантов, можно сравнить их в A/B-тесте. Посетители распределяются между вариантами по заданным долям и при повторных визитах видят тот же вариант. Перед активацией проверка предупредит, что для теста используется цель конверсии по умолчанию и результат учитывается в течение 30 дней после показа (окно атрибуции).
В стандартном поп-апе целевое действие учитывается при нажатии ссылки или кнопки открытия чата, а также при успешной отправке формы. Открытие чата не означает отправку сообщения или оплату. Собственный скрипт может отдельно сообщить о целевом действии через mybotPopup.track.
Кнопки
В поп-апе может быть до пяти кнопок. Каждая выполняет одно действие: закрывает окно, открывает чат, ведёт по https://-ссылке, отправляет форму или записывает событие аналитики. Запуск произвольного callback или JavaScript и переход по HTTP-ссылке не поддерживаются. У каждой кнопки должен быть уникальный технический ключ в нижнем регистре и надпись не длиннее 80 символов. Кнопку «отправить форму» можно добавить только к поп-апу с формой. Если список кнопок настроен неверно, он отклоняется целиком и на сервере, и в виджете.
Формы заявок
Форма собирает до 12 полей. Типы полей: короткий текст, email, телефон, список вариантов, флажок и скрытое поле. У каждого поля есть уникальный технический ключ в нижнем регистре, и ключи, похожие на чувствительные, отклоняются: всё, что содержит password, passwd, pwd, token, secret, card, cvv, cvc, government, passport, ssn, authorization или cookie, причём подчёркивания не спасают: pass_word тоже отклоняется. Не запрашивайте в поп-апе пароли и платёжные данные.
Значения ограничены: максимальная длина не больше 400 символов (у поля email от 64 до 254), не больше 50 уникальных вариантов не длиннее 120 символов каждый, телефон в виде + и от 7 до 15 цифр, у флажка только true или false. Скрытое поле всегда берёт значение из сохранённого на сервере описания, а не из браузера, даже если браузер прислал ту же константу. Значение поля, которого в форме нет, отклоняется целиком. Можно требовать явного согласия перед отправкой формы.
Поле может записываться в свойство профиля (property.<имя>). Email и телефон остаются обычными свойствами профиля. Они не создают и не подтверждают контакт в канале, поэтому два посетителя никогда не склеиваются просто из-за одинакового адреса, а обычная отправка формы не создаёт согласия на маркетинговые письма.
Чтобы принимать подписку на рассылку, добавьте обязательное поле email и отдельный флажок с понятной подписью о получении писем. Включите «Подписывать на email-рассылку» и выберите оба поля. Флажок обработки персональных данных для подписки не используется. Если адрес ещё не подтверждён, посетитель может получить код и ввести его прямо в поп-апе. Подтверждение владения адресом само по себе не означает согласие на рассылку.
Для новой или возобновляемой подписки после отправки формы посетителю направляется отдельное письмо. Он должен перейти по ссылке и подтвердить подписку на открывшейся странице. Только после этого подписка становится активной и возникает событие $email_subscribed. Если не удалось подготовить подтверждение, форма показывает сообщение и предлагает повторить попытку. Постановка письма в очередь не гарантирует его доставку. Снятый флажок не оформляет подписку; уже активная подписка не создаёт повторного события. Жалоба или жёсткая блокировка адреса не снимаются подпиской.
При двойном нажатии или повторной отправке форма создаёт одну заявку, а не две. Для этого каждой отправке назначается уникальный ключ (ключ идемпотентности).
Что мешает активировать поп-ап
Активация проходит проверку на сервере и запрещается, если верно хотя бы одно:
- виджет на сайте не подключён, выключен или у него нет ни одного разрешённого origin;
- правило таргетинга по страницам использует origin, которого нет в разрешённых origin виджета;
- выбранный сегмент больше не существует или не готов;
- версия контента отсутствует, не опубликована или в архиве;
- контент использует блоки, которые поп-ап на сайте не может показать;
- некорректно настроены форма или кнопки;
- веса вариантов A/B-теста нельзя распределить.
Проверка запускается при каждом сохранении поп-апа с включённым «Показывать посетителям». Заблокированная активация возвращается как 400 с полным отчётом, неподтверждённые предупреждения: как 409, пока не отмечена галочка подтверждения. Выключенный поп-ап можно сохранить, даже если что-то из перечисленного не исправлено.
Самое частое предупреждение сообщает, что вариант всё ещё использует старые блоки и его стоит перевести на опубликованный контент поп-апа до следующей крупной правки.
Уведомления в браузере
Виджет также умеет спрашивать у посетителя разрешение на браузерные уведомления, и Web Push настраивается на этом же экране. Для него нужен шаг, который нельзя сделать из одного кабинета: файл сервис-воркера должен отдаваться с вашего собственного домена. Настройка, ограничения содержимого и то, чего браузерный пуш пока не умеет, описаны на странице «Пуш в браузере».
Доступные настройки
Готовые пресеты есть для онлайн-школы и интернет-магазина. Их можно изменить под свой сайт; отдельного универсального пресета нет. Быстрые действия отправляют текст и запускают выбранную реакцию. Посетитель может прикреплять файлы и изображения, если вложения включены в настройках поля ввода на вкладке «Диалоги». Форма перед началом чата предлагает заданный набор полей; добавлять в неё произвольные поля пока нельзя.
Устранение неполадок
- Убедитесь, что фрагмент есть ровно один раз, в правильном порядке и с непустым ключом.
- Проверьте, что origin страницы точно совпадает с сохранённым разрешённым origin.
- Запустите автоматическую диагностику и различайте статические признаки и подтверждение в реальном браузере.
- Проверьте сообщения CSP в консоли браузера и повторите тест без блокировщиков контента.
- Если виджет открывается, но не даёт полезного ответа, настройте подходящие реакции.
- Если проблема остаётся, обратитесь в поддержку, приложив результат диагностики.
Правила трекинга
Создайте правило в разделе Трекинг, чтобы превратить просмотр страницы, клик, видимость элемента или взаимодействие с формой в именованное событие. Задайте стабильное имя события, выберите триггер и при необходимости ограничьте страницы. Для элементов нужен CSS-селектор, например #checkout-button; для просмотра страницы он не требуется.
Извлечения добавляют свойства события из URL, атрибута или свойства элемента, параметра запроса, поля формы или константы. Проверьте правило через инспектор и отладчик событий перед включением. Не собирайте пароли, токены и другие секреты в свойствах события.
Поп-ап со своим JavaScript
Тип Свой скрипт выполняет ваш JavaScript вместо стандартной карточки поп-апа. Настройки стандартных блоков, форм и внешнего вида к нему не применяются. Таргетинг и частота по-прежнему определяют момент запуска.
Скрипт сам создаёт и убирает свой интерфейс. Используйте mybotPopup.track('converted') для конверсии и mybotPopup.close() при завершении; удаляйте собственные DOM-элементы при закрытии. Проверьте скрипт на своём сайте перед включением для посетителей.
Чтобы учитывать видимые показы в отчёте, после добавления поп-апа на страницу вызовите mybotPopup.observe(element), передав DOM-элемент с содержимым поп-апа. Событие записывается, когда не менее половины элемента находится в области экрана две секунды подряд во видимой вкладке. Это не подтверждает прочтение. Исторические показы не пересчитываются.
Выигранные сделки после показа
Отчёт по поп-апу показывает суммы первых зарегистрированных выигранных сделок CRM за выбранный период, раздельно по валютам. Сделка учитывается, если связанному с ней известному человеку показали этот поп-ап не более чем за 30 дней до выигрыша. Повторные события одной сделки не суммируются. Для учёта CRM должна передавать связь сделки с человеком и её сумму с валютой. Разбивка по дням показывает число сделок и сумму отдельно для каждой валюты; день определяется по времени первого выигрыша в UTC.
Это показатель связи с показом, а не подтверждение оплаты или причинного
влияния поп-апа. Одна сделка может войти в отчёты нескольких поп-апов.
Исторические CRM-события без идентификатора подключения не включаются;
если старая сделка не позволяет однозначно определить подключение, её
последующие обновления также не учитываются, чтобы не завысить сумму. Для
просмотра сумм нужно право analytics.revenue, а для PAT дополнительно
нужен scope analytics:read.
Подтверждённые оплаты после показа
Отдельно отчёт показывает подтверждённые оплаты за выбранный период, если платёж связан с известным посетителем, которому этот поп-ап показали не более чем за 30 дней до оплаты. Учитываются только оплаты, принятые через MyBot, от посетителей, однозначно связанных на сайте, в Telegram, VK или WhatsApp. Анонимные оплаты и оплаты без такой связи не попадут в этот показатель.
Оплаты, проведённые на сайте или во внешней платёжной системе без MyBot, не учитываются, даже если посетитель известен. Выигранные CRM-сделки показаны в отдельном разделе и подтверждённой оплатой не считаются.
Динамика группируется по дню оплаты в UTC и валюте: для каждого дня доступны число оплат, исходная сумма, текущая сумма возвратов и сумма после их вычета. Возврат относится к дню исходной оплаты, а не к дню возврата, поэтому данные за прошлый день могут измениться. Валюты и показатели сделок и оплат не складываются в одну сумму: одна покупка может присутствовать в обоих отчётах.
Финансовые данные доступны при наличии права analytics.revenue; для PAT
дополнительно нужен scope analytics:read. Связь оплаты с показом не
доказывает, что именно поп-ап привёл к покупке. Видимый показ также не
подтверждает прочтение.