Vdelajte spletni gradnik

Dodajte glasovnega agenta na svoje trženjsko ali podporno spletno mesto z eno samo oznako skripta — obiskovalci se z njim pogovarjajo neposredno iz brskalnika, telefonska številka ni potrebna.

Spletni gradnik obiskovalcem vašega spletnega mesta omogoča pogovor s klikom za pogovor z agentom AI prek mikrofona v brskalniku. Gre za ločen JavaScript / React SDK z lastno referenco SDK — ta vodnik se osredotoča na nastavitev na strani ThunderPhone, ki jo gradnik potrebuje.

Predpogoji#

1. Ustvarite agenta

   Agent, katerega poziv in glas bosta uporabljena v seji gradnika. Nastavite widget_enabled: true (privzeto).

2. Določite način usmerjanja
   • mode="agent" — en statični agent na ključ. Najpreprosteje.
   • mode="webhook" — vaš strežnik izbere agenta za vsakega obiskovalca prek spletnega kavlja web.incoming. To uporabite za prijavljene uporabnike, A/B-teste ali usmerjanje po posameznih straneh.
3. Navedite dovoljene domene

   Navedite vsako ime gostitelja, ki bo vdelalo gradnik. Brskalniki z vsako zahtevo za sejo pošljejo izvor strani, zato seznam prepreči, da bi vaš ključ deloval, če ga nekdo kopira na drugo spletno mesto. To ni preverjanje pristnosti: skript zunaj brskalnika lahko pošlje katero koli glavo Origin. localhost v produkciji ni samodejno dovoljen; za lokalno testiranje s produkcijskim API-jem dodajte localhost na seznam.

4. Izberite preglasitve v brskalniku

   Določite, katere nastavitve seje lahko pošlje vaša stran. Novi ključi ne sprejemajo nobene; glejte Preglasitve v brskalniku.

Ustvarite objavljivi ključ#

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

Odgovor vključuje key, ki se začne z pk_live_.... Objavljivi ključi so javni že po zasnovi — varno jih lahko vključite v paket frontenda. Za vsa polja glejte referenco objavljivih ključev.

Dodajte gradnik na svoje spletno mesto#

V dokumentaciji SDK za gradnik so obravnavane tri možnosti integracije:

Vse tri možnosti sprejmejo isti publishableKey in prikažejo gumb za mikrofon ter zvočni element med klicem.

Preglasitve brskalnika#

Pripomoček lahko s strani pošlje štiri nastavitve za posamezno sejo:

Vaš objavljivi ključ je javen, zato lahko te nastavitve pošlje vsakdo, ki ga ima, tudi iz skripta, ki ponareja vašo domeno. Vsaka je zato izklopljena, dokler je ne dovolite za ključ: ob ustvarjanju ali urejanju gradnika na nadzorni plošči jo označite v razdelku Preglasitve brskalnika ali nastavite allowed_overrides prek API-ja za objavljive ključe. Dovolite le tisto, kar vaša stran dejansko pošilja.

Zahteva za sejo, ki vsebuje nastavitev, ki je ključ ne dovoljuje, ne uspe z 400 in jo navede:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Preverjanje velja v obeh načinih. V načinu webhook se dovoljena nastavitev posreduje tudi vašemu webhooku web.incoming (context prispe kot website_context). Ključi, ustvarjeni pred uvedbo te nastavitve, dovoljujejo vse štiri, zato obstoječe vdelave še naprej delujejo; izklopite tisto, česar ne uporabljate.

context pripomočka je omejen na 12.000 znakov (približno 3.400 žetonov običajnega angleškega besedila) in se všteva v doplačilo za velikost poziva. Agentu je naročeno, naj ga obravnava kot vsebino strani, ne kot navodila.

Webhooki načina gradnika#

Ko je mode="webhook", ThunderPhone ob vsakem začetku seje pokliče vaš webhook_url s koristnim tovorom web.incoming. Vrnite konfiguracijo agenta, ki jo želite zagnati za tega obiskovalca — uporablja isto odzivno shemo kot telefonski klici:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

V poziv lahko vključite kontekst iz lastne seje (katera stranka brska, na kateri strani je) in menjate agente za posamezne uvedbe.

Spremljajte seje#

Seje gradnika se prikažejo v GET /v1/calls z direction="widget" — z enakim prepisom, posnetkom, ocenjevanjem in obračunavanjem kot telefonski klici. Filtrirajte po direction, da ustvarite nadzorno ploščo samo za gradnik.

Naslednji koraki#