Webové widgety
Vložte svého hlasového agenta na jakýkoli web, aby návštěvníci mohli zahájit hlasovou konverzaci přímo z prohlížeče. Karta Widgety poskytuje kódy pro vložení, možnosti přizpůsobení a nastavení doménového zabezpečení.
Widget zpětného volání funguje velmi odlišně od widgetů na této stránce — místo zahájení hlasového hovoru v prohlížeči sbírá telefonní číslo návštěvníka a nechá vašeho agenta zavolat mu zpět. Viz samostatná stránka Widget zpětného volání.
Typy widgetů
Hanc.AI nabízí čtyři typy widgetů v prohlížeči a navíc samostatný Widget zpětného volání pro telefonická zpětná volání:
| Widget | Název tagu | Popis | Nejvhodnější pro |
|---|---|---|---|
| Plovoucí widget | hanc-ai-floating-call | Tlačítko v podobě koule plovoucí nad vaší stránkou | Vždy viditelná výzva k akci |
| Pilulkový widget | hanc-ai-pill-call | Kompaktní tlačítko ve tvaru pilulky umístěné vloženě ve vašem obsahu | Minimální stopa uvnitř stávajícího rozvržení |
| Plovoucí pilulkový widget | hanc-ai-pill-floating-call | Stejný kompaktní tvar pilulky jako Pilulka, ale plove se stránkou jako plovoucí widget | Když chcete estetiku pilulky, která návštěvníka sleduje při posouvání |
| Vložený widget | hanc-ai-inline-call | Tlačítko hovoru v plné velikosti vložené do obsahu stránky | Vyhrazené sekce „Zavolejte nám“ |
| Widget zpětného volání | hanc-ai-callback | Formulář pro telefonní číslo; agent zavolá návštěvníkovi zpět | Stránky pro sběr leadů, vstupní stránky s vysokým záměrem — viz Widget zpětného volání |
Společné atributy
Všechny typy widgetů podporují tyto základní atributy:
| Atribut | Povinný | Popis | Výchozí |
|---|---|---|---|
agent-id | Ano | Jedinečný identifikátor vašeho agenta | — |
voice-service-url | Ne | Přepsat URL hlasové služby | Automaticky detekováno |
api-base-url | Ne | Přepsat základní URL API | Automaticky detekováno |
Atributy zobrazení
| Atribut | Popis | Hodnoty | Výchozí |
|---|---|---|---|
position | Pozice widgetu na stránce | bottom-right, bottom-left, top-right, top-left, static | bottom-right |
size | Velikost widgetu v pixelech | Číslo | 120 |
theme | Název barevného motivu | Viz Barevné motivy | default |
Atributy textu tlačítka
| Atribut | Popis | Výchozí |
|---|---|---|
button-start-text | Text zobrazený na nečinném tlačítku | "Call" |
button-connecting-text | Text zobrazený během navazování | "Connecting..." |
button-end-text | Text zobrazený během aktivního hovoru | — |
Atributy podmínek
| Atribut | Popis | Výchozí |
|---|---|---|
terms-enabled | Zapnout dialog souhlasu před hovorem | false |
terms-content | Text souhlasu formátovaný v Markdownu | "" |
terms-url | Odkaz na vaši stránku s podmínkami a smluvními ujednáními | "https://hanc.ai/terms" |
privacy-url | Odkaz na vaši stránku se zásadami ochrany osobních údajů | "https://hanc.ai/privacy" |
Atributy podmínek nastavené na HTML elementu jsou přepsány nastavením widgetu agenta získaným z API, pokud není skip-fetch nastaveno na true.
Atributy zvuku
| Atribut | Popis | Výchozí |
|---|---|---|
sound-enabled | Zapnout zvuky začátku/konce hovoru | true |
sound-volume | Hlasitost zvukového efektu | 0.25 |
sound-preset | Identifikátor zvukové předvolby | "1" |
Barevné motivy
Přizpůsobte vzhled widgetu pomocí 11 vestavěných barevných motivů:
| Motiv | Hodnota |
|---|---|
| Default | default |
| Purple | purple |
| Blue | blue |
| Cyan | cyan |
| Emerald | emerald |
| Amber | amber |
| Tangerine | tangerine |
| Rose | rose |
| Ember | ember |
| Black | black |
| White | white |
Každý motiv má tmavou i světlou variantu. Motiv nastavte pomocí atributu theme v kódu pro vložení, nebo ho nakonfigurujte v nastavení widgetu agenta.
Příklady vložení
Plovoucí 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>
Plovoucí widget s motivem a pozicí
<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>
Pilulkový 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>
Vložený 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>
Výše uvedená URL skriptu vždy načte nejnovější vydaný widget — váš web automaticky přebírá vylepšení a @latest je výchozí, když není zadána žádná verze. Pokud potřebujete zamknout na pevné vydání, připněte ho explicitně přidáním požadované verze, např. https://unpkg.com/hanc-webrtc-widgets@X.Y.Z.
Události widgetu
Widgety vysílají události, na které můžete naslouchat v JavaScriptu:
| Událost | Popis |
|---|---|
status-changed | Vyvolá se při změně stavu hovoru |
connecting | Hovor se navazuje |
connected | Hovor je aktivní |
idle | Žádný aktivní hovor |
error | Došlo k chybě |
audio-track | Přijata vzdálená zvuková stopa (pro vizualizaci) |
local-audio-track | Zvuková stopa z lokálního mikrofonu (pro vizualizaci) |
microphone-enabled | Mikrofon byl zapnut |
microphone-disabled | Mikrofon byl vypnut |
call-start | Vyvolá se, když hovor úspěšně začne |
call-end | Vyvolá se, když hovor skončí |
Příklad: Naslouchání událostem
const widget = document.querySelector('hanc-ai-floating-call');
widget.addEventListener('call-start', () => {
console.log('Call started');
});
widget.addEventListener('call-end', () => {
console.log('Call ended');
});
Jak nechat agenta otevírat stránky
Během hovoru z prohlížeče může agent požádat váš web, aby otevřel stránku – „ukážu vám ceník“ – a návštěvník to vidí, aniž by přerušil rozhovor.
Rozhoduje vaše stránka. Agent pošle požadavek, váš kód určí, co znamená. Otevřít adresu, přepnout záložku, odrolovat k sekci a rozbalit accordion – všechno jsou platné odpovědi.
Jsou k tomu tři kroky a žádný nefunguje samostatně.
Krok 1 – Řekněte agentovi, jaké stránky existují
Agent nevidí mapu vašeho webu. Ptá se vždy jen na cestu, kterou jste mu dali – vypište je v promptu agenta nebo ve znalostní bázi:
Stránky našeho webu:
/pricing — tarify a ceny
/contact — kontaktní formulář a telefon
/product/crm — CRM
Bez tohoto kroku nemá agent nač se ptát, a tak to ani nezkusí.
Krok 2 – Zpracujte požadavek na své stránce
Přidejte to jednou, kdekoli za skriptem widgetu. Událost probublává stránkou, takže document je vhodné místo:
<script>
document.addEventListener('agent-command', (event) => {
const { type, payload } = event.detail;
if (type === 'navigate') {
// SPA: přechod bez načtení stránky — hovor pokračuje.
router.push(payload.path);
// Klasický web: otevřít druhou záložku, tato (a hovor) zůstane naživu.
// window.open(payload.path, '_blank');
event.preventDefault(); // ← tím agentovi říkáte „vyřízeno“
}
});
</script>
Hovor žije v této stránce. window.location.href = … dokument zahodí a rozhovor jde s ním — návštěvník je přerušen uprostřed věty. Máte-li router, přecházejte na klientu; jinak stránku otevřete v nové záložce. Znovupřipojení neexistuje: načtení stránky nepřežije nic.
preventDefault() není volitelnéJe to jediný způsob, jak říct „zpracoval jsem to“. Bez něj se agent dozví, že web navigaci nepodporuje: po zbytek hovoru to přestane zkoušet a vrátí se k popisu, kam kliknout. V konzoli se nic neobjeví – stránka prostě vypadá, že požadavek ignorovala, protože ho ignorovala.
Krok 3 – Vyzkoušejte to
Zavolejte svému agentovi z webu a požádejte o stránku jménem. Mají nastat dvě věci: stránka se otevře a agent řekne něco jako „tady jsou ceny“ místo „najdete je v menu“.
Jak agentovi odpovědět daty
Některé příkazy jsou otázky, ne pokyny. Přicházejí stejně, ale odpovídá se přes respond():
| Příkaz | Na co se agent ptá | Čím odpovíte |
|---|---|---|
navigate | „otevři tuto cestu“ | ničím – stačí preventDefault() |
page_context | „na co se návštěvník dívá?“ | čímkoli užitečným: cesta, titulek, produkt |
cart_state | „co má v košíku?“ | položky, součty, měna |
<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>
Po preventDefault() máte na odpověď zhruba sekundu – await je v pořádku, pomalé volání API ne. Odpovězte tím, co už máte po ruce.
Co agent smí a nesmí žádat
- Jen cesty na vašem vlastním webu. Cesta musí začínat
/. Cokoli, co by mohlo opustit vaši doménu –//evil.com,https://…, zpětná lomítka – je odmítnuto dřív, než se dostane na vaši stránku. Agent nemůže poslat návštěvníky jinam. - Jen hovory z prohlížeče. Při telefonním hovoru není co otevírat, takže tam tyto příkazy neexistují.
- Jedno odmítnutí stačí. Pokud vaše stránka nepotvrdí první požadavek, agent se po zbytek hovoru ptát přestane. Nebude to zkoušet znovu a – což je důležitější – neřekne návštěvníkovi, že něco otevřel, když neotevřel.
Logujte každý příkaz ještě před filtrováním: document.addEventListener('agent-command', e => console.log(e.detail)). Vidíte-li v konzoli navigate, agent svou část splnil a chybí preventDefault() nebo váš handler. Nevidíte-li nic, agentovi nikdo neřekl, že taková cesta existuje – zpět ke kroku 1.
Technické požadavky
Widgety vyžadují, aby prohlížeč návštěvníka podporoval:
- WebGL 2.0 — pro vykreslování
- Web Audio API — pro zpracování zvuku
- WebRTC — pro hlasovou komunikaci v reálném čase
Všechny moderní prohlížeče (Chrome, Firefox, Safari, Edge) tyto technologie podporují.
Doménová omezení
Určete, které weby mohou vkládat widget vašeho agenta.
Vždy povolené domény
Následující domény jsou vždy povoleny bez ohledu na konfiguraci:
hanc.ai(a subdomény)hanc.me(a subdomény)localhost
Povolit všechny domény
Ve výchozím nastavení lze váš widget vložit na jakýkoli web. Přepnutím „Povolit všechny domény“ v nastavení widgetu to omezíte.
Omezit na konkrétní domény
Při omezení přidejte každou doménu, která má být povolena:
- Zadejte názvy domén bez
https://(např.example.com) - Subdomény vyžadují samostatné položky (např.
www.example.com,shop.example.com) - Lze zadat porty (např.
localhost:3000) - Na seznam povolených lze zařadit maximálně 50 domén
U produkčních agentů omezte widgety na vlastní domény, abyste zabránili neoprávněnému vkládání.
Podmínky a smluvní ujednání
Zapněte dialog souhlasu předtím, než mohou volající zahájit konverzaci.
Konfigurace
| Nastavení | Popis |
|---|---|
| Zapnout podmínky | Zapnout/vypnout dialog s podmínkami |
| Obsah podmínek | Text souhlasu formátovaný v Markdownu zobrazený uživatelům (max. 5 000 znaků) |
| URL podmínek | Odkaz na vaši úplnou stránku s podmínkami a smluvními ujednáními |
| URL ochrany osobních údajů | Odkaz na vaši stránku se zásadami ochrany osobních údajů |
Když je zapnuto:
- Uživatelé před zahájením hovoru vidí dialog souhlasu
- K pokračování musí kliknout na „Souhlasím“
- Souhlas je uložen lokálně v prohlížeči
- Tlačítko Resetovat souhlas vymaže uložený souhlas pro účely testování
Formátování obsahu
Obsah podmínek podporuje formátování Markdown:
- Použijte
####pro nadpisy - Použijte
**bold**pro zvýraznění - Použijte zalomení řádků pro lepší čitelnost
Související
- Widget zpětného volání — Telefonická zpětná volání pro návštěvníky, kteří raději nechtějí mluvit v prohlížeči
- Přehled hlasových agentů
- Nastavení — Nastavení agenta včetně konfigurace widgetu
- Integrace — API klíče a nastavení telefonního čísla