---
title: "Composant React"
description: "Intégrez le widget vocal ThunderPhone dans une application React"
---

Le composant `ThunderPhoneWidget` affiche une barre d'appel au style glassmorphique avec des commandes intégrées pour couper le son, terminer l'appel et afficher l'état de connexion. C'est le moyen le plus rapide d'ajouter une IA vocale à une application React.

## Installation

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

## Utilisation de base

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}
```

<Warning>
  Vous **devez** importer le fichier CSS pour que le widget s'affiche correctement. Sans lui, le widget ne sera pas stylisé.
</Warning>

---

## Props

Le composant accepte les props suivantes via `ThunderPhoneWidgetProps` :

| Propriété | Type | Obligatoire | Par défaut | Description |
|------|------|----------|---------|-------------|
| `publishableKey` | `string` | Oui | -- | Clé API publiable (`pk_live_...`) depuis **Web Widgets** dans le tableau de bord. L'agent est résolu automatiquement à partir de la configuration du widget associée à la clé. |
| `theme` | `'light' \| 'dark'` | Non | `'light'` | Jeu de couleurs. Applique la classe `tp--light` ou `tp--dark` à la racine du widget. |
| `primaryColor` | `string` | Non | `'#000000'` (clair) / `'#ffffff'` (foncé) | Chaîne de couleur CSS utilisée comme couleur d'accentuation (bouton d'appel, forme d'onde, indicateurs actifs). |
| `title` | `string` | Non | `'Voice assistant'` | Texte affiché dans la barre du widget. |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Non | `'bottom-right'` | Position fixe du widget dans la fenêtre d'affichage. |
| `apiBase` | `string` | Non | `'https://api.thunderphone.com/v1'` | Remplacement de l'URL de base de l'API. |
| `language` | `string` | Non | -- | Remplacement de la langue par session -- un code de langue ou des paramètres régionaux tels que `en`, `es` ou `fr-FR`. Lorsqu'elle n'est pas définie, la langue configurée de l'agent s'applique. Nécessite `language` dans les [remplacements du navigateur](/fr/guides/embed-web-widget) de la clé. |
| `voice` | `string` | Non | -- | Remplacement de la voix par session -- un nom de voix tel que `maria`. Lorsqu'elle n'est pas définie, la voix configurée de l'agent s'applique. Nécessite `voice` dans les [remplacements du navigateur](/fr/guides/embed-web-widget) de la clé. |
| `context` | `string` | Non | -- | Contexte factuel de la page ou du site par session transmis à l'agent (par exemple, les détails de la page consultée par le visiteur). Tronqué côté serveur à 12 000 caractères. Nécessite `context` dans les [remplacements du navigateur](/fr/guides/embed-web-widget) de la clé. |
| `onConnect` | `() => void` | Non | -- | Appelé lorsque la session vocale se connecte avec succès. |
| `onDisconnect` | `() => void` | Non | -- | Appelé lorsque la session se termine. |
| `onError` | `(error) => void` | Non | -- | Appelé en cas d'erreur. L'objet `error` contient les champs `error` (code) et `message`. |
| `className` | `string` | Non | -- | Nom de classe CSS supplémentaire appliqué au conteneur du widget. |
| `ringtone` | `boolean \| string` | Non | `false` | Joue une sonnerie pendant la connexion. `true` pour la sonnerie par défaut, ou une chaîne d'URL pour un audio personnalisé. |

---

## Exemples

### Thème sombre avec couleur personnalisée

```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"
      title="Talk to our AI"
    />
  )
}
```

### Position personnalisée

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

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}
```

### Langue, voix et contexte par session

Les props `language`, `voice` et `context` sont transmises à la requête de session (`POST /widget/session`) au démarrage d’un appel, remplaçant les valeurs par défaut configurées de l’agent pour cette session. Activez chaque prop utilisée dans **Remplacements du navigateur** pour le widget dans le tableau de bord (ou dans `allowed_overrides` de la clé). Les nouveaux widgets n’en acceptent aucune, et une requête de session qui en inclut une désactivée échoue avec `400 override_not_allowed` ; consultez [Remplacements du navigateur](/fr/guides/embed-web-widget).

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

function PricingPageWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      language="es"
      voice="maria"
      context="Page: Pricing. Plans: Starter $29/mo, Pro $99/mo. Annual billing saves 20%."
    />
  )
}
```

Utilisez `context` pour fournir à l’agent des informations factuelles sur la page consultée par le visiteur : détails du produit, tarifs ou FAQ propres à la page. L’agent le traite comme du contenu de page, et non comme des instructions. Il est tronqué côté serveur à 12 000 caractères.

### Avec des rappels d’événements

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

function SupportWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      onConnect={() => {
        console.log('Voice session connected')
        analytics.track('widget_call_started')
      }}
      onDisconnect={() => {
        console.log('Voice session ended')
        analytics.track('widget_call_ended')
      }}
      onError={(error) => {
        console.error(`Widget error: ${error.error} - ${error.message}`)
      }}
    />
  )
}
```

### Avec un style personnalisé

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

function BrandedWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      primaryColor="#4a90d9"
      className="my-custom-widget"
    />
  )
}
```

```css
.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}
```

Consultez le [guide de style](/fr/widget/styling) pour voir toutes les classes CSS et propriétés personnalisées disponibles.

### Avec sonnerie

Jouez un son de téléphone qui sonne pendant l’établissement de la connexion :

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

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}
```

Utilisez une sonnerie personnalisée en transmettant l’URL d’un fichier audio :

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>
```

La sonnerie se répète tant que le widget est dans l’état `connecting` et s’estompe progressivement lorsque l’agent se connecte.

### Avec une base API personnalisée

<Tip>
  Vous devez définir `apiBase` uniquement si vous utilisez un point de terminaison d’API auto-hébergé ou proxy. La valeur par défaut pointe vers `https://api.thunderphone.com/v1`.
</Tip>

```tsx
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>
```

---

## Gestion des erreurs

Lorsque le rappel `onError` est déclenché, il reçoit un objet d’erreur comportant deux champs :

| Champ | Type | Description |
|-------|------|-------------|
| `error` | `string` | Code d’erreur lisible par machine |
| `message` | `string` | Description d’erreur lisible par un humain |

Les codes d’erreur courants incluent un domaine non autorisé, un agent introuvable et une clé API non valide.

---

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Hook headless" icon="code" href="/fr/widget/headless-hook">
    Besoin d’un contrôle total sur l’interface utilisateur ? Utilisez plutôt le hook `useThunderPhone`.
  </Card>
  <Card title="Style" icon="palette" href="/fr/widget/styling">
    Personnalisez les couleurs, les tailles et la mise en page avec des propriétés CSS personnalisées.
  </Card>
</CardGroup>