SupportHubSupportHub/ docs
Назад
Установка
Виджет / Установка

Установка виджета на сайт

Один тег с ID проекта в адресе — и чат на любой странице. Ниже — необязательные data-атрибуты и JS-API для идентификации и управления.

Установка за 4 шага

  1. 1
    Возьмите код
    В дашборде откройте НастройкиКонструктор виджета — кнопка «Код для вставки» внизу левой панели открывает готовый код с ID вашего проекта. Тот же код есть в НастройкиКаналы, в карточке Web Widget. ID проекта — это UUID в параметре ?ws=.
  2. 2
    Вставьте код перед </body>
    На каждой странице, где должен быть чат:
    index.htmlhtml
    <script>
(function(w, d){
  function loadWidget(token){
    var s = d.createElement('script');
    s.async = 1;
    s.src = 'https://supporthub.cc/widget-bundle?ws=00000000-0000-0000-0000-000000000000';
    if (token) s.setAttribute('data-visitor-token', token);
    d.head.appendChild(s);
  }
  // ── Optional: cross-device HMAC visitor token ─────────────────
  // Uncomment + implement /api/supporthub/token on your backend to
  // bind the same visitor across devices. Recipes per stack:
  //   https://supporthub.cc/docs/widget/hmac-examples
  //
  // fetch('/api/supporthub/token', { credentials: 'include' })
  //   .then(function(r){ return r.ok ? r.json() : null; })
  //   .then(function(data){ loadWidget(data && data.token); })
  //   .catch(function(){ loadWidget(); });
  //
  // Default — anonymous (no token):
  loadWidget();
})(window, document);
</script>
    По умолчанию код подключает виджет в анонимном режиме — никакого бэкенда у вас не требуется. Если хотите узнавать посетителя на разных устройствах (iPhone и MacBook → один контакт) — раскомментируйте блок fetch('/api/supporthub/token') и реализуйте endpoint у себя по одному из шаблонов; код сам передаст токен в атрибут data-visitor-token. Скрипт добавляется через document.createElement('script') с async=1 и не блокирует отрисовку страницы. Обязательный параметр один — ?ws=; адрес API виджет знает сам. Полный референс HMAC — /docs/widget/hmac, идентификация целиком — /docs/widget/identify.
  3. 3
    Проверьте, что кнопка появилась
    Откройте сайт в режиме инкогнито. В правом нижнем углу должна появиться кнопка виджета — по умолчанию с иконкой чата и текстом. Если её нет или что-то не работает, посмотрите в консоль браузера. Частые причины:
    • Опечатка в ?ws= — кнопка всё равно появится, но с оформлением по умолчанию, и сообщения не будут доходить.
    • CSP сайта: нужны supporthub.cc в script-src, https://supporthub.cc и wss://supporthub.cc в connect-src, supporthub.cc и data: в img-src. Стили виджет добавляет тегом <style>, поэтому style-src должен разрешать inline-стили.
    • Блокировщик рекламы или расширение, которое режет сторонние скрипты.
  4. 4
    Откройте чат и отправьте тестовое сообщение
    Нажмите кнопку → откроется панель → нажмите «Задать вопрос» → отправьте «привет». В дашборде во «Входящих» сразу появится новое обращение — значит, код подключён правильно.

Что делает тег

При загрузке /widget-bundle?ws=…:

  1. Читает ?ws= из адреса скрипта и необязательные data-*-атрибуты тега. Опубликованный конфиг и адрес API сервер обычно вставляет прямо в начало бандла, так что отдельного запроса за /config нет; если не вышло, виджет запросит конфиг сам.
  2. Применяет тему, цвета и свой CSS, добавляет на страницу кнопку и панель.
  3. Находит или создаёт ID посетителя — он хранится в пяти местах (cookie, localStorage, sessionStorage, IndexedDB и старый общий ключ); подробности — в справочнике для разработчиков.
  4. Если заданы data-email/name/phone/telegram-id, отправляет POST /api/webhooks/widget/{ws}/identify — контакт создаётся или обновляется сразу, ещё до первого сообщения.
  5. Когда у посетителя есть обращение, подключает WebSocket /api/ws/widget/{visitor_id}?workspace_id={ws} для ответов в реальном времени.

Параметры тега

?ws= (query)
Тип: uuidПо умолчанию: —
Обязательный. UUID проекта в адресе скрипта. Без него виджет сам не запустится — только через SupportHub.init().
data-api-base
Тип: stringПо умолчанию: —
Свой адрес API. Обычно не нужен и не срабатывает: сервер, который отдаёт бандл, сам прописывает адрес API в его начало, и тогда атрибут игнорируется. Нужен, только если бандл отдаётся без этого — например, из своей сборки без NEXT_PUBLIC_API_URL.
data-cookie-domain
Тип: stringПо умолчанию: —
Домен cookie с ID посетителя — чтобы у посетителя была одна переписка на всех поддоменах. auto — виджет сам находит основной домен сайта (для my.example.com — example.com); или свой домен с точкой в начале (.example.com). Без атрибута и настройки cookie живёт только на текущем хосте. Если cookie на общем домене уже поставил другой поддомен (лендинг), побеждает он — так обращение с лендинга продолжается в кабинете. То же самое задаётся в Конструктор виджетаРасширенныеCookie-домен; атрибут на теге важнее конфига.
data-locale
Тип: string (BCP-47)По умолчанию: —
Язык виджета — ru или en (теги вида en-GB тоже подходят, берутся первые две буквы). Полезно, если у сайта несколько языковых версий: на каждой ставите свой data-locale. Заданный так язык действует всегда. Без атрибута виджет берёт <html lang="…"> страницы, потом язык браузера — каждый, только если тексты проекта есть на этом языке, — а иначе основной язык проекта. Неподдерживаемые значения (fr, xx) пропускаются. Если в Конструктор виджетаБрендингЯзык виджета выбран «Всегда русский» или «Всегда английский», атрибут не действует (подробнее — на странице «Бренд и шапка»). Программный аналог — SupportHub.init({ locale: "en" }).
data-email
Тип: stringПо умолчанию: —
Email посетителя. Уходит в identify вместе с остальными data-*. Пошаговая pre-chat форма (стиль по умолчанию) уже известные поля не спрашивает.
data-name
Тип: stringПо умолчанию: —
Имя посетителя. Заменяет только временное имя вроде «Гость».
data-phone
Тип: stringПо умолчанию: —
Телефон (рекомендуется E.164). Записывается, если у контакта телефона ещё нет.
data-telegram-id
Тип: intПо умолчанию: —
Telegram ID посетителя. Записывается, если у контакта его ещё нет.
data-visitor-token
Тип: stringПо умолчанию: —
HMAC-токен посетителя, который выдаёт ваш бэкенд (см. /docs/widget/hmac). С ним обращения с разных устройств попадают в один контакт.
data-hide-launcher
Тип: booleanПо умолчанию: false
Значение "true" скрывает кнопку-лончер. Виджет тогда открывается только программно — вызовите window.SupportHub.open() со своей кнопки или ссылки. Действует при автозапуске по ?ws=; при ручной инициализации используйте SupportHub.init({ hideLauncher: true }).
data-require-auth
Тип: booleanПо умолчанию: false
Виджет только для вошедших посетителей. Пока ваш сайт не передал подписанный токен посетителя (data-visitor-token или SupportHub.identify({ visitor_token })), вместо чата, справки и новостей виджет пишет «Пройдите авторизацию». Токен пришёл — виджет открывается сам, SupportHub.logout() закрывает его снова. Подробнее — «Только для вошедших». При ручной инициализации — SupportHub.init({ requireAuth: true }).
data-auth-url
Тип: stringПо умолчанию: —
Адрес страницы входа на вашем сайте для кнопки «Войти» под надписью «Пройдите авторизацию» — полный адрес http(s) или путь на сайте. Без него — только надпись.
data-identify-url
Тип: stringПо умолчанию: —
Адрес на вашем сайте, который отдаёт токен вошедшего посетителя — JSON { token, exp, email?, name? } или { error }, код ответа не важен. Виджет запрашивает его с cookie посетителя и заголовком X-SupportHub-Widget: 1, передаёт токен в identify() и обновляет до истечения. Ответ no_session или not_a_client выводит посетителя, которого опознал этот адрес, как SupportHub.logout(). Полный адрес http(s) или путь на сайте; запрос с другого поддомена требует CORS на стороне адреса. Подробнее — «Опознание по адресу токена». При ручной инициализации — SupportHub.init({ identifyUrl: "…" }).
async
Тип: booleanПо умолчанию: false
Рекомендуется ставить. Бандл грузится параллельно остальной странице и не блокирует отрисовку.

Программное управление

Бандл создаёт window.SupportHub. Сразу после загрузки скрипта в нём есть только init() и identify() — вызовы identify до запуска виджета копятся и отправляются после него. Остальные методы (open, close, isOpen, setTab, applyConfig, showState, destroy) появляются, когда виджет запустится, поэтому вызывайте их с проверкой: window.SupportHub?.open?.().

js
// Кнопка «Связаться с поддержкой» где-то у вас на сайте:
document.getElementById("contact-support").addEventListener("click", () => {
  window.SupportHub?.open?.();
});

Автооткрытие

Сам по себе виджет открывается в двух случаях — оба настраиваются в НастройкиКонструктор виджетаПриветствие.

  • «Задержка авто-открытия» — через заданное число секунд (1–3600) после загрузки страницы, один раз за сессию и только если посетитель ещё не открывал виджет сам. Пусто или 0 — выключено.
  • «Сразу открывать чат в Telegram Mini App» — если сайт запущен как Mini App, панель открывается сразу, а кнопка прячется (закрывает Telegram). Выключите, если Mini App — это ваш сайт, а чат в нём вспомогательный: тогда виджет останется обычной кнопкой. Ссылки, открытые из чатов Telegram (встроенный браузер), — не Mini App: там виджет сам не открывается никогда.
  • «Где открывать само» — для задержки: везде, только в обычном браузере (не внутри приложений вроде Telegram или Instagram и не у сайта, установленного на экран) или только на компьютере. Поисковым роботам виджет сам не открывается.
  • «Что открыть» — экран, на котором виджет откроется сам (по задержке или в Mini App): вкладка, а для «Помощи» и «Новостей» — конкретный раздел, статья или новость. Вкладка, которую посетитель не видит, игнорируется — виджет откроется как обычно.

Удаление и обновление

Удалить виджет с сайта

Уберите <script>-тег. После следующего деплоя посетители не увидят кнопку. Открытые обращения в системе остаются — операторы продолжают их вести, но новые посетители без виджета обращаться не смогут.

Обновлять не нужно

Бандл обновляется сам: тег ссылается на тот же адрес, и новые версии посетители получают при следующей загрузке страницы. Браузер кеширует бандл на 5 минут (max-age=300) и ещё какое-то время может один раз показать старую копию, пока обновляет её в фоне (stale-while-revalidate), — так что обновления и опубликованные настройки доходят за несколько минут.

Была ли страница полезной?