Bygg inn nettwidgeten

Legg en stemmeagent på markedsførings- eller supportsiden din med én enkelt script-tag – besøkende snakker med den direkte fra nettleseren, uten behov for telefonnummer.

Nettwidgeten gir besøkende på nettstedet ditt en klikk-for-å-snakke-samtale med en stemmeagent ved å bruke nettleserens mikrofon. Det er et separat JavaScript- / React-SDK med sin egen SDK-referanse — denne veiledningen fokuserer på oppsettet på ThunderPhone-siden som widgeten trenger.

Forutsetninger#

1. Opprett en agent

   Agenten hvis prompt og stemme skal kjøre widgetøkten. Angi widget_enabled: true (standardinnstillingen).

2. Velg rutingsmodus
   • mode="agent" — én statisk agent per nøkkel. Enklest.
   • mode="webhook" — serveren din velger agenten per besøkende via en web.incoming-webhook. Bruk dette for innloggede brukere, A/B-tester eller ruting per side.
3. List opp de tillatte domenene

   Oppgi hvert vertsnavn som skal bygge inn widgeten. Nettlesere sender sidens opprinnelse med hver øktforespørsel, så listen hindrer nøkkelen din i å fungere når noen kopierer den til et annet nettsted. Dette er ikke autentisering: et skript utenfor en nettleser kan sende enhver Origin- header. localhost er ikke automatisk tillatt i produksjon; for å teste lokalt mot produksjons-API-et, legg til localhost i listen.

4. Velg nettleseroverstyringene

   Bestem hvilke øktinnstillinger siden din kan sende. Nye nøkler godtar ingen; se Nettleseroverstyringer.

Opprett en publiserbar nøkkel#

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

Responsen inneholder en key som starter med pk_live_.... Publiserbare nøkler er offentlige av hensikt — det er trygt å inkludere dem i front-end-pakken din. Se referansen for publiserbare nøkler for alle felter.

Legg widgeten på nettstedet ditt#

Tre integrasjonsalternativer dekkes i widget-SDK-dokumentasjonen:

Alle tre godtar samme publishableKey og viser mikrofonknappen samt lydelementet under samtalen.

Nettleseroverstyringer#

Widgeten kan sende fire innstillinger per økt fra siden:

Den publiserbare nøkkelen din er offentlig, så alle som har den, kan sende disse innstillingene, også fra et skript som utgir seg for å være domenet ditt. Hver av dem er derfor deaktivert til du tillater den for nøkkelen: merk av for den under Nettleseroverstyringer når du oppretter eller redigerer widgeten i dashbordet, eller angi allowed_overrides via API-et for publiserbare nøkler. Tillat bare det siden din faktisk sender.

En øktforespørsel som inneholder en innstilling nøkkelen ikke tillater, mislykkes med 400 og oppgir den:

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

Kontrollen gjelder i begge modus. I webhook-modus blir en tillatt innstilling også videresendt til web.incoming-webhooken din (context kommer som website_context). Nøkler opprettet før denne innstillingen fantes, tillater alle fire, så eksisterende innbygginger fortsetter å fungere; slå av det du ikke bruker.

Widgetens context avkortes til 12 000 tegn (omtrent 3 400 token i typisk engelsk tekst) og regnes med i tillegget for promptstørrelse. Agenten får beskjed om å behandle den som sideinnhold, ikke som instruksjoner.

Webhooks i widgetmodus#

Når mode="webhook", kaller ThunderPhone webhook_url ved hver øktstart med en web.incoming-nyttelast. Returner agentkonfigurasjonen du vil kjøre for den besøkende — den følger samme responsformat som telefonsamtaler:

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

Du kan blande inn kontekst fra din egen økt (hvilken kunde som surfer, hvilken side de er på) i prompten og bytte agent per utrulling.

Overvåk øktene#

Widgetøkter vises i GET /v1/calls med direction="widget" — samme transkripsjon, opptak, vurdering og fakturering som telefonsamtaler. Filtrer etter direction for å bygge et dashboard kun for widgeten.

Neste steg#