Виджет чата на сайте #
Виджет добавляет на сайт кнопку чата. Посетители общаются с вашим ИИ-агентом, а оператор может подключиться в рабочем пространстве. Диалоги, знания, передача оператору, вложения и аналитика те же, что и в других каналах; общую часть описывает архитектура каналов-мессенджеров.
Как добавить на сайт #
- В рабочем пространстве создайте сайт: выберите проект и опубликованного агента, перечислите страницы, которым разрешено показывать чат (разрешённые адреса).
- Скопируйте публичный ключ сайта (он выглядит как
sw_pub_...). - Вставьте код на каждую страницу, где нужен чат, перед закрывающим
</body>:
<script src="https://app.heysora.ai/widget/v1/loader.js" data-sora-key="PUBLIC_KEY" async></script>Тот же виджет можно запустить из JavaScript: SoraWidget.init({ key: 'PUBLIC_KEY' }). Пошаговые инструкции для администраторов и полная документация разработчика находятся в Справке (нужен вход).
Разрешённые адреса #
Сайт перечисляет адреса страниц, которым разрешено показывать его чат, например https://www.example.com: схема и имя, а также порт, если он не стандартный. Без подстановок, без путей и только https (сайт TEST может перечислить и локальные адреса для разработки с портом). Сравнение точное, поэтому www и поддомен это разные записи. Список обеспечивает браузер через политику frame-ancestors панели. Подробнее: разрешённые адреса.
Content-Security-Policy вашего сайта #
Если ваш сайт отправляет Content-Security-Policy, разрешите адрес приложения HeySora в script-src и frame-src. Настраивать CORS не нужно: ваша страница не отправляет запросов к HeySora, панель чата работает в собственной рамке. Подробнее: требования CSP.
JavaScript API #
| Вызов | Назначение |
|---|---|
SoraWidget.init({ key, locale, position, autoOpen }) | запустить виджет; возвращает true, если запуск начат |
SoraWidget.open(), close(), destroy() | открыть или закрыть панель, или убрать виджет |
SoraWidget.setUser(user) | передать имя, почту, телефон, ваш идентификатор пользователя и несколько атрибутов |
SoraWidget.setContext(context) | передать адрес страницы, заголовок, реферер, часовой пояс, класс устройства |
SoraWidget.on(event, handler), off(event, handler) | подписаться на ready, open, close, message, unread, conversationStarted, escalated, operatorJoined, conversationClosed, error |
setUser персонализирует профиль, но не подтверждает личность: значения приходят из браузера посетителя и могут быть подделаны, поэтому никогда не используйте их для доступа к аккаунту и для решений о деньгах и безопасности. Адреса страниц сохраняются без параметров запроса. Полное описание: JavaScript API.
Режимы работы, вложения и передача оператору #
Сайт работает в одном из трёх режимов: ИИ и оператор (отвечает агент, человек может подключиться), только оператор (каждый диалог сразу уходит в очередь) или только ИИ (без передачи; когда подтверждённого ответа нет, посетитель получает заданный вами резервный текст). Посетители могут прикреплять файлы допустимых типов до 10 МБ каждый. Кнопка «Позвать оператора» запускает обычную передачу, и посетитель видит статус: ожидание, специалист подключился, завершено. Подробнее: режимы, вложения и передача оператору.
Проверка до запуска #
Сайт со средой TEST принимает локальные адреса для разработки, помечает свои диалоги как тестовые и открывается в предпросмотре из рабочего пространства. Используйте его для стенда и не добавляйте локальные адреса к рабочим сайтам.
Безопасность вкратце #
- Публичный ключ не секрет; сам по себе он никогда не открывает чат.
- Токен диалога не передаётся вашей странице.
- Сообщения показываются только обычным текстом.
- Список адресов проверяет браузер; злоупотребления других клиентов ограничиваются лимитами частоты.
Читайте основы безопасности и безопасность виджета.
Версии и ограничения #
Виджет версионируется под /widget/v1; изменения внутри v1 только добавляют возможности. В первой версии нет подписанной идентификации хоста, продолжения между вкладками и устройствами, потоковых ответов, богатых карточек, быстрых ответов, Markdown, WebSocket и подстановочных адресов. Ограничитель частоты и сигналы длинного опроса работают внутри одного процесса приложения, а автоматические браузерные тесты покрывают только Chromium. См. версии.