Как добавить

Добавьте голосового агента на любой сайт через диалог настройки виджета в настройках агента. Шаг 1: Откройте настройки агента, нажав иконку шестеренки в правом верхнем углу редактора агента. Шаг 2: Прокрутите до раздела Добавление на сайт и нажмите Настроить виджет. Шаг 3: Включите встраивание, добавьте домен вашего сайта в Разрешенные домены, выберите Плавающий виджет, Встроенный компонент или Headless (свой интерфейс), при необходимости настройте кнопку (позицию, цвет, текст) и нажмите Сохранить конфигурации. Шаг 4: Скопируйте сгенерированный код встраивания и вставьте его на страницу сайта, чтобы протестировать агента.

Режимы встраивания

Требования

Они относятся ко всем трем режимам:
  • Отдавайте страницу по HTTPS. Браузеры запрещают доступ к микрофону на обычных HTTP-страницах и file://.
  • Если вы задали Разрешенные домены в панели управления, добавьте домен сайта; иначе конфигурация виджета и сигнальные запросы будут отклонены. Оставьте список пустым, чтобы разрешить все домены.
  • Embed-сниппет из панели управления — это один тег <script>, который загружает agentika-widget.js асинхронно. Виджет инициализируется автоматически после загрузки и предоставляет window.AgentikaWidget. Код, который регистрирует колбэки, должен дождаться доступности виджета.
Старые имена по-прежнему работают. Страницы, встроенные до переименования, продолжают работать без изменений: /embed/agentika-widget.js загружает актуальный виджет, window.AgentikaWidget — алиас window.AgentikaWidget, а <div id="agentika-inline-container"> по-прежнему подхватывается в режиме встроенного компонента. Для новых встраиваний используйте актуальные имена.

Плавающий виджет

Рендерит кнопку-«таблетку» (иконка микрофона + текст), закрепленную в углу страницы. Клик запускает звонок, повторный клик завершает его. Кнопка автоматически обновляет подпись и цвет по ходу жизненного цикла звонка: заданный текст → «Connecting…» → «End Call» → «Retry» при ошибке. Настройте текст кнопки, цвет кнопки и позицию (верх/низ + лево/право) в панели управления. Хост-страница не требует написания JavaScript: вся интеграция — это вставка embed-сниппета. Если нужно подписаться на события жизненного цикла, например для аналитики, см. Колбэки жизненного цикла ниже.

Встроенный компонент

Рендерит панель (иконка статуса + текст статуса + кнопка действия) внутри <div>, который вы размещаете на странице. Смены статуса обновляют панель на месте. Настройте текст кнопки, цвет кнопки и текст призыва к действию в панели управления.

Обычный HTML

Поместите контейнер <div> туда, где должен рендериться виджет. Виджет автоматически привяжется к нему.

React

Поскольку React монтируется после того, как скрипт виджета уже мог загрузиться, интегрируйте через initInline при первом монтировании и refresh при повторном монтировании. Опрос window.AgentikaWidget нужен, чтобы обработать асинхронную загрузку скрипта.

Режим Headless

В режиме Headless виджет не добавляет свой интерфейс. Вы рендерите любые кнопки, баннеры или индикаторы состояния звонка и вызываете JavaScript API для запуска и завершения звонков.

JavaScript API

Все сеттеры on* принимают одного слушателя: повторный вызов того же сеттера заменяет предыдущий обработчик.
О тайминге. Скрипт виджета загружается асинхронно, поэтому window.AgentikaWidget может еще не существовать, когда ваш встроенный <script> впервые выполняется. Примеры ниже предполагают, что window.AgentikaWidget уже доступен при регистрации. Чтобы гарантировать это:
  • Vanilla JS: оберните код регистрации в window.addEventListener('load', () => { /* register here */ }).
  • React: внутри useEffect регистрируйтесь сразу, если document.readyState === 'complete'; иначе добавьте одноразовый слушатель window.load, который выполнит регистрацию.
  • Обработчики кликов, вызывающие start() / end(), не требуют проверок: к моменту клика виджет, как правило, уже загружен.

Vanilla JS

React + TypeScript

start() должен запускаться внутри реального обработчика жеста пользователя (click, touchend и т. д.). Браузеры не дают доступ к микрофону скриптам, которые запрашивают его вне такого обработчика: вызов start() из setTimeout или при загрузке страницы завершится ошибкой разрешений.

Колбэки жизненного цикла (все режимы)

Колбэки on* из JavaScript API режима Headless работают во всех трех режимах встраивания, а не только в Headless. Используйте их для аналитики или управления интерфейсом на хост-странице, даже когда виджет рендерит собственный UI (плавающий или встроенный).
onCallConnected и onCallDisconnected срабатывают только когда звонок действительно установил медиасоединение. Неудачные попытки подключения — например, отказ в доступе к микрофону или сбой сети — их не вызывают, поэтому аналитика остается чистой.