Установка на сайт
Один тег script — и агент на странице.
Виджет подключается одним тегом <script>, который нужно вставить перед закрывающим тегом </body> на странице сайта.
Код вставки
<script src="https://cdn.cosai.pro/widget/v1/widget.js"
data-agent-id="<uuid агента>"
data-agent-key="<cosai_wk_…>"
data-title="Чат с консультантом"></script>Этот адрес обновляется автоматически в пределах крупной версии /widget/v1/: исправления и улучшения виджета приезжают к вам без правки кода на сайте. Если нужно зафиксировать конкретный релиз — см. Про SRI ниже.
Параметры
| Атрибут | Обязателен | Назначение |
|---|---|---|
data-agent-id | да | Идентификатор опубликованного агента |
data-agent-key | да | Ключ со scope chat:widget, ограниченный доверенными доменами (см. Домен-allowlist) |
data-title | нет | Заголовок панели чата (по умолчанию «Чат с консультантом») |
data-api | нет | Адрес API. По умолчанию используется адрес, вшитый в бандл виджета при сборке; задавать нужно только для нестандартных установок платформы |
Где взять agent-id и agent-key
Проще всего — не собирать тег вручную: в разделе Настройка → Ключи выберите тип «Виджет на сайт», укажите агента и домены, и консоль выдаст готовый тег <script> с подставленными data-agent-id и data-agent-key. Ключ показывается один раз (см. API-ключи).
Если нужно собрать тег самостоятельно: agent-id — идентификатор агента из GET /v1/agents (см. Примеры запросов), data-agent-key — виджет-ключ с ограниченным доступом, отдельный от ключа полного доступа.
Про SRI (integrity)
Атрибут integrity с SRI-хэшем (sha384-…) защищает от подмены содержимого файла виджета, если он будет скомпрометирован на CDN: браузер проверит, что загруженный файл совпадает с ожидаемым, и не выполнит его при несовпадении.
Хэш можно вешать только на адрес конкретного релиза — он неизменяемый:
<script src="https://cdn.cosai.pro/widget/v1/<релиз>/widget.js"
integrity="sha384-…" crossorigin="anonymous"
data-agent-id="<uuid агента>"
data-agent-key="<cosai_wk_…>"></script>Готовый тег с релизом и хэшем выдаёт консоль рядом с обычным кодом вставки (Настройка → Ключи, блок «Фиксированная версия с проверкой целостности»). Плата за фиксацию — обновления виджета к вам сами не приезжают: при выходе новой версии тег нужно заменить. На авто-обновляемый адрес /widget/v1/widget.js атрибут integrity ставить нельзя — после ближайшего обновления браузер перестанет исполнять файл, и чат на сайте пропадёт.
Проверка после установки
Откройте страницу сайта — в правом нижнем углу должна появиться кнопка чата. Нажмите на неё и задайте тестовый вопрос: ответ должен прийти по потоковому SSE так же, как в чат-превью в консоли. Если чат не открывается — проверьте консоль браузера на ошибки data-agent-id/data-agent-key и убедитесь, что текущий домен добавлен в allowlist ключа.