Bädda in webbwidgeten

Lägg till en röstagent på din marknadsförings- eller supportsida med en enda skripttagg — besökare pratar med den direkt i webbläsaren, utan telefonnummer.

Webbwidgeten ger dina webbplatsbesökare ett samtal där de kan klicka för att prata med en röstagent via webbläsarens mikrofon. Det är ett separat JavaScript-/React-SDK med en egen SDK-referens — den här guiden fokuserar på konfigurationen på ThunderPhone-sidan som widgeten behöver.

Förutsättningar#

1. Skapa en agent

   Agenten vars prompt och röst ska användas i widgetsessionen. Ange widget_enabled: true (standardvärdet).

2. Välj routningsläge
   • mode="agent" — en statisk agent per nyckel. Enklast.
   • mode="webhook" — din server väljer agent per besökare via en web.incoming-webhook. Använd detta för inloggade användare, A/B-tester eller routning per sida.
3. Lista tillåtna domäner

   Ange varje värdnamn som ska bädda in widgeten. Webbläsare skickar sidans ursprung med varje sessionsbegäran, så listan förhindrar att din nyckel fungerar när någon kopierar den till en annan webbplats. Det är inte autentisering: ett skript utanför en webbläsare kan skicka valfri Origin- header. localhost tillåts inte automatiskt i produktion; för att testa lokalt mot produktions-API:t lägger du till localhost i listan.

4. Välj webbläsaröverskrivningar

   Bestäm vilka sessionsinställningar din sida får skicka. Nya nycklar accepterar inga; se Webbläsaröverskrivningar.

Skapa en publicerbar nyckel#

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 innehåller en key som börjar med pk_live_.... Publicerbara nycklar är offentliga avsiktligt — de kan säkert inkluderas i ditt front-end-paket. Se referensen för publicerbara nycklar för alla fält.

Lägg till widgeten på din webbplats#

Tre integrationsalternativ beskrivs i widgetens SDK-dokumentation:

Alla tre accepterar samma publishableKey och renderar mikrofonknappen samt ljudelementet under samtal.

Webbläsaråsidosättningar#

Widgeten kan skicka fyra inställningar per session från sidan:

Din publicerbara nyckel är offentlig, så alla som har den kan skicka dessa inställningar, även från ett skript som utger sig för att vara din domän. Var och en är därför avstängd tills du tillåter den på nyckeln: markera den under Webbläsaråsidosättningar när du skapar eller redigerar widgeten i instrumentpanelen, eller ange allowed_overrides via API för publicerbara nycklar. Tillåt bara det som din sida faktiskt skickar.

En sessionsbegäran som innehåller en inställning som nyckeln inte tillåter misslyckas med 400 och anger den:

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

Kontrollen gäller i båda lägena. I webhook-läge vidarebefordras en tillåten inställning också till din web.incoming-webhook (context kommer som website_context). Nycklar som skapades innan den här inställningen fanns tillåter alla fyra, så befintliga inbäddningar fortsätter att fungera; stäng av det du inte använder.

Widgetens context trunkeras till 12 000 tecken (ungefär 3 400 token för normal engelsk text) och räknas mot tilläggsavgiften för promptstorlek. Röstagenten instrueras att behandla den som sidinnehåll, inte som instruktioner.

Webbhooks i widgetläge#

När mode="webhook" används anropar ThunderPhone din webhook_url vid varje sessionsstart med en web.incoming-payload. Returnera den agentkonfiguration du vill köra för den besökaren — den följer samma svartsschema som telefonsamtal:

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

Du kan blanda in kontext från din egen session (vilken kund som surfar, vilken sida de är på) i prompten och byta agent per utrullning.

Övervaka sessionerna#

Widgetsessioner visas i GET /v1/calls med direction="widget" — samma transkription, inspelning, bedömning och fakturering som telefonsamtal. Filtrera efter direction för att bygga en dashboard enbart för widgeten.

Nästa steg#