Developer cookbook

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 köra widgetsessionen. Ange widget_enabled: true (standardvärdet).

2. Bestäm routningsläget
   • 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

   Publicerbara nycklar är låsta till ursprung. Du måste ange varje värdnamn som ska bädda in widgeten. localhost / 127.0.0.1 är alltid tillåtna under lokal utveckling.

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

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.

Widgetens context trunkeras vid 12 000 tecken (ungefär 3 400 token av typisk engelsk text) och räknas mot tillägget för promptstorlek.

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#