Перейти к основному содержимому
DocumentationAPI ReferenceVideo Tutorials

Виджеты для сайта

Встраивайте голосового агента на любой сайт, чтобы посетители могли начать голосовой разговор прямо из браузера. Вкладка Widgets предоставляет embed-коды, опции кастомизации и настройки безопасности доменов.

Ищете callback-виджет?

Callback Widget работает совсем иначе, чем виджеты на этой странице — вместо старта голосового звонка в браузере он собирает номер посетителя, и агент сам перезванивает. См. отдельную страницу Callback Widget.

Типы виджетов​

Hanc.AI предлагает четыре типа браузерных виджетов плюс отдельный Callback Widget для телефонных callback:

ВиджетИмя тегаОписаниеЛучше всего для
Floating Widgethanc-ai-floating-callOrb-кнопка, плавающая над страницейВсегда видимый CTA
Pill Widgethanc-ai-pill-callКомпактная пилюлевидная кнопка, встроенная inlineМинимальный footprint в существующем макете
Pill Floating Widgethanc-ai-pill-float-callТа же компактная форма pill, но плавает со страницей как FloatingКогда нужна эстетика pill, следующая за посетителем при скролле
Inline Widgethanc-ai-inline-callПолноразмерная кнопка вызова, встроенная в контентВыделенные секции «Поговорить с нами»
Callback Widgethanc-ai-callbackФорма номера телефона; агент перезваниваетЛидген-страницы, high-intent лендинги — см. Callback Widget

Общие атрибуты​

Все типы виджетов поддерживают ключевые атрибуты:

АтрибутОбязательноОписаниеДефолт
agent-idДаУникальный идентификатор агента—
voice-service-urlНетПереопределить URL голосового сервисаАвтоопределение
api-base-urlНетПереопределить базовый URL APIАвтоопределение

Атрибуты отображения​

АтрибутОписаниеЗначенияДефолт
positionПозиция виджета на страницеbottom-right, bottom-left, top-right, top-left, staticbottom-right
sizeРазмер виджета в пикселяхЧисло120
themeИмя цветовой темыСм. Цветовые темыdefault

Атрибуты текста кнопки​

АтрибутОписаниеДефолт
button-start-textТекст на бездействующей кнопке"Call"
button-connecting-textТекст при соединении"Connecting..."
button-end-textТекст во время активного звонка—

Атрибуты Terms​

АтрибутОписаниеДефолт
terms-enabledВключить диалог согласия до звонкаfalse
terms-contentMarkdown-форматированный текст согласия""
terms-urlСсылка на страницу Terms & Conditions"https://hanc.ai/terms"
privacy-urlСсылка на страницу Privacy Policy"https://hanc.ai/privacy"
к сведению

Terms-атрибуты на HTML-элементе переопределяются настройками виджета агента из API, если только skip-fetch не выставлен в true.

Атрибуты звука​

АтрибутОписаниеДефолт
sound-enabledВключить звуки старта/окончания звонкаtrue
sound-volumeГромкость звуковых эффектов0.25
sound-presetИдентификатор пресета звука"1"

Цветовые темы​

Кастомизируйте внешний вид виджета — 11 встроенных цветовых тем:

ТемаЗначение
Defaultdefault
Purplepurple
Blueblue
Cyancyan
Emeraldemerald
Amberamber
Tangerinetangerine
Roserose
Emberember
Blackblack
Whitewhite

У каждой темы — тёмный и светлый варианты. Тема задаётся через атрибут theme в embed-коде или в настройках виджета агента.

Примеры встраивания​

Floating Widget​

<hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Floating Widget с темой и позицией​

<hanc-ai-floating-call
  agent-id="YOUR_AGENT_ID"
  theme="emerald"
  position="bottom-left"
  size="140"
></hanc-ai-floating-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Pill Widget​

<hanc-ai-pill-call agent-id="YOUR_AGENT_ID"></hanc-ai-pill-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>

Inline Widget​

<hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
<script src="https://unpkg.com/hanc-webrtc-widgets" async type="text/javascript"></script>
Закрепление версии виджета

URL скрипта выше всегда грузит последнюю выпущенную версию — сайт автоматически подхватывает улучшения. Если нужно закрепить известно-рабочую версию, явно укажите https://unpkg.com/hanc-webrtc-widgets@1.4.0 (подставьте нужную версию). Тег @latest — дефолт, когда версия не указана.

События виджета​

Виджеты генерируют события, которые можно слушать в JavaScript:

СобытиеОписание
status-changedПри смене статуса звонка
connectingЗвонок устанавливается
connectedЗвонок активен
idleНет активного звонка
errorПроизошла ошибка
audio-trackПолучен удалённый аудиотрек (для визуализации)
local-audio-trackЛокальный аудиотрек микрофона (для визуализации)
microphone-enabledМикрофон включён
microphone-disabledМикрофон выключен
call-startПри успешном старте звонка
call-endПри завершении звонка

Пример: слушать события​

const widget = document.querySelector('hanc-ai-floating-call');

widget.addEventListener('call-start', () => {
  console.log('Call started');
});

widget.addEventListener('call-end', () => {
  console.log('Call ended');
});

Технические требования​

Виджеты требуют, чтобы браузер посетителя поддерживал:

  • WebGL 2.0 — для отрисовки
  • Web Audio API — для обработки звука
  • WebRTC — для реал-тайм голосовой связи

Все современные браузеры (Chrome, Firefox, Safari, Edge) поддерживают эти технологии.

Ограничения доменов​

Контролируйте, какие сайты могут встраивать виджет агента.

Всегда разрешённые домены​

Эти домены всегда разрешены, независимо от конфигурации:

  • hanc.ai (и поддомены)
  • hanc.me (и поддомены)
  • localhost

Allow All Domains​

По умолчанию виджет можно встраивать на любой сайт. Переключите «Allow all domains» в настройках виджета, чтобы ограничить.

Ограничение конкретными доменами​

При ограничении добавьте каждый разрешённый домен:

  • Имена доменов без https:// (например, example.com)
  • Поддомены — отдельными записями (например, www.example.com, shop.example.com)
  • Порты можно указывать (например, localhost:3000)
  • Максимум 50 доменов в whitelist
Безопасность

Для продакшен-агентов ограничивайте виджеты своими доменами, чтобы предотвратить несанкционированное встраивание.

Terms & Conditions​

Включите диалог согласия до того, как звонящие смогут начать разговор.

Конфигурация​

НастройкаОписание
Enable TermsПереключатель диалога terms
Terms ContentMarkdown-форматированный текст согласия (макс. 5000 символов)
Terms URLСсылка на полную страницу Terms & Conditions
Privacy URLСсылка на страницу Privacy Policy

Когда включено:

  • Пользователи видят диалог согласия до старта звонка
  • Должны нажать «Agree» для продолжения
  • Согласие хранится локально в браузере
  • Кнопка Reset Consent очищает сохранённое согласие для тестов

Форматирование контента​

Контент terms поддерживает Markdown:

  • #### для заголовков
  • **bold** для акцента
  • Переводы строк для читаемости

Связанное​