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

# Widget vocal intégrable

> 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="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="Widget ThunderPhone dans des thèmes clairs et sombres avec différentes couleurs d’accentuation" width="1200" height="800" data-path="images/widget-showcase.png" />
</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 une clé API publiable">
    Accédez à **Développeurs** dans les paramètres du dashboard et créez une clé publiable. Les clés publiables commencent par `pk_live_` et peuvent être incluses sans risque dans le code côté client.
  </Step>

  <Step title="Configurer les domaines autorisés">
    Dans les mêmes paramètres Développeurs, ajoutez les domaines où le widget sera intégré. `localhost` est toujours autorisé pour le développement. Les caractères génériques sont pris en charge (par exemple, `*.example.com`).
  </Step>

  <Step title="Créer un widget web">
    Accédez à **Widgets Web** dans le dashboard et créez un widget. Sélectionnez l’agent que vous souhaitez exposer et la clé publiable à utiliser. L’agent est déterminé automatiquement à partir de la configuration de votre clé publiable.
  </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>

***

## Démarrage rapide

Installez le package :

```bash theme={null}
npm install @thunderphone/widget
```

Ajoutez le widget à votre application :

```tsx theme={null}
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) theme={null}
  <ThunderPhoneWidget
    publishableKey="pk_live_your_publishable_key"
  />
  ```

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

Trois props supplémentaires personnalisent la session plutôt que l’apparence ; elles sont toutes transmises à la requête de session lorsqu’un appel démarre :

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

***

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