Урок 2. Бот на вашем сайте

Урок 1 закончился публичной ссылкой на чат. Ссылку надо кому-то отправить — а виджет ставит того же бота прямо на вашу страницу: кнопка в углу или блок внутри вёрстки.

Что получится в конце: одна строчка <script> в HTML вашего сайта. Посетитель видит кнопку чата, нажимает и разговаривает с тем же ботом, что и по ссылке из урока 1. Ничего переписывать в графе не нужно — это та же публикация и тот же токен.

Шаг 1. Убедитесь, что бот опубликован

Виджет не публикуется отдельно от сценария: он читает ту же опубликованную версию, что и публичный чат.

Шаг 2. Настройте внешний вид

Настройки виджета живут в том же канале и применяются при публикации — вместе с графом, одной кнопкой. Пока вы правите поля, канал в списке помечен как ждущий публикации, и кнопка «Опубликовать» становится активной.

Что задаётся: Акцент, Положение (слева или справа), Заголовок панели, Текст кнопки и Иконка кнопки, Открывать автоматически и Разрешённые домены (по одному на строку), а также приветствие виджета — своё, отдельное от приветствия ссылки на чат. После правки нажмите ту же кнопку публикации, что и в шаге 1 (Опубликовать версию 2 — номер версии свой).

Открывать автоматически по умолчанию выключено, и это осознанно: окно, которого посетитель не просил, портит впечатление от сайта, ради которого он пришёл. Если включить — рядом появляется Через сколько секунд открыть: 0 открывает панель вместе со страницей, любое другое число даёт посетителю это время побыть на странице. Открывается окно один раз; тот, кто уже нажимал кнопку сам, его не увидит.

Разрешить вложения — отдельный тумблер, тоже выключенный по умолчанию. Включите, если бот должен принимать фото, голосовые и документы: в панели появится скрепка, а файл можно будет просто перетащить в окно чата. Настройка общая со ссылкой на чат — это один разговор с двумя входами. Принимаются картинки, аудио, PDF (до 8 МБ) и текстовые файлы; они занимают место в вашем хранилище и участвуют в контексте следующих ходов. PDF доходит до модели, которая умеет читать документы; на остальных ход остановится с ошибкой.

Кнопка «Очистить историю» — тоже общий тумблер и тоже выключен по умолчанию: кнопка позволяет посетителю стереть переписку, а она нужна и вам — в «Диалогах» видно, о чём спрашивали.

Подпись «Работает на iterna.ai» в панели чата убирается настройкой white-label, а она доступна начиная с тарифа «Про».

Шаг 3. Скопируйте код для вставки

Внизу того же канала лежит блок Код для вставки с переключателем Пузырёк / Встроенный и кнопкой Копировать. Токен вашего сценария уже подставлен.

Пузырёк — плавающая кнопка в углу страницы:

<script src="https://app.example.com/widget/iterna-widget.js"
  data-token="<ваш публичный токен>" data-mode="bubble" async></script>

Встроенный — чат рисуется внутри вашего блока, кнопки нет:

<div id="iterna-chat"></div>
<script src="https://app.example.com/widget/iterna-widget.js"
  data-token="<ваш публичный токен>" data-mode="inline" data-target="#iterna-chat" async></script>

В разделе Настройки → Виджет лежит тот же тег, но с заглушкой <PUBLIC_TOKEN> вместо токена: это общая на всё пространство страница, а токен принадлежит конкретному сценарию. Там же — секрет подписи, он нужен только для авторизованных посетителей (см. «Встраиваемый виджет»).

Шаг 4. Вставьте тег на страницу

Поставьте скопированную строку перед закрывающим </body> вашего сайта. Больше ничего подключать не нужно: адрес API виджет берёт из адреса самого скрипта, а внешний вид — из настроек сценария, которые он запрашивает при загрузке.

Чат монтируется в изолированный Shadow DOM. Это значит, что стили вашего сайта не влияют на виджет, а стили виджета — на ваш сайт, даже если у вас агрессивный глобальный CSS.

Шаг 5. Проверьте на своей странице

Откройте страницу в обычном браузере — не в редакторе. Кнопка появляется в правом нижнем углу (или в левом, если так настроено), клик открывает панель, первое сообщение стартует сессию.

Атрибуты data-*

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

Ограничение по доменам

Поле Разрешённые домены (по одному на строку) — список источников, с которых виджету разрешено работать. Пусто означает «любой домен». Проверяется заголовок Origin браузера при старте сессии и при отправке сообщения; чужой домен получает в панели надпись «Этот чат не авторизован на данном домене».

Это мягкая защита: заголовок ставит браузер, и запрос не из браузера его не ставит вовсе. Реальным ограничителем остаётся сам токен — кто угодно, кто его увидел, может писать боту, а запуски тарифицируются владельцу пространства. Относитесь к токену как к публикации, а не как к секрету.

Где смотреть диалоги

Переписка посетителей не теряется: раздел Диалоги показывает список сессий выбранного сценария и всю переписку по каждой. Разбор — в «Клиентах». Технические подробности запуска (какая нода что вернула, сколько стоило) — в «Запусках».

Если не получилось

Что дальше