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

# React-component

> Sluit de ThunderPhone-spraakwidget in een React-applicatie in

De component `ThunderPhoneWidget` rendert een glasmorfische oproepbalk met ingebouwde bedieningselementen voor dempen, het beëindigen van de oproep en het weergeven van de verbindingsstatus. Dit is de snelste manier om spraak-AI aan een React-app toe te voegen.

## Installatie

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

## Basisgebruik

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

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

<Warning>
  Je **moet** het CSS-bestand importeren om de widget correct te renderen. Zonder dit bestand heeft de widget geen opmaak.
</Warning>

***

## Props

De component accepteert de volgende props via `ThunderPhoneWidgetProps`:

| Prop             | Type                                                           | Vereist | Standaard                                  | Beschrijving                                                                                                                                                                          |
| ---------------- | -------------------------------------------------------------- | ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Ja      | --                                         | Publiceerbare API-sleutel (`pk_live_...`) uit de Ontwikkelaarsinstellingen. De agent wordt automatisch bepaald op basis van de widgetconfiguratie van de sleutel.                     |
| `theme`          | `'light' \| 'dark'`                                            | Nee     | `'light'`                                  | Kleurenschema. Past de klasse `tp--light` of `tp--dark` toe op de hoofdcontainer van de widget.                                                                                       |
| `primaryColor`   | `string`                                                       | Nee     | `'#000000'` (licht) / `'#ffffff'` (donker) | CSS-kleurtekenreeks die wordt gebruikt als accentkleur (oproepknop, golfvorm, actieve indicatoren).                                                                                   |
| `title`          | `string`                                                       | Nee     | `'Voice assistant'`                        | Tekst die wordt weergegeven in de widgetbalk.                                                                                                                                         |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nee     | `'bottom-right'`                           | Vaste viewportpositie voor de widget.                                                                                                                                                 |
| `apiBase`        | `string`                                                       | Nee     | `'https://api.thunderphone.com/v1'`        | Overschrijving van de basis-URL van de API.                                                                                                                                           |
| `language`       | `string`                                                       | Nee     | --                                         | Taaloverschrijving per sessie -- een taalcode of landinstelling zoals `en`, `es` of `fr-FR`. Wanneer deze niet is ingesteld, wordt de geconfigureerde taal van de agent gebruikt.     |
| `voice`          | `string`                                                       | Nee     | --                                         | Spraakoverschrijving per sessie -- een spraaknaam zoals `maria`. Wanneer deze niet is ingesteld, wordt de geconfigureerde stem van de agent gebruikt.                                 |
| `context`        | `string`                                                       | Nee     | --                                         | Feitelijke pagina- of sitecontext per sessie die aan de agent wordt doorgegeven (bijvoorbeeld details van de pagina die de bezoeker bekijkt). Server-side afgekapt tot 12.000 tekens. |
| `onConnect`      | `() => void`                                                   | Nee     | --                                         | Aangeroepen wanneer de spraaksessie succesvol verbinding maakt.                                                                                                                       |
| `onDisconnect`   | `() => void`                                                   | Nee     | --                                         | Aangeroepen wanneer de sessie eindigt.                                                                                                                                                |
| `onError`        | `(error) => void`                                              | Nee     | --                                         | Aangeroepen bij fouten. Het object `error` heeft de velden `error` (code) en `message`.                                                                                               |
| `className`      | `string`                                                       | Nee     | --                                         | Extra CSS-klassennaam die wordt toegepast op de widgetcontainer.                                                                                                                      |
| `ringtone`       | `boolean \| string`                                            | Nee     | `false`                                    | Speel een beltoon af tijdens het verbinden. `true` voor de standaardbeltoon, of een URL-tekenreeks voor aangepaste audio.                                                             |

***

## Voorbeelden

### Donker thema met aangepaste kleur

```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"
    />
  )
}
```

### Aangepaste positie

```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"
    />
  )
}
```

### Taal, stem en context per sessie

De props `language`, `voice` en `context` worden bij het starten van een oproep doorgestuurd naar het sessieverzoek (`POST /widget/session`) en overschrijven voor die sessie de geconfigureerde standaardwaarden van de agent:

```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%."
    />
  )
}
```

Gebruik `context` om de agent feitelijke kennis te geven over de pagina waarop de bezoeker zich bevindt: productdetails, prijzen of veelgestelde vragen die specifiek zijn voor de pagina. Deze wordt aan serverzijde afgekapt op 12.000 tekens.

### Met eventcallbacks

```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}`)
      }}
    />
  )
}
```

### Met aangepaste styling

```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;
}
```

Zie de [stylinggids](/nl/widget/styling) voor alle beschikbare CSS-klassen en aangepaste eigenschappen.

### Met beltoon

Speel een telefoongerinkel af terwijl de verbinding tot stand wordt gebracht:

```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}
    />
  )
}
```

Gebruik een aangepaste beltoon door een URL van een audiobestand door te geven:

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

De beltoon wordt herhaald terwijl de widget de status `connecting` heeft en vervaagt soepel wanneer de agent verbinding maakt.

### Met aangepaste API-basis

<Tip>
  Je hoeft `apiBase` alleen in te stellen als je een zelfgehost of via een proxy beschikbaar API-eindpunt gebruikt. De standaardwaarde verwijst naar `https://api.thunderphone.com/v1`.
</Tip>

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

***

## Foutafhandeling

Wanneer de callback `onError` wordt aangeroepen, ontvangt deze een foutobject met twee velden:

| Veld      | Type     | Beschrijving              |
| --------- | -------- | ------------------------- |
| `error`   | `string` | Machineleesbare foutcode  |
| `message` | `string` | Leesbare foutbeschrijving |

Veelvoorkomende foutcodes zijn onder meer domein niet toegestaan, agent niet gevonden en ongeldige API-sleutel.

***

## Volgende stappen

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/nl/widget/headless-hook">
    Wil je volledige controle over de UI? Gebruik dan de `useThunderPhone`-hook.
  </Card>

  <Card title="Styling" icon="palette" href="/nl/widget/styling">
    Pas kleuren, formaten en lay-out aan met aangepaste CSS-eigenschappen.
  </Card>
</CardGroup>