---
title: "Widget vocal intégrable"
description: "Ajoutez un agent vocal IA à n’importe quel site web avec quelques lignes de code"
---

Le widget vocal intégrable ThunderPhone permet aux visiteurs de votre site web de parler à un agent IA directement depuis le navigateur. Aucun appel téléphonique requis : les utilisateurs cliquent sur un bouton et démarrent une conversation vocale en temps réel propulsée par ThunderPhone.

Le widget s’affiche sous la forme d’une barre avec effet glassmorphism qui s’adapte aux thèmes clairs et sombres, avec des couleurs d’accentuation et un positionnement personnalisables. Il est distribué sous forme de package npm `@thunderphone/widget` et est également disponible via CDN pour les environnements sans bundler.

<Frame>
  <img src="/images/widget-showcase.png" alt="Widget ThunderPhone dans des thèmes clairs et sombres avec différentes couleurs d’accentuation" />
</Frame>

## Prérequis

Avant d’intégrer le widget, effectuez ces trois étapes dans le [Dashboard ThunderPhone](https://app.thunderphone.com) :

<Steps>
<Step title="Créer un widget web">
  Accédez à **Widgets web** dans le tableau de bord et créez un widget. Sélectionnez l’agent que vous souhaitez rendre accessible. Chaque widget possède sa propre clé publiable (`pk_live_...`), que vous pouvez inclure sans risque dans le code côté client ; l’agent est déterminé à partir de la clé.
</Step>

<Step title="Configurer les domaines autorisés">
  Dans ce même widget, ajoutez les domaines où il sera intégré. Les caractères génériques sont pris en charge (par exemple, `*.example.com`). Cette liste empêche le widget de fonctionner lorsqu’une personne copie votre clé sur un autre site ; il ne s’agit pas d’une authentification, car un script exécuté hors d’un navigateur peut envoyer n’importe quel en-tête `Origin`. `localhost` n’est pas autorisé automatiquement en production : ajoutez-le à la liste pour effectuer des tests locaux avec l’API de production.
</Step>

<Step title="Choisir les surcharges du navigateur">
  Si votre page définit `language`, `voice` ou `context`, activez chacune de ces options dans **Surcharges du navigateur**. Les nouveaux widgets n’en acceptent aucune, et une requête de session contenant un paramètre désactivé échoue avec `400 override_not_allowed`. Consultez [Surcharges du navigateur](/fr/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Les clés publiables (`pk_live_...`) ne sont **pas** les mêmes que vos jetons API secrets. Les clés publiables sont conçues pour une utilisation côté client et sont limitées aux sessions de widget sur vos domaines autorisés. N’utilisez jamais votre jeton API secret dans du code côté client.
</Warning>

<Note>
  Les sessions de widget se terminent après 30 minutes par défaut, ou plus tôt si la durée maximale d’appel de l’agent est plus courte. Modifiez la limite pour chaque clé avec `max_call_duration_seconds` sur la [clé publiable](/api-reference/publishable-keys) (jusqu’à 6 heures), ou définissez-la sur `null` pour utiliser la limite propre à l’agent.
</Note>

---

## Démarrage rapide

Installez le package :

```bash
npm install @thunderphone/widget
```

Ajoutez le widget à votre application :

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

C’est tout. Vos utilisateurs verront une barre d’appel avec effet glassmorphism qui les connecte à votre agent IA en un seul clic.

---

## Personnalisation

Le widget possède quatre props d’apparence :

| Prop | Valeur par défaut | Description |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` pour un verre blanc, `'dark'` pour un verre sombre |
| `primaryColor` | `'#000000'` (clair) / `'#ffffff'` (sombre) | Couleur d’accentuation du bouton de démarrage, de la forme d’onde et de l’indicateur de connexion |
| `title` | `'Voice assistant'` | Texte affiché dans le widget |
| `position` | `'bottom-right'` | Coin de la fenêtre d’affichage : `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

Trois autres props personnalisent la session plutôt que l’apparence — elles sont toutes transmises à la requête de session lorsqu’un appel démarre. Chacune fonctionne uniquement lorsque la clé publiable du widget l’autorise dans **Remplacements du navigateur** ; sinon, la requête de session échoue avec `400 override_not_allowed` :

| Prop | Description |
|------|-------------|
| `language` | Remplacement de la langue par session : un code ou une locale tel que `en`, `es` ou `fr-FR` |
| `voice` | Remplacement de la voix par session : un nom de voix tel que `maria` |
| `context` | Contexte factuel de la page ou du site transmis à l’agent (tronqué côté serveur à 12 000 caractères) |

Consultez la [référence du composant React](/fr/widget/react) pour le tableau complet des props.

Pour une interface utilisateur entièrement personnalisée, utilisez le [hook headless](/fr/widget/headless-hook) pour gérer la session vocale pendant que vous créez votre propre interface. Le hook expose les niveaux audio en temps réel pour créer des visualisations réactives à l’audio.

Chaque conversation du widget est un appel. Elle est comptabilisée dans la [limite d’appels simultanés](/api-reference/introduction#call-limits) de votre organisation (20 appels en cours par défaut, partagés avec les appels téléphoniques et les autres appels) ainsi que dans une limite de 25 sessions actives pour le widget (ou votre limite d’appels simultanés, si elle est supérieure). Lorsqu’une de ces limites est atteinte, aucune nouvelle conversation ne peut démarrer tant qu’un appel ne s’est pas terminé.

---

## Options d’intégration

Choisissez la méthode d’intégration adaptée à votre stack :

<CardGroup cols={3}>
  <Card title="Composant React" icon="react" href="/fr/widget/react">
    Composant d’interface préconfiguré avec commandes d’appel et affichage de l’état intégrés. Importez-le, passez les props, c’est prêt.
  </Card>
  <Card title="Hook headless" icon="code" href="/fr/widget/headless-hook">
    Contrôle total de l’interface. Le hook `useThunderPhone` gère la session vocale pendant que vous créez votre propre interface.
  </Card>
  <Card title="CDN / balise de script" icon="globe" href="/fr/widget/cdn-script-tag">
    Aucun bundler requis. Chargez le widget via une balise de script pour les sites statiques, WordPress et les autres environnements non-React.
  </Card>
</CardGroup>

---

## Style

Le widget inclut des thèmes clair et sombre intégrés, contrôlés par la prop `theme`, ainsi qu’une couleur d’accent contrôlée par la prop `primaryColor`. Pour une personnalisation plus poussée, vous pouvez remplacer les propriétés et classes CSS personnalisées. Consultez le [guide de style](/fr/widget/styling) pour plus de détails.

<Note>
  Besoin d’aide ? Contactez-nous à l’adresse [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>