Intégrer le widget web

Ajoutez un agent vocal à votre site marketing ou d’assistance avec une seule balise de script — les visiteurs lui parlent directement depuis le navigateur, sans numéro de téléphone.

Le widget web offre aux visiteurs de votre site une conversation en un clic pour parler avec un agent IA, en utilisant le microphone du navigateur. Il s’agit d’un SDK JavaScript / React distinct avec sa propre référence du SDK — ce guide se concentre sur la configuration côté ThunderPhone requise par le widget.

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. Répertorier les domaines autorisés

   Indiquez chaque nom d’hôte qui intégrera le widget. Les navigateurs envoient l’origine de la page avec chaque requête de session ; cette liste empêche donc votre clé de fonctionner si quelqu’un la copie sur un autre site. Il ne s’agit pas d’une authentification : un script hors d’un navigateur peut envoyer n’importe quel en-tête Origin. localhost n’est pas automatiquement autorisé en production ; pour effectuer des tests locaux avec l’API de production, ajoutez localhost à la liste.

4. Choisir les surcharges du navigateur

   Déterminez quels paramètres de session votre page peut envoyer. Les nouvelles clés n’en acceptent aucun ; consultez Surcharges du navigateur.

Créer une clé publiable#

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

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.

Ajoutez le widget à votre site#

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

Les trois acceptent la même publishableKey et affichent le bouton de microphone ainsi que l’élément audio en appel.

Remplacements du navigateur#

Le widget peut envoyer quatre paramètres par session depuis la page :

Votre clé publiable est publique. Toute personne qui la possède peut donc envoyer ces paramètres, y compris depuis un script qui usurpe votre domaine. Ils sont tous désactivés tant que vous ne les autorisez pas sur la clé : cochez-les dans Remplacements du navigateur lorsque vous créez ou modifiez le widget dans le tableau de bord, ou définissez allowed_overrides via l’ API des clés publiables. N’autorisez que les paramètres effectivement envoyés par votre page.

Une requête de session contenant un paramètre que la clé n’autorise pas échoue avec 400 et le nomme :

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

La vérification s’applique dans les deux modes. En mode webhook, un paramètre autorisé est également transmis à votre webhook web.incoming (context arrive sous le nom website_context). Les clés créées avant l’existence de ce paramètre autorisent les quatre, afin que les intégrations existantes continuent de fonctionner ; désactivez ceux que vous n’utilisez pas.

Le context du widget est tronqué à 12 000 caractères (environ 3 400 tokens de texte anglais standard) et compte dans le supplément lié à la taille du prompt. L’agent est invité à le traiter comme du contenu de page, et non comme des instructions.

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 de l’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 :

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

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" — même transcription, enregistrement, évaluation et facturation que les appels téléphoniques. Filtrez par direction pour créer un tableau de bord dédié au widget.

Étapes suivantes#