> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Intégrer le widget web

> Ajoutez un agent vocal à votre site marketing ou d’assistance, sans numéro de téléphone requis.

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](/fr/widget/overview) — ce guide se concentre sur la configuration côté ThunderPhone nécessaire au widget.

<Note>
  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.
</Note>

## Prérequis

<Steps>
  <Step title="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).
  </Step>

  <Step title="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`](/fr/webhooks/call-incoming). Utilisez ce mode pour
      les utilisateurs connectés, les tests A/B ou le routage par page.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Créer une clé publiable

<CodeGroup>
  ```bash Static agent theme={null}
  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"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  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"]
    }'
  ```
</CodeGroup>

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](/api-reference/publishable-keys) pour
tous les champs.

<Warning>
  `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.
</Warning>

## Ajouter le widget à votre site

Trois options d’intégration sont présentées dans la
[documentation du SDK du widget](/fr/widget/overview) :

<CardGroup cols={3}>
  <Card title="Composant React" icon="react" href="/fr/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Hook sans interface" icon="circle-nodes" href="/fr/widget/headless-hook">
    `useThunderPhone()` pour des interfaces personnalisées.
  </Card>

  <Card title="Balise script CDN" icon="code" href="/fr/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` pour les sites sans bundler.
  </Card>
</CardGroup>

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](/fr/guides/billing-and-topups).

## 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](/fr/webhooks/call-incoming) que les appels
téléphoniques :

```json theme={null}
{
  "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`](/api-reference/calls#list-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

<CardGroup cols={2}>
  <Card title="Référence du SDK Widget" icon="window-maximize" href="/fr/widget/overview">
    Détails de l’intégration React / hook / CDN.
  </Card>

  <Card title="Configuration dynamique par appel" icon="bolt" href="/fr/guides/dynamic-call-config">
    Implémentez le flux `mode="webhook"` de bout en bout.
  </Card>

  <Card title="Référence des clés publiables" icon="key" href="/api-reference/publishable-keys">
    Tous les champs de la ressource de clé.
  </Card>

  <Card title="API des sessions micro" icon="microphone" href="/api-reference/mic-sessions">
    Ignorez le widget ; pilotez LiveKit directement pour des interfaces utilisateur personnalisées.
  </Card>
</CardGroup>