Developer cookbook

Sluit de webwidget in

Plaats met één script-tag een spraakagent op je marketing- of supportsite — bezoekers praten er rechtstreeks vanuit de browser mee, zonder telefoonnummer.

De webwidget geeft bezoekers van je site een gesprek via klik om te praten met een AI-agent, met behulp van de microfoon van de browser. Het is een aparte JavaScript- / React-SDK met een eigen SDK-referentie — deze handleiding richt zich op de configuratie aan de ThunderPhone-kant die de widget nodig heeft.

Vereisten#

1. Maak een agent

   De agent waarvan de prompt en stem de widgetsessie uitvoeren. Stel widget_enabled: true in (de standaardwaarde).

2. Bepaal de routeringsmodus
   • mode="agent" — één statische agent per sleutel. Het eenvoudigst.
   • mode="webhook" — je server kiest de agent per bezoeker via een web.incoming-webhook. Gebruik dit voor ingelogde gebruikers, A/B-tests of routering per pagina.
3. Lijst de toegestane domeinen op

   Publiceerbare sleutels zijn gebonden aan de oorsprong. Je moet elke hostnaam opgeven die de widget insluit. localhost / 127.0.0.1 zijn tijdens lokale ontwikkeling altijd toegestaan.

Maak een publiceerbare sleutel#

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

Het antwoord bevat een key die begint met pk_live_.... Publiceerbare sleutels zijn standaard openbaar — je kunt ze veilig opnemen in je front-endbundle. Zie de referentie voor publiceerbare sleutels voor alle velden.

Plaats de widget op je site#

Drie integratieopties worden behandeld in de widget-SDK-documentatie:

Alle drie accepteren dezelfde publishableKey en renderen de microfoonknop plus het audio-element tijdens gesprekken.

De context van de widget wordt afgekapt op 12.000 tekens (ongeveer 3.400 tokens van typische Engelse tekst) en telt mee voor de toeslag voor promptgrootte.

Webhooks voor widgetmodus#

Wanneer mode="webhook" is ingesteld, roept ThunderPhone je webhook_url aan bij elke sessiestart met een web.incoming-payload. Geef de agentconfiguratie terug die je voor die bezoeker wilt uitvoeren — deze volgt hetzelfde antwoordschema als telefoongesprekken:

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

Je kunt context uit je eigen sessie (welke klant browst, op welke pagina ze zijn) in de prompt opnemen en agents per uitrol wisselen.

Sessies bekijken#

Widgetsessies verschijnen in GET /v1/calls met direction="widget" — met hetzelfde transcript, dezelfde opname, beoordeling en facturering als telefoongesprekken. Filter op direction om een dashboard alleen voor widgets te bouwen.

Volgende stappen#