ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

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ľúč

Static agent
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"]
  }'
Dynamic via webhook
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:

NastavenieVlastnosť widgetuČo mení
contextcontextText 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
voicevoiceHlas agenta pre túto reláciu
languagelanguageJazyk, 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