Integrer webwidgetten

Tilføj en stemmeagent på dit marketing- eller supportsite med et enkelt script-tag — besøgende taler direkte med den fra browseren, uden behov for et telefonnummer.

Webwidgetten giver dine besøgende på webstedet en klik-for-at-tale-samtale med en AI-agent ved hjælp af browserens mikrofon. Det er et separat JavaScript- / React-SDK med sin egen SDK-reference — denne vejledning fokuserer på den ThunderPhone-opsætning, som widgetten har brug for.

Forudsætninger#

1. Opret en agent

   Agenten, hvis prompt og stemme skal køre widgetsessionen. Indstil widget_enabled: true (standardindstillingen).

2. Vælg routingtilstand
   • mode="agent" — én statisk agent pr. nøgle. Enklest.
   • mode="webhook" — din server vælger agenten pr. besøgende via en web.incoming-webhook. Brug dette til indloggede brugere, A/B-tests eller routing pr. side.
3. Angiv de tilladte domæner

   Angiv hvert værtsnavn, der skal indlejre widgetten. Browsere sender sidens oprindelse med hver sessionsanmodning, så listen forhindrer din nøgle i at virke, hvis nogen kopierer den til et andet websted. Det er ikke godkendelse: et script uden for en browser kan sende enhver Origin- header. localhost er ikke automatisk tilladt i produktion; hvis du vil teste lokalt mod produktions-API'et, skal du føje localhost til listen.

4. Vælg browseroverstyringer

   Vælg, hvilke sessionsindstillinger din side må sende. Nye nøgler accepterer ingen; se Browseroverstyringer.

Opret en udgivbar nøgle#

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

Svaret indeholder en key, der starter med pk_live_.... Udgivbare nøgler er offentlige af design — de kan sikkert inkluderes i din frontend-pakke. Se reference for udgivbare nøgler for alle felter.

Indsæt widgetten på dit websted#

Tre integrationsmuligheder er beskrevet i widget-SDK-dokumentationen:

Alle tre accepterer den samme publishableKey og gengiver mikrofonknappen samt lydelementet under opkaldet.

Browseroverstyringer#

Widgetten kan sende fire indstillinger pr. session fra siden:

Din publicerbare nøgle er offentlig, så alle, der har den, kan sende disse indstillinger, også fra et script, der udgiver sig for at være dit domæne. De er derfor alle slået fra, indtil du tillader dem på nøglen: markér dem under Browseroverstyringer, når du opretter eller redigerer widgetten i dashboardet, eller angiv allowed_overrides via API'et for publicerbare nøgler. Tillad kun det, din side faktisk sender.

En sessionsanmodning, der indeholder en indstilling, som nøglen ikke tillader, mislykkes med 400 og angiver den:

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

Kontrollen gælder i begge tilstande. I webhooktilstand videresendes en tilladt indstilling også til din web.incoming-webhook (context ankommer som website_context). Nøgler, der blev oprettet, før denne indstilling fandtes, tillader alle fire, så eksisterende indlejringer fortsat virker; deaktiver det, du ikke bruger.

Widgettens context afkortes ved 12.000 tegn (omtrent 3.400 tokens af typisk engelsk tekst) og tæller med i tillægget for promptstørrelse. Agenten instrueres i at behandle den som sideindhold, ikke som instruktioner.

Webhooks i widgettilstand#

Når mode="webhook", kalder ThunderPhone din webhook_url ved hver sessionsstart med en web.incoming-payload. Returner den agentkonfiguration, du vil køre for den besøgende — den følger samme svartskema som telefonopkald:

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

Du kan blande kontekst fra din egen session (hvilken kunde der browser, hvilken side de er på) ind i prompten og skifte agenter for hver udrulning.

Overvåg sessionerne#

Widgetsessioner vises i GET /v1/calls med direction="widget" — samme transskription, optagelse, vurdering og fakturering som telefonopkald. Filtrér efter direction for at opbygge et dashboard kun til widgets.

Næste trin#