💬 Виджет на сайте

Чат с ассистентом через embed.js: кнопка запуска и iframe, которые обращаются к вашему API Gonka SaaS.

✅ Доступно для: всех типов агентов. Ключ и настройки — в кабинете: Агенты → [агент] → Виджет.

Что нужно до вставки кода

Требование	Подробности
Агент опубликован	Агент создан в Gonka SaaS.
Ключ виджета	Вкладка Виджет → «Сгенерировать ключ» → префикс `gw_…`. Храните как секрет.
Хостинг embed.js	Статика пакета `widget/`: `embed.js`, `iframe.html`, ассеты — по HTTPS (CDN, поддомен, Render и т.п.).
Публичный API	Браузер посетителя должен достучаться до `GET /api/v1/widget/public-config/:agentId` и чат-эндпоинтов. В атрибуте `data-api-base` указывается origin API без слэша в конце.

Универсальный код вставки

Готовый фрагмент копируется из кабинета: Агент → Виджет → Код для вставки. Минимальный вид:

<script
  src="https://YOUR_WIDGET_HOST/embed.js"
  async
  id="gonka-widget-script"
  data-gonka-widget
  data-agent-id="YOUR_AGENT_UUID"
  data-widget-key="gw_YOUR_SECRET_KEY"
  data-api-base="https://YOUR_API_ORIGIN"
  data-theme="ocean"
  data-position="right"
></script>

Атрибуты

Атрибут	Обязательный	Назначение
src	Да	HTTPS URL к `embed.js`.
id / data-gonka-widget	Желательно	Помогают loader найти тег скрипта.
data-agent-id	Да	UUID агента (как в URL кабинета).
data-widget-key	Да	Ключ из кабинета после генерации.
data-api-base	Почти всегда*	Origin вашего API, например `https://api.example.com`. Если сайт и API на одном origin — можно опустить (редко).
data-theme	Нет	Тема iframe: ocean, sunset и др.
data-position	Нет	`right` или `left` — угол кнопки.

В сниппете кабинета URL скрипта берётся из NEXT_PUBLIC_WIDGET_SCRIPT_URL, origin API — из NEXT_PUBLIC_API_URL (см. деплой фронтенда).

Как это устроено

embed.js читает атрибуты тега <script>.
Запрашивается оформление: GET {apiBase}/api/v1/widget/public-config/{agentId}.
Встраивается iframe со страницей хоста виджета (iframe.html), база задаётся при сборке (VITE_IFRAME_BASE).
В iframe через postMessage передаются ключ, agentId, theme, apiBase.

Проверка после установки

Сайт открывается по HTTPS.
В Network вкладке embed.js отдаётся с кодом 200.
В консоли браузера: fetch('https://ВАШ_API/api/v1/widget/public-config/ВАШ_AGENT_ID').then(r=>r.json()) → success: true.
Виджет включён в настройках агента; ключ не отозван.
Сообщение из чата видно в Агенты → Диалоги.

Сайт на Tilda

Вставляется тот же блок <script>…</script>. Удобнее один раз на весь сайт.

Вариант A — на все страницы (рекомендуется)

Редактор Tilda → Настройки сайта → Дополнительно.
Поле HTML-код для вставки перед </body> (или аналог по локали Tilda).
Вставьте целиком тег <script …></script>.
Опубликуйте сайт — без публикации изменения не на проде.

Вариант B — только одна страница

Откройте страницу в редакторе.
Добавьте блок T123 «HTML-код» / Embed HTML внизу (например подвал).
Вставьте тот же скрипт. Опубликуйте.

Тема	Совет
HTTPS	Домен Tilda или свой домен с SSL; API и виджет тоже по HTTPS.
Дублирование	Не вставляйте скрипт и в настройки сайта, и в блок на той же странице — будет два виджета.
Cookies / согласия	Согласуйте с cookie-баннером и политикой ПДн; для юр. текста см. инструкцию по встраиванию виджета.

Если что-то не работает

Кнопки нет

404 на embed.js, неверный URL в src; блокировщик рекламы.

Кнопка есть, чат пустой / ошибка

Неверный data-api-base; CORS — API должен разрешать origin вашего сайта, не только кабинета SaaS.

Не тот агент

Опечатка в data-agent-id; staging vs production ключ.

Полная версия в репозитории: docs/04-resources/widget-embed.md

← Все интеграции Быстрый старт агента →