Ugradite web widget

Dodajte glasovnog agenta na svoju marketinšku stranicu ili stranicu za podršku jednom oznakom skripte — posjetitelji s njim razgovaraju izravno iz preglednika, bez potrebe za telefonskim brojem.

Web-widget vašim posjetiteljima web-mjesta omogućuje razgovor klikom za govor s AI glasovnim agentom putem mikrofona preglednika. To je zaseban JavaScript / React SDK s vlastitom SDK referencom — ovaj vodič usredotočen je na postavljanje na strani ThunderPhonea koje widget treba.

Preduvjeti#

1. Izradite agenta

   Agent čiji će upit i glas pokretati sesiju widgeta. Postavite widget_enabled: true (zadano).

2. Odlučite o načinu usmjeravanja
   • mode="agent" — jedan statični agent po ključu. Najjednostavnije.
   • mode="webhook" — vaš poslužitelj odabire agenta za svakog posjetitelja putem web.incoming webhooka. Upotrijebite ovo za prijavljene korisnike, A/B testove ili usmjeravanje po stranici.
3. Navedite dopuštene domene

   Navedite svaki naziv hosta koji će ugraditi widget. Preglednici šalju ishodište stranice sa svakim zahtjevom za sesiju, pa popis sprječava rad vašeg ključa kada ga netko kopira na drugo web-mjesto. To nije autentifikacija: skripta izvan preglednika može poslati bilo koje zaglavlje Origin. localhost nije automatski dopušten u produkciji; za lokalno testiranje s produkcijskim API-jem dodajte localhost na popis.

4. Odaberite nadjačavanja preglednika

   Odlučite koje postavke sesije vaša stranica smije slati. Novi ključevi ne prihvaćaju nijednu; pogledajte Nadjačavanja preglednika.

Stvorite 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 uključuje key koji počinje s pk_live_.... Objavljivi ključevi javni su po dizajnu — sigurno ih je uključiti u paket vašeg sučelja. Pogledajte referencu objavljivih ključeva za sva polja.

Ugradite widget na svoje web-mjesto#

Tri mogućnosti integracije obuhvaćene su u dokumentaciji SDK-a za widget:

Sve tri mogućnosti prihvaćaju isti publishableKey i prikazuju gumb mikrofona te audioelement tijekom poziva.

Nadjačavanja iz preglednika#

Widget može poslati četiri postavke po sesiji sa stranice:

Vaš ključ za objavu javan je, pa svatko tko ga ima može poslati ove postavke, uključujući iz skripte koja oponaša vašu domenu. Svaka je stoga isključena dok je ne dopustite za ključ: označite je u odjeljku Nadjačavanja preglednika kada stvarate ili uređujete widget na nadzornoj ploči ili postavite allowed_overrides putem API-ja za ključeve za objavu. Dopustite samo ono što vaša stranica zaista šalje.

Zahtjev za sesiju koji sadrži postavku koju ključ ne dopušta ne uspijeva s kodom 400 i navodi je:

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

Provjera se primjenjuje u oba načina rada. U načinu rada webhooka dopuštena se postavka također prosljeđuje vašem webhooku web.incoming (context stiže kao website_context). Ključevi stvoreni prije nego što je ova postavka postojala dopuštaju sve četiri, pa postojeća ugrađivanja nastavljaju raditi; isključite ono što ne koristite.

context widgeta skraćuje se na 12.000 znakova (otprilike 3.400 tokena tipičnog engleskog teksta) i uračunava se u doplatu za veličinu prompta. Agentu se nalaže da ga tretira kao sadržaj stranice, a ne kao upute.

Webhookovi načina rada widgeta#

Kada je mode="webhook", ThunderPhone poziva vaš webhook_url pri svakom početku sesije s teretom web.incoming. Vratite konfiguraciju agenta koju želite pokrenuti za tog posjetitelja — slijedi istu shemu odgovora kao telefonski pozivi:

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

U upit možete uključiti kontekst iz vlastite sesije (koji korisnik pregledava, na kojoj se stranici nalazi) i mijenjati agente ovisno o postupnom uvođenju.

Pratite sesije#

Sesije widgeta prikazuju se u GET /v1/calls s postavkom direction="widget" — s istim transkriptom, snimkom, ocjenjivanjem i naplatom kao i telefonski pozivi. Filtrirajte prema direction kako biste izradili nadzornu ploču samo za widget.

Sljedeći koraci#