Developer cookbook

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 cette option 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 liées à l’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#

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

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.

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 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#