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. Vytvoriť agenta

   Agent, ktorého prompt a hlas budú riadiť reláciu widgetu. Nastavte widget_enabled: true (predvolené).

2. 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 webhooku web.incoming. Použite ho pre prihlásených používateľov, A/B testy alebo smerovanie podľa stránky.
3. 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. localhost nie je v produkcii automaticky povolený; ak chcete lokálne testovať oproti produkčnému API, pridajte localhost do zoznamu.

4. 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:

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:

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.

Hodnota context widgetu sa skráti na 12,000 znakov (približne 3,400 tokenov typického anglického textu) a započítava sa do príplatku za veľkosť promptu. Agent dostane pokyn, aby ju považoval za obsah stránky, nie za inštrukcie.

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#