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

# Composant React

> 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 theme={null}
npm install @thunderphone/widget
```

## Utilisation de base

```tsx theme={null}
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` :

| Prop             | Type                                                           | Obligatoire | Par défaut                                | Description                                                                                                                                                                                       |
| ---------------- | -------------------------------------------------------------- | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Oui         | --                                        | Clé API publiable (`pk_live_...`) des paramètres Développeurs. L'agent est résolu automatiquement à partir de la configuration du widget de 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. |
| `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.                                                   |
| `context`        | `string`                                                       | Non         | --                                        | Contexte factuel de la page ou du site, transmis à l'agent pour chaque session (par exemple, les détails de la page consultée par le visiteur). Tronqué côté serveur à 12 000 caractères.         |
| `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` comporte 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 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"
      title="Talk to our AI"
    />
  )
}
```

### Position personnalisée

```tsx theme={null}
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, en remplaçant les valeurs par défaut configurées de l’agent pour cette session :

```tsx theme={null}
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. Son contenu est tronqué côté serveur à 12 000 caractères.

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

```tsx theme={null}
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 theme={null}
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 theme={null}
.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 theme={null}
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 theme={null}
<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 theme={null}
<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>