Віджети сайту

Вбудовуйте свого голосового агента на будь-який сайт, щоб відвідувачі могли розпочати голосову розмову прямо з браузера. Вкладка Widgets надає коди вбудовування, опції налаштування та параметри безпеки доменів.

Шукаєте віджет зворотного дзвінка?

Віджет зворотного дзвінка працює зовсім інакше, ніж віджети на цій сторінці — замість того, щоб почати голосовий дзвінок у браузері, він збирає номер телефону відвідувача, і ваш агент передзвонює йому. Див. окрему сторінку Віджет зворотного дзвінка.

Типи віджетів

Hanc.AI пропонує чотири типи віджетів у браузері плюс окремий Віджет зворотного дзвінка для телефонних зворотних дзвінків:

Віджет	Назва тегу	Опис	Найкраще для
Floating Widget	`hanc-ai-floating-call`	Кругла кнопка, яка плаває над вашою сторінкою	Завжди видимий заклик до дії
Pill Widget	`hanc-ai-pill-call`	Компактна кнопка у формі pill, розміщена inline у вашому контенті	Мінімальний слід усередині наявного макета
Pill Floating Widget	`hanc-ai-pill-floating-call`	Така ж компактна форма pill, як у Pill, але плаває разом зі сторінкою, як Floating-віджет	Коли хочете естетику pill, яка слідує за відвідувачем при прокручуванні
Inline Widget	`hanc-ai-inline-call`	Повнорозмірна кнопка дзвінка, вбудована в контент сторінки	Виділені секції «Talk to Us»
Callback Widget	`hanc-ai-callback`	Форма для номера телефону; агент передзвонює відвідувачу	Лід-генеруючі сторінки, лендінги з високим наміром — див. Віджет зворотного дзвінка

Спільні атрибути

Усі типи віджетів підтримують ці основні атрибути:

Атрибут	Обов'язковий	Опис	За замовчуванням
`agent-id`	Так	Унікальний ідентифікатор вашого агента	—
`voice-service-url`	Ні	Перевизначає URL голосового сервісу	Автовизначення
`api-base-url`	Ні	Перевизначає базовий URL API	Автовизначення

Атрибути відображення

Атрибут	Опис	Значення	За замовчуванням
`position`	Позиція віджета на сторінці	`bottom-right`, `bottom-left`, `top-right`, `top-left`, `static`	`bottom-right`
`size`	Розмір віджета в пікселях	Число	`120`
`theme`	Назва кольорової теми	Див. Кольорові теми	`default`

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

Атрибут	Опис	За замовчуванням
`button-start-text`	Текст, який показується на неактивній кнопці	`"Call"`
`button-connecting-text`	Текст, який показується під час підключення	`"Connecting..."`
`button-end-text`	Текст, який показується під час активного дзвінка	—

Атрибути умов

Атрибут	Опис	За замовчуванням
`terms-enabled`	Увімкнути діалог згоди перед дзвінком	`false`
`terms-content`	Markdown-форматований текст згоди	`""`
`terms-url`	Посилання на вашу сторінку Terms & Conditions	`"https://hanc.ai/terms"`
`privacy-url`	Посилання на вашу сторінку Privacy Policy	`"https://hanc.ai/privacy"`

інформація

Атрибути умов, установлені на HTML-елементі, перевизначаються налаштуваннями віджета агента, отриманими з API, якщо skip-fetch не встановлено в true.

Звукові атрибути

Атрибут	Опис	За замовчуванням
`sound-enabled`	Увімкнути звуки початку/завершення дзвінка	`true`
`sound-volume`	Гучність звукових ефектів	`0.25`
`sound-preset`	Ідентифікатор звукового пресета	`"1"`

Кольорові теми

Налаштовуйте зовнішній вигляд віджета 11 вбудованими кольоровими темами:

Тема	Значення
Default	`default`
Purple	`purple`
Blue	`blue`
Cyan	`cyan`
Emerald	`emerald`
Amber	`amber`
Tangerine	`tangerine`
Rose	`rose`
Ember	`ember`
Black	`black`
White	`white`

Кожна тема має варіанти dark і light. Установіть тему через атрибут theme у коді вбудовування або налаштуйте її в налаштуваннях віджета агента.

Приклади вбудовування

<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>

<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>

<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>

<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 скрипту вище завжди завантажує останню випущену версію віджета — ваш сайт автоматично отримує покращення, і @latest є значенням за замовчуванням, коли версію не вказано. Якщо вам треба зафіксуватися на конкретному релізі, явно закріпіть його, додавши потрібну версію, наприклад https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.

Події віджета

Віджети генерують події, які можна слухати в 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');
});

Під час дзвінка з браузера агент може попросити ваш сайт відкрити сторінку — «покажу вам тарифи» — і відвідувач бачить це, не перериваючи розмову.

Рішення лишається за вашою сторінкою. Агент надсилає запит, ваш код вирішує, що він означає. Відкрити адресу, перемкнути вкладку, прокрутити до розділу, розгорнути акордеон — усе це допустимі відповіді.

Потрібні три кроки, і жоден не працює окремо.

Крок 1 — Скажіть агентові, які сторінки існують

Агент не бачить мапи вашого сайту. Він просить лише той шлях, який ви йому дали, — перелічіть їх у промпті агента або в базі знань:

Сторінки нашого сайту:
/pricing — тарифи й ціни
/contact — форма звʼязку і телефон
/product/crm — CRM

Пропустите цей крок — агентові нема чого просити, тож він навіть не спробує.

Крок 2 — Обробіть запит на своїй сторінці

Додайте це один раз, будь-де після скрипта віджета. Подія спливає сторінкою, тож document — зручне місце:

<script>
document.addEventListener('agent-command', (event) => {
  const { type, payload } = event.detail;

  if (type === 'navigate') {
    // SPA: перехід без перезавантаження — дзвінок триває.
    router.push(payload.path);

    // Звичайний сайт: відкрити другу вкладку, ця (і дзвінок) лишиться живою.
    // window.open(payload.path, '_blank');

    event.preventDefault();   // ← саме це каже агентові «прийнято»
  }
});
</script>

Повне перезавантаження сторінки обриває дзвінок

Дзвінок живе в цій сторінці. window.location.href = … вивантажує документ, і розмова зникає разом із ним — відвідувача обриває на півслові. Якщо є роутер, переходьте без перезавантаження; інакше відкривайте сторінку в новій вкладці. Перепідключення немає: перезавантаження не переживає ніщо.

preventDefault() не є необовʼязковим

Це єдиний спосіб сказати «я обробив». Без нього агентові повідомлять, що сайт не підтримує навігацію: до кінця дзвінка він припинить спроби й повернеться до пояснень, куди натиснути. У консолі нічого не зʼявиться — сторінка просто має вигляд такої, що проігнорувала запит, бо так і сталося.

Крок 3 — Перевірте

Зателефонуйте своєму агентові з сайту й попросіть відкрити сторінку за назвою. Мають статися дві речі: сторінка відкрилася, і агент сказав щось на кшталт «ось ціни», а не «знайдете їх у меню».

Як відповідати агентові даними

Деякі команди — це запитання, а не вказівки. Надходять вони так само, але відповідати треба через respond():

Команда	Про що питає агент	Чим відповідаєте
`navigate`	«відкрий цей шлях»	нічим — досить `preventDefault()`
`page_context`	«що зараз перед відвідувачем?»	будь-чим корисним: шлях, заголовок, товар
`cart_state`	«що в нього в кошику?»	позиції, суми, валюта

<script>
document.addEventListener('agent-command', (event) => {
  const { type, respond } = event.detail;

  if (type === 'page_context') {
    event.preventDefault();
    respond({ path: location.pathname, title: document.title });
  }
});
</script>

Після preventDefault() на відповідь є приблизно секунда, тож await допустимий, а повільний запит до API — ні. Відповідайте тим, що вже маєте під рукою.

Що агент може просити, а що ні

Лише шляхи всередині вашого сайту. Шлях має починатися з /. Усе, що виводить із домену — //evil.com, https://…, зворотні скісні — відхиляється ще до вашої сторінки. Відвести відвідувача на чужий сайт агент не може.
Лише дзвінки з браузера. Під час телефонного дзвінка відкривати нема чого, тож там таких команд немає.
Однієї відмови досить. Якщо сторінка не підтвердила перший запит, агент припиняє питати до кінця дзвінка. Він не спробує знову і — що важливіше — не скаже відвідувачеві, що відкрив те, чого не відкривав.

Нічого не відбувається?

Виводьте кожну команду до того, як фільтруєте: document.addEventListener('agent-command', e => console.log(e.detail)). Бачите в консолі navigate — агент свою частину зробив, отже, річ у preventDefault() або у вашому обробнику. Не бачите нічого — агентові не сказали, що такий шлях існує; поверніться до кроку 1.

Технічні вимоги

Віджети вимагають, щоб браузер відвідувача підтримував:

WebGL 2.0 — для рендерингу
Web Audio API — для обробки аудіо
WebRTC — для голосової комунікації в реальному часі

Усі сучасні браузери (Chrome, Firefox, Safari, Edge) підтримують ці технології.

Обмеження доменів

Контролюйте, які сайти можуть вбудовувати ваш віджет агента.

Завжди дозволені домени

Наступні домени дозволені завжди, незалежно від конфігурації:

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

Дозволити всі домени

За замовчуванням ваш віджет можна вбудовувати на будь-якому сайті. Перемкніть «Allow all domains» у налаштуваннях віджета, щоб це обмежити.

Обмежити конкретними доменами

Коли обмежено, додайте кожен домен, який має бути дозволено:

Вводьте назви доменів без https:// (наприклад, example.com)
Піддомени потребують окремих записів (наприклад, www.example.com, shop.example.com)
Можна вказувати порти (наприклад, localhost:3000)
Максимум 50 доменів можна додати в білий список

Безпека

Для продакшн-агентів обмежуйте віджети своїми власними доменами, щоб запобігти несанкціонованому вбудовуванню.

Terms & Conditions

Увімкніть діалог згоди, перш ніж співрозмовники зможуть розпочати розмову.

Конфігурація

Параметр	Опис
Enable Terms	Перемикач діалогу умов on/off
Terms Content	Markdown-форматований текст згоди, що показується користувачам (макс. 5 000 символів)
Terms URL	Посилання на вашу повну сторінку Terms & Conditions
Privacy URL	Посилання на вашу сторінку Privacy Policy

Коли увімкнено:

Користувачі бачать діалог згоди перед початком дзвінка
Вони мають натиснути «Agree», щоб продовжити
Згода зберігається локально в браузері
Кнопка Reset Consent очищає збережену згоду для тестування

Форматування контенту

Контент умов підтримує форматування Markdown:

Використовуйте #### для заголовків
Використовуйте **bold** для виділення
Використовуйте переноси рядків для зручності читання

Пов'язане

Віджет зворотного дзвінка — Телефонні зворотні дзвінки для відвідувачів, які не хочуть говорити в браузері
Огляд голосових агентів
Налаштування — Налаштування агента, включно з конфігурацією віджета
Інтеграції — Налаштування ключів API та номерів телефонів

Віджети сайту

Типи віджетів

Спільні атрибути

Атрибути відображення

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

Атрибути умов

Звукові атрибути

Кольорові теми

Приклади вбудовування

Floating Widget

Floating Widget із темою та позицією

Pill Widget

Inline Widget

Події віджета

Приклад: прослуховування подій

Як дозволити агентові відкривати сторінки

Крок 1 — Скажіть агентові, які сторінки існують

Крок 2 — Обробіть запит на своїй сторінці

Крок 3 — Перевірте

Як відповідати агентові даними

Що агент може просити, а що ні

Технічні вимоги

Обмеження доменів

Завжди дозволені домени

Дозволити всі домени

Обмежити конкретними доменами

Terms & Conditions

Конфігурація

Форматування контенту

Пов'язане

Типи віджетів​

Спільні атрибути​

Атрибути відображення​

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

Атрибути умов​

Звукові атрибути​

Кольорові теми​

Приклади вбудовування​

Floating Widget​

Floating Widget із темою та позицією​

Pill Widget​

Inline Widget​

Події віджета​

Приклад: прослуховування подій​

Як дозволити агентові відкривати сторінки​

Крок 1 — Скажіть агентові, які сторінки існують​

Крок 2 — Обробіть запит на своїй сторінці​

Крок 3 — Перевірте​

Як відповідати агентові даними​

Що агент може просити, а що ні​

Технічні вимоги​

Обмеження доменів​

Завжди дозволені домени​

Дозволити всі домени​

Обмежити конкретними доменами​

Terms & Conditions​

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

Форматування контенту​

Пов'язане​

Типи віджетів

Спільні атрибути

Атрибути відображення

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

Атрибути умов

Звукові атрибути

Кольорові теми

Приклади вбудовування

Floating Widget

Floating Widget із темою та позицією

Pill Widget

Inline Widget

Події віджета

Приклад: прослуховування подій

Як дозволити агентові відкривати сторінки

Крок 1 — Скажіть агентові, які сторінки існують

Крок 2 — Обробіть запит на своїй сторінці

Крок 3 — Перевірте

Як відповідати агентові даними

Що агент може просити, а що ні

Технічні вимоги

Обмеження доменів

Завжди дозволені домени

Дозволити всі домени

Обмежити конкретними доменами

Terms & Conditions

Конфігурація

Форматування контенту

Пов'язане