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 standaardinstelling).

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. Vermeld de toegestane domeinen

   Geef elke hostnaam op die de widget insluit. Browsers sturen de oorsprong van de pagina mee met elk sessieverzoek, zodat de lijst voorkomt dat je sleutel werkt wanneer iemand deze naar een andere site kopieert. Dit is geen authenticatie: een script buiten een browser kan elke Origin- header versturen. localhost is in productie niet automatisch toegestaan; voeg localhost aan de lijst toe om lokaal te testen met de productie-API.

4. Kies de browseroverschrijvingen

   Bepaal welke sessie-instellingen je pagina mag versturen. Nieuwe sleutels accepteren geen; zie Browseroverschrijvingen.

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

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.

Browseroverschrijvingen#

De widget kan vier instellingen per sessie vanaf de pagina verzenden:

Je publishable key is openbaar, dus iedereen die deze heeft kan deze instellingen verzenden, ook vanuit een script dat je domein nabootst. Ze staan daarom allemaal uit totdat je ze voor de key toestaat: vink ze aan onder Browser overrides wanneer je de widget in het dashboard maakt of bewerkt, of stel allowed_overrides in via de API voor publishable keys. Sta alleen toe wat je pagina daadwerkelijk verzendt.

Een sessieverzoek met een instelling die de sleutel niet toestaat, mislukt met 400 en vermeldt deze:

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

De controle geldt in beide modi. In webhookmodus wordt een toegestane instelling ook doorgestuurd naar je web.incoming-webhook (context komt aan als website_context). Sleutels die zijn gemaakt voordat deze instelling bestond, staan alle vier toe, zodat bestaande insluitingen blijven werken; schakel uit wat je niet gebruikt.

Widget-context wordt afgekapt op 12.000 tekens (ongeveer 3.400 tokens van typische Engelse tekst) en telt mee voor de toeslag voor promptgrootte. De agent krijgt de instructie dit als pagina-inhoud te behandelen, niet als instructies.

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#