#Встраивание виджета чата

Статус: Доступно (текущие параметры и блоки 1–5). Планируется — параметры виджета v2, блок 6 «Встроенный блок на странице» и блок 7 «Своя кнопка „Задать вопрос“» в их целевом виде. Статус отмечен у каждого параметра и блока.

Назначение: подключить к сайту окно чата с ИИ-продажником — одной строкой <script> либо через загрузчик модуля — и настроить внешний вид и поведение.

#Содержание

1. Когда использовать
2. Доступ и требования
3. Способы подключения
4. Параметры: текущие (Доступно)
5. Параметры v2 (Планируется)
6. Настройки канала в кабинете
7. Домен сайта и заголовки кадра
8. Как выглядит виджет
9. Готовые блоки
10. Ошибки и диагностика
11. Известные ограничения
12. Заметки
13. Открытые вопросы

#Когда использовать

• Нужен чат на вашем сайте без разработки интерфейса.
• Вы хотите менять цвет, приветствие и позицию из кабинета, не трогая код страницы.
• Для своего дизайна чата используйте клиентский Chat API, для чата в своём мессенджере — серверный API.

#Доступ и требования

Скрипт и кадр отдаёт та ячейка, где заведён канал. Идентификатор канала одной ячейки не работает на другой.

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

Порядок источников для каждого параметра: data-атрибут тега → ключ window.SapportWidget → значение по умолчанию.

#Параметры: текущие (Доступно)

#Атрибуты тега и ключи window.SapportWidget

Ключи без data-атрибута:

window.SapportWidget должен быть задан до тега widget.js. Если вы меняете consent позже, меняйте свойство того же объекта, а не подменяйте объект целиком.

#Что передаётся кадру

При первом открытии окна виджет создаёт iframe с адресом https://<ячейка>/widget/<channel_id> и параметрами.

Языка в адресе кадра widget.js не ставит: язык кадра берётся из настройки канала locale, а если её нет — из языка браузера посетителя (поддерживаются ru, en, ms, id; по умолчанию en).

#Что делает виджет

• Загружает настройки канала запросом POST /api/widget/init (этот маршрут единственный открыт для запросов с чужих сайтов).
• Рисует круглую кнопку 60×60 px. Окно (iframe) создаётся только при первом нажатии на кнопку: до этого адрес страницы на платформу не уходит.
• Окно — 380×560 px над кнопкой; на экранах шириной до 440 px занимает почти весь экран (ширина 100vw − 24 px, высота 100dvh − 100 px).
• z-index контейнера — 2147483647. Менять его параметрами нельзя.
• Счётчик непрочитанных на кнопке: пока окно закрыто, каждое новое сообщение увеличивает число (9+ при более чем девяти).
• Внутренние CSS-классы sapport-* — не контракт, они могут измениться.

#Параметры v2 (Планируется)

Статус: Планируется. Параметры ниже не работают в текущей версии widget.js: неизвестные атрибуты игнорируются. Не используйте их в боевой разметке до публикации в журнале изменений.

Значения по умолчанию, помеченные «предположительно», проект не фиксирует; окончательные значения будут в справочнике при выпуске.

#Настройки канала в кабинете

Часть внешнего вида меняется без правки кода страницы: настройки хранятся в канале и подгружаются запросом init.

Позиция, тема, текст пузырька и задержка попадают в виджет только как атрибуты скопированного из кабинета кода. Если подключить виджет через загрузчик (Bitrix/WordPress), эти четыре значения не применяются: загрузчик передаёт только идентификатор канала, адрес и признаки согласия.

Ключи канала, которые читает сервер, но для которых в кабинете нет полей: locale (язык кадра), pre_chat_form (форма перед чатом), ai_daily_limit (суточный предел ответов ИИ). Они задаются записью канала; интерфейса для них сегодня нет.

Код для встраивания в кабинете собирается подстановкой строк: кавычки в тексте пузырька не экранируются. Не используйте символ " в тексте пузырька.

#Домен сайта и заголовки кадра

Окно чата — это страница на домене ячейки, встроенная в ваш сайт. Браузер покажет её, только если ваш сайт разрешён заголовком Content-Security-Policy: frame-ancestors.

Разрешены:

• сама ячейка;
• домены арендатора (список domains арендатора);
• домены сайтов, привязанных к арендатору через коннектор (с https:// и https://www.);
• на EN дополнительно статический партнёрский список.

Условия: канал активен; арендатор активен и ему доступен модуль «Продвижение». Ответ кэшируется на 60 секунд. Если база недоступна, заголовок строится только по 'self'.

Запрос init не проверяет домен: кнопка может показаться даже там, где окно будет заблокировано.

#Как выглядит виджет

Макеты схематичны; точные отступы и цвета определяет тема.

#Кнопка

 Закрыта:                         Есть непрочитанные:             Открыта:

        Нужна помощь?                                                 ┌────┐
       ┌─────────────┐                                                │ ✕  │
       └─────────▽───┘                          ┌─┐                   └────┘
            ╭────────╮                        ╭─┤3├────╮
            │  ◯◯    │  60×60 px              │ └─┘ ◯◯  │            крестик вместо значка
            ╰────────╯                        ╰────────╯
   подпись над кнопкой —              красный счётчик в углу,
   data-bubble-text                   «9+» при больше девяти

#Окно на десктопе, 380×560

                                   ┌────────────────────────────────┐
                                   │ ◯  Название канала          ✕  │  шапка: аватар,
                                   │    ● отвечаем мгновенно        │  название, закрыть
                                   ├────────────────────────────────┤
                                   │ ┌───────────────────────┐      │
                                   │ │ Здравствуйте! Чем     │      │  приветствие
                                   │ │ можем помочь?         │      │  (из настроек канала)
                                   │ └───────────────────────┘      │
                                   │                  ┌───────────┐ │
                                   │                  │ Сколько   │ │  реплика посетителя
                                   │                  │ стоит?    │ │
                                   │                  └───────────┘ │
                                   │ ◌ ● ● ●                        │  индикатор набора
                                   ├────────────────────────────────┤
                                   │ [ Напишите сообщение…   ] [+] > │  ввод, вложение
                                   ├────────────────────────────────┤
                                   │        Powered by Formula AI   │  подпись в кадре
                                   └────────────────────────────────┘
                                        ╭────────╮
                                        │   ✕    │  кнопка 60×60 в углу, отступ 20 px
                                        ╰────────╯

#Окно на телефоне, ширина ≤ 440 px

 ┌─────────────────────────────┐
 │ ◯ Название канала        ✕  │   ширина: 100vw − 24 px
 │   ● отвечаем мгновенно      │   высота: 100dvh − 100 px
 ├─────────────────────────────┤   отступ от нижнего края 84 px,
 │ ┌─────────────────┐         │   по бокам 12 px
 │ │ Здравствуйте!   │         │
 │ └─────────────────┘         │
 │              ┌────────────┐ │
 │              │ Привет     │ │
 │              └────────────┘ │
 ├─────────────────────────────┤
 │ [ Напишите сообщение… ] [+]> │
 ├─────────────────────────────┤
 │    Powered by Formula AI    │
 └─────────────────────────────┘
          ╭────────╮
          │   ✕    │
          ╰────────╯

#Форма перед чатом

Показывается, если у канала включена pre_chat_form и у посетителя ещё нет сессии. Поля: name, email, phone; обязательные задаёт required.

 ┌────────────────────────────────┐
 │ ◯  Название канала          ✕  │
 ├────────────────────────────────┤
 │             (◯◯)               │
 │        Начните разговор        │
 │ Заполните данные ниже, чтобы   │
 │ начать.                        │
 │                                │
 │ Имя *                          │
 │ [____________________________] │
 │ Email *                        │
 │ [____________________________] │
 │ Телефон                        │
 │ [____________________________] │
 │                                │
 │ [        Начать чат          ] │
 └────────────────────────────────┘

Сервер использует из формы только имя (sender_name). Email и телефон отправляются, но не читаются — известное ограничение.

#Плашка согласия

Показывается над полем ввода, если арендатор задал consent_text. Пока флажок не отмечен, сообщение не отправляется.

 ├────────────────────────────────┤
 │ ☐ Я согласен с условиями       │
 │   оферты. Открыть оферту       │   ссылка из consent_url
 │   Отметьте согласие, чтобы     │   (если задана)
 │   написать.                    │
 ├────────────────────────────────┤
 │ [ Напишите сообщение…   ] [+] > │

#Индикатор набора

 │ ◌ ● ● ●                        │   пока ИИ готовит ответ (пузырь с тремя точками)
 │ ◯ ● ● ●  Анна печатает…        │   оператор печатает: аватар и имя

#Оператор с аватаром

После подключения оператора в шапке показывается его имя, а под шапкой — полоса «Вы на связи с …».

 ┌────────────────────────────────┐
 │ ◯  Анна                     ✕  │   вместо названия канала — имя оператора
 │    ● в сети                    │
 ├────────────────────────────────┤
 │ (◯) Вы на связи с Анна         │   полоса с аватаром 24 px
 ├────────────────────────────────┤
 │  Анна                          │   подпись над репликой оператора
 │ (◯) ┌──────────────────────┐   │   аватар 26 px рядом с пузырём
 │     │ Конечно, расскажу.   │   │
 │     └──────────────────────┘   │

#Готовые блоки

Во всех блоках замените 00000000-0000-4000-8000-000000000000 на идентификатор своего канала, а formula-cream.pro — на домен своей ячейки (wfacademy.org для EN, wfacademy.id для ID). Файлы для копирования лежат в examples/.

#Блок 1. Плавающая кнопка

Статус: Доступно. Файл: examples/floating-button.html.

Стандартное подключение: круглая кнопка в правом нижнем углу.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  async></script>

Макет — кнопка и окно.

Если тег загружается синхронно (без async), виджет стартует после DOMContentLoaded; с async — сразу после загрузки скрипта.

#Блок 2. Кнопка слева с подписью

Статус: Доступно.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-position="bottom-left"
  data-theme="dark"
  data-bubble-text="Нужна помощь?"
  async></script>

 ┌───────────────────────────────────────────┐
 │  страница                                 │
 │                                           │
 │                                           │
 │  Нужна помощь?                            │
 │ ┌──────────────┐                          │
 │ └──▽───────────┘                          │
 │ ╭────────╮                                │
 │ │  ◯◯    │                                │
 │ ╰────────╯                                │
 └───────────────────────────────────────────┘

Эквивалент через глобальный объект:

<script>
  window.SapportWidget = {
    channelId: '00000000-0000-4000-8000-000000000000',
    position: 'bottom-left',
    theme: 'dark',
    bubbleText: 'Нужна помощь?'
  };
</script>
<script src="https://formula-cream.pro/widget.js" async></script>

#Блок 3. Отложенный запуск

Статус: Доступно.

Кнопка появляется через заданное число секунд. До этого скрипт ничего не рисует и не обращается к платформе.

<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-bubble-text="Есть вопросы по курсу?"
  data-delay="15"
  async></script>

Через 15 секунд после загрузки скрипта виджет запрашивает настройки канала и рисует кнопку. Окно не открывается само: автоматическое открытие появится в v2 (data-open="after:N", Планируется).

#Блок 4. Контекст страницы товара или курса

Статус: Доступно. Файл: examples/product-page-context.html.

Виджет сам передаёт адрес и заголовок страницы. Тип и идентификатор сущности (курс, товар, статья) задайте объектом window.sapportPage до первого открытия чата. Чтобы значение точно было готово, ставьте его до тега виджета.

<script>
  window.sapportPage = { type: 'course', id: 'hydrolat-basics' };
</script>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  async></script>

Что получает модель (в промпте, как данные браузера, не как инструкции):

Текущая страница посетителя: https://shop.example.com/courses/hydrolat-basics · "[course #hydrolat-basics] Основы гидролатов"

Контекст читается один раз при первом открытии окна. Переход на другую страницу без перезагрузки (SPA) контекст не обновляет — для этого предназначен Sapport.setPage() из JS API (Планируется). Подробности — Страница, источник и UTM.

Модули Bitrix и WordPress выводят window.sapportPage сами.

#Блок 5. Согласие на cookie через загрузчик

Статус: Доступно. Файл: examples/consent-banner.html.

Подходит сайту, привязанному к Sapport: загрузчик подключает чат, счётчик и сбор поведения и сам ждёт согласия посетителя. Канал чата задаётся настройками сайта (chat, chat_channel_id), поэтому в теге нет data-channel.

<!-- 1. Заглушка очереди согласия: ДО загрузчика -->
<script>
  window.sapport = window.sapport || {
    q: [],
    consent: function (v) { this.q.push(['consent', !!v]); }
  };
</script>

<!-- 2. Загрузчик ячейки. k — публичный ключ сайта (не секрет) -->
<script async src="https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef"></script>

<!-- 3. Ваш баннер cookie вызывает consent -->
<script>
  document.getElementById('cookie-accept').addEventListener('click', function () {
    window.sapport.consent(true);
  });
  document.getElementById('cookie-decline').addEventListener('click', function () {
    window.sapport.consent(false);
  });
</script>

 ┌─────────────────────────────────────────────────────┐
 │ Мы используем cookie, чтобы понимать, откуда        │
 │ приходят посетители, и подсказывать в чате.         │
 │                                                     │
 │            [ Принять ]    [ Отклонить ]             │
 └─────────────────────────────────────────────────────┘

Событием: window.dispatchEvent(new CustomEvent('sapport:consent', { detail: true })); допустима и форма { granted: true }. consent(false) возвращает режим минимального контекста.

Согласие в чате — отдельное: это не cookie-баннер, а согласие с офертой арендатора (плашка).

Ручная установка без загрузчика, но с тем же поведением:

<script>
  window.SapportWidget = {
    channelId: '00000000-0000-4000-8000-000000000000',
    consent: false,
    firstTouch: false
  };
  // после согласия посетителя — на том же объекте:
  function onCookieAccepted() {
    window.SapportWidget.consent = true;
    window.SapportWidget.firstTouch = true;
  }
</script>
<script src="https://formula-cream.pro/widget.js" async></script>

Модуль для Bitrix/WordPress ставит этот загрузчик сам; вручную тег добавлять не нужно.

#Блок 6. Встроенный блок на странице

Статус: Планируется (data-mode="inline", data-container). Временного поддерживаемого способа нет; ниже — обходной путь, который работает по коду, но не является контрактом.

Целевая разметка v2 (не работает сегодня):

<div id="sapport-chat" style="height:560px"></div>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-mode="inline"
  data-container="#sapport-chat"
  async></script>

 ┌───────────────────────────────────────────────────────────┐
 │ Вопросы по курсу?                                         │
 │ ┌───────────────────────────────────────────────────────┐ │
 │ │ ◯ Название канала                                  ✕  │ │
 │ │ ┌───────────────────────┐                             │ │
 │ │ │ Здравствуйте!         │   окно чата внутри          │ │
 │ │ └───────────────────────┘   текста страницы           │ │
 │ │ [ Напишите сообщение…                       ] [+] >   │ │
 │ └───────────────────────────────────────────────────────┘ │
 └───────────────────────────────────────────────────────────┘

Обходной путь сегодня. Страница чата открывается как обычный iframe:

<iframe
  title="Чат"
  src="https://formula-cream.pro/widget/00000000-0000-4000-8000-000000000000?theme=light"
  style="width:100%;max-width:380px;height:560px;border:0"
  allow="clipboard-write"></iframe>

Ограничения обходного пути:

• домен вашего сайта должен быть разрешён заголовком frame-ancestors (выше);
• адрес страницы, заголовок, sapportPage и первое касание кадр не получает: их собирает только widget.js. Если нужен контекст, добавьте их в адрес вручную: &page=<адрес>&title=<заголовок> (значения в encodeURIComponent), так же работают pt, pid, ref;
• внутри кадра остаётся кнопка «Закрыть» (✕). Она отправляет родителю сообщение sapport:close, которое без widget.js никто не обрабатывает;
• кадр сам не растягивается шире 380 px и по высоте не больше 560 px, центрируется;
• обходной путь не описан как публичный контракт, его поведение может измениться.

#Блок 7. Своя кнопка «Задать вопрос»

Статус: Планируется (data-launcher="none" и Sapport.open()). Поддерживаемого способа открыть окно из своего кода сегодня нет.

Целевая разметка v2 (не работает сегодня):

<button id="ask">Задать вопрос</button>
<script
  src="https://formula-cream.pro/widget.js"
  data-channel="00000000-0000-4000-8000-000000000000"
  data-launcher="none"
  async></script>
<script>
  document.getElementById('ask').addEventListener('click', function () {
    window.Sapport.open();
  });
</script>

 ┌───────────────────────────────────────────────┐
 │ Курс «Основы гидролатов»                      │
 │ [ Записаться ]   [ Задать вопрос ]            │   ваша кнопка
 │                        │                      │
 │                        ▼                      │
 │              ┌────────────────────┐           │
 │              │ окно чата 380×560  │           │
 │              └────────────────────┘           │
 └───────────────────────────────────────────────┘

Что можно сегодня.

1. Использовать стандартную плавающую кнопку (блоки 1–3) и подписать её data-bubble-text="Задать вопрос".
2. Для ссылки «Задать вопрос» открыть страницу чата в своём окне или во всплывающем iframe (обходной путь блока 6).
3. Нажимать стандартную кнопку программно (document.querySelector('.sapport-bubble').click()) — не рекомендуется: имена внутренних классов sapport-* не являются контрактом и могут измениться без предупреждения.

#Ошибки и диагностика

В «Сети» браузера ищите запросы widget.js, /api/widget/init и после открытия — /widget/<channel_id>.

#Известные ограничения

Эти пункты отражают расхождения между ожиданием и поведением; формулировки нейтральны, источник — код на 11.10.2026.

Нумерация соответствует перечню расхождений проекта.

#Заметки

• Размеры: кнопка 60×60 px; окно 380×560 px; на ширине ≤ 440 px — окно почти на весь экран.
• Политика реферера. Сообщения кадра (sapport:new-message, sapport:close) идут на origin страницы. Origin кадр определяет по ancestorOrigins (Chrome, Safari) или по document.referrer (Firefox). Если ваш сайт отправляет Referrer-Policy: no-referrer, счётчик непрочитанных на кнопке работать не будет, а сам чат продолжит работу.
• Скрытие на страницах. Загружайте тег только на нужных страницах (например, не на странице оформления заказа): параметра «не показывать здесь» нет.
• Кэш. Скрипт widget.js и ответ init не версионируются адресом; обновления подхватываются по обычным правилам кэширования браузера.
• Подпись в окне. В нижней части окна показывается подпись «Powered by Formula AI»; параметра, отключающего её, в коде нет.
• Журнал изменений: 90-changelog.

#Открытые вопросы

• Где в кабинете арендатор управляет списком domains, который определяет разрешённые домены для кадра: в интерфейсе подтвердить не удалось. Для привязанных сайтов домен добавляется автоматически.
• Где в интерфейсе берётся публичный ключ сайта k для ручной установки загрузчика (он выдаётся при привязке и в кабинете не показывается).
• Значения по умолчанию data-open, data-locale в v2 и нужны ли перечисленные параметры в первой версии — не зафиксировано.
• Нужен ли параметр для отключения подписи «Powered by Formula AI» (в проекте не описан).