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#

1. Vytvorte agenta

   Agent, ktorého pokyn a hlas budú použité počas relácie widgetu. Nastavte widget_enabled: true (predvolená hodnota).

2. Rozhodnite o režime smerovania
   • mode="agent" — jeden statický agent pre každý kľúč. Najjednoduchšie riešenie.
   • mode="webhook" — váš server vyberie agenta pre každého návštevníka prostredníctvom webhooku web.incoming. Tento režim použite pre prihlásených používateľov, A/B testy alebo smerovanie podľa stránky.
3. Uveďte povolené domény

   Publikovateľné kľúče sú viazané na pôvod. Musíte uviesť každý názov hostiteľa, ktorý bude vkladať widget. localhost / 127.0.0.1 sú počas lokálneho vývoja vždy povolené.

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"]
  }'

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:

Všetky tri prijímajú rovnaký publishableKey a vykreslia tlačidlo mikrofónu spolu so zvukovým prvkom počas hovoru.

Parameter context widgetu je skrátený na 12 000 znakov (približne 3 400 tokenov bežného anglického textu) a započítava sa do príplatku za veľkosť pokynu.

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#