Skip to main content
De webwidget biedt je sitebezoekers een klik-om-te-praten-gesprek met een AI-agent via de microfoon van de browser. Het is een afzonderlijke JavaScript- / React-SDK met een eigen SDK-referentie — deze handleiding richt zich op de configuratie aan de ThunderPhone-zijde die de widget nodig heeft.
Je kunt dit allemaal zonder cURL doen: de dashboardpagina Webwidgets (/dashboard/web-widgets) maakt de widget, stelt de modus en agent in, beheert toegestane domeinen en geeft je het embedfragment.

​
Vereisten

1

Maak een agent

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

Kies 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

Maak een lijst van de toegestane domeinen

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

​
Maak een publiceerbare sleutel

Het antwoord bevat een key die begint met pk_live_.... Publiceerbare sleutels zijn bewust openbaar — je kunt ze veilig in je front-endbundle opnemen. Zie de referentie voor publiceerbare sleutels voor alle velden.
allowed_domains moet ten minste één invoer bevatten. *.example.com komt overeen met subdomeinen (bijv. api.example.com), maar niet met het hoofddomein. Losse wildcards zoals * of *.* worden geweigerd.

​
Plaats de widget op je site

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

React-component

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Headless hook

useThunderPhone() voor aangepaste UI’s.

CDN-scripttag

ThunderPhone.mount({...}) voor sites zonder bundler.
Alle drie accepteren dezelfde publishableKey en renderen de microfoonknop plus het audio-element tijdens het gesprek. De context van de widget wordt afgekapt op 12.000 tekens (ongeveer 3.400 tokens aan typische Engelse tekst) en telt mee voor de toeslag voor promptgrootte.

​
Webhooks in widgetmodus

Wanneer mode="webhook" is ingesteld, roept ThunderPhone je webhook_url aan bij elke sessiestart met een web.incoming-payload. Retourneer de agentconfiguratie die je voor die bezoeker wilt uitvoeren — deze volgt hetzelfde antwoordschema als telefoongesprekken:
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 te bouwen dat alleen widgets toont.

​
Volgende stappen

Widget SDK-referentie

Integratiedetails voor React / hooks / CDN.

Dynamische configuratie per oproep

Implementeer de mode="webhook"-flow end-to-end.

Referentie voor publiceerbare sleutels

Elk veld in de sleutelresource.

Mic-sessies-API

Sla de widget over; stuur LiveKit rechtstreeks aan voor aangepaste UI’s.