Skip to main content
Le widget web offre aux visiteurs de votre site une conversation en un clic avec un agent IA à l’aide du microphone du navigateur. Il s’agit d’un SDK JavaScript / React distinct avec sa propre référence SDK — ce guide se concentre sur la configuration côté ThunderPhone nécessaire au widget.
Vous pouvez tout faire sans cURL : la page Web Widgets du tableau de bord (/dashboard/web-widgets) crée le widget, définit son mode et son agent, gère les domaines autorisés et vous fournit l’extrait d’intégration.

​
Prérequis

1

Créer un agent

L’agent dont le prompt et la voix exécuteront la session du widget. Définissez widget_enabled: true (valeur par défaut).
2

Choisir le mode de routage

  • mode="agent" — un agent statique par clé. Le plus simple.
  • mode="webhook" — votre serveur choisit l’agent pour chaque visiteur via un webhook web.incoming. Utilisez ce mode pour les utilisateurs connectés, les tests A/B ou le routage par page.
3

Lister les domaines autorisés

Les clés publiables sont verrouillées par origine. Vous devez indiquer chaque nom d’hôte qui intégrera le widget. localhost / 127.0.0.1 sont toujours autorisés pendant le développement local.

​
Créer une clé publiable

La réponse inclut une key commençant par pk_live_.... Les clés publiables sont publiques par conception — vous pouvez les inclure sans risque dans votre bundle front-end. Consultez la référence des clés publiables pour tous les champs.
allowed_domains doit contenir au moins une entrée. *.example.com correspond aux sous-domaines (par exemple, api.example.com), mais pas au domaine nu. Les caractères génériques seuls comme * ou *.* sont refusés.

​
Ajouter le widget à votre site

Trois options d’intégration sont présentées dans la documentation du SDK du widget :

Composant React

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

Hook sans interface

useThunderPhone() pour des interfaces personnalisées.

Balise script CDN

ThunderPhone.mount({...}) pour les sites sans bundler.
Les trois acceptent la même publishableKey et affichent le bouton du micro ainsi que l’élément audio pendant l’appel. Le context du widget est tronqué à 12 000 caractères (environ 3 400 tokens de texte anglais courant) et compte dans le supplément lié à la taille du prompt.

​
Webhooks en mode widget

Lorsque mode="webhook", ThunderPhone appelle votre webhook_url au début de chaque session avec une charge utile web.incoming. Renvoyez la configuration d’agent que vous souhaitez exécuter pour ce visiteur — elle suit le même schéma de réponse que les appels téléphoniques :
Vous pouvez intégrer au prompt le contexte de votre propre session (le client qui navigue, la page qu’il consulte) et changer d’agent selon le déploiement.

​
Observer les sessions

Les sessions du widget apparaissent dans GET /v1/calls avec direction="widget" — avec la même transcription, le même enregistrement, la même évaluation et la même facturation que les appels téléphoniques. Filtrez par direction pour créer un tableau de bord dédié au widget.

​
Étapes suivantes

Référence du SDK Widget

Détails de l’intégration React / hook / CDN.

Configuration dynamique par appel

Implémentez le flux mode="webhook" de bout en bout.

Référence des clés publiables

Tous les champs de la ressource de clé.

API des sessions micro

Ignorez le widget ; pilotez LiveKit directement pour des interfaces utilisateur personnalisées.