Open in
Vloženie webového widgetu
Pridajte hlasového agenta na svoj marketingový alebo podporný web jediným značkou script — návštevníci s ním hovoria priamo z prehliadača, bez potreby telefónneho čísla.
Webový widget umožňuje návštevníkom vašej stránky konverzáciu po kliknutí na hovor s hlasovým agentom AI pomocou mikrofónu prehliadača. Ide o samostatné JavaScript / React SDK s vlastnou referenciou SDK — táto príručka sa zameriava na nastavenie na strane ThunderPhone, ktoré widget potrebuje.
Požiadavky
- Vytvoriť agenta
Agent, ktorého prompt a hlas budú riadiť reláciu widgetu. Nastavte
widget_enabled: true(predvolené). - Rozhodnúť o režime smerovania
mode="agent"— jeden statický agent na kľúč. Najjednoduchšie.mode="webhook"— váš server vyberie agenta pre každého návštevníka prostredníctvom webhookuweb.incoming. Použite ho pre prihlásených používateľov, A/B testy alebo smerovanie podľa stránky.
- Uviesť povolené domény
Uveďte každý názov hostiteľa, do ktorého sa vloží widget. Prehliadače odosielajú pôvod stránky s každou požiadavkou na reláciu, takže tento zoznam zabráni fungovaniu vášho kľúča, keď ho niekto skopíruje na inú stránku. Nejde o overovanie: skript mimo prehliadača môže odoslať ľubovoľnú hlavičku
Origin.localhostnie je v produkcii automaticky povolený; ak chcete lokálne testovať oproti produkčnému API, pridajtelocalhostdo zoznamu. - Vybrať prepisy prehliadača
Rozhodnite, ktoré nastavenia relácie môže vaša stránka odosielať. Nové kľúče neprijímajú žiadne; pozrite si Prepisy prehliadača.
Vytvorte publikovateľný kľúč
curl -X POST https://api.thunderphone.com/v1/publishable-key \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing site (prod)",
"mode": "agent",
"agent_id": 12,
"allowed_domains": ["example.com", "*.example.com"],
"allowed_overrides": ["context"]
}'curl -X POST https://api.thunderphone.com/v1/publishable-key \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support (dynamic)",
"mode": "webhook",
"webhook_url": "https://example.com/thunderphone/widget-hook",
"allowed_domains": ["support.example.com"]
}'Odpoveď obsahuje key začínajúci na pk_live_.... Publikovateľné
kľúče sú verejné už svojím návrhom — môžete ich bezpečne zahrnúť do balíka front-endu.
Všetky polia nájdete v referencii publikovateľných kľúčov.
Vložte widget na svoju stránku
V dokumentácii SDK widgetu sú popísané tri možnosti integrácie:
<ThunderPhoneWidget publishableKey="pk_live_..." />.
useThunderPhone() pre vlastné používateľské rozhrania.
ThunderPhone.mount({...}) pre stránky bez bundlera.
Všetky tri prijímajú rovnaký publishableKey a vykreslia tlačidlo mikrofónu
spolu so zvukovým prvkom počas hovoru.
Prepísania z prehliadača
Widget môže zo stránky odoslať štyri nastavenia pre reláciu:
| Nastavenie | Vlastnosť widgetu | Čo mení |
|---|---|---|
context | context | Text zo stránky pripojený k promptu agenta ako referencia |
variables | žiadna (iba nespracovaný POST /v1/widget/session) | Hodnoty pre zástupné symboly {{variable}} v prompte |
voice | voice | Hlas agenta pre túto reláciu |
language | language | Jazyk, v ktorom sa relácia začne |
Váš publikovateľný kľúč je verejný, takže ktokoľvek, kto ho má, môže odosielať tieto
nastavenia vrátane zo skriptu, ktorý napodobňuje vašu doménu. Každé z nich je
preto vypnuté, kým ho nepovolíte pre daný kľúč: zaškrtnite ho v časti Prepísania
prehliadača, keď vytvárate alebo upravujete widget na ovládacom paneli, alebo nastavte
allowed_overrides prostredníctvom
API publikovateľných kľúčov. Povoľte iba to, čo
vaša stránka skutočne odosiela.
Požiadavka na reláciu, ktorá obsahuje nastavenie nepovolené daným kľúčom, zlyhá
s chybou 400 a uvedie jeho názov:
{
"error": "override_not_allowed",
"fields": ["voice"],
"message": "This publishable key does not allow the browser to set `voice`. ..."
}Kontrola platí v oboch režimoch. V režime webhooku sa povolené nastavenie
tiež prepošle do vášho webhooku web.incoming (context príde ako
website_context). Kľúče vytvorené pred zavedením tohto nastavenia povoľujú všetky
štyri, takže existujúce vloženia naďalej fungujú; vypnite to, čo nepoužívate.
context widgetu sa skracuje na 12 000 znakov (približne 3 400
tokenov typického anglického textu) a je súčasťou výzvy, ktorú modely čítajú, takže
dlhší kontext stojí viac za minútu.
Agent dostane pokyn, aby ho považoval za obsah stránky, nie za pokyny.
Webhooky režimu widgetu
Keď je nastavené mode="webhook", ThunderPhone zavolá váš webhook_url pri každom
spustení relácie s dátami web.incoming. Vráťte konfiguráciu agenta,
ktorú chcete pre daného návštevníka spustiť — používa rovnakú
schému odpovede ako telefónne
hovory:
{
"prompt": "You are a VIP concierge for Jane Doe.",
"voice": "john",
"product": "storm-base",
"tools": [ /* per-customer tools */ ]
}Do pokynu môžete pridať kontext z vlastnej relácie (ktorý zákazník prezerá obsah, na ktorej stránke sa nachádza) a pri každom nasadení meniť agentov.
Sledujte relácie
Relácie widgetu sa zobrazujú v
GET /v1/calls s
direction="widget" — s rovnakým prepisom, nahrávkou, hodnotením a
fakturáciou ako telefonické hovory. Filtrujte podľa direction a vytvorte si
dashboard iba pre widget.
Ďalšie kroky
Podrobnosti integrácie Reactu / hookov / CDN.
Implementujte tok mode="webhook" od začiatku do konca.
Každé pole v prostriedku kľúča.
Preskočte widget; pre vlastné používateľské rozhrania ovládajte LiveKit priamo.