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

> Betten Sie das ThunderPhone-Sprach-Widget in eine React-Anwendung ein

Die Komponente `ThunderPhoneWidget` rendert eine glasartige Anrufleiste mit integrierten Steuerelementen zum Stummschalten, Beenden des Anrufs und Anzeigen des Verbindungsstatus. Sie ist der schnellste Weg, Sprach-KI zu einer React-App hinzuzufügen.

## Installation

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

## Grundlegende Verwendung

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

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

<Warning>
  Sie **müssen** die CSS-Datei importieren, damit das Widget korrekt gerendert wird. Ohne sie hat das Widget kein Styling.
</Warning>

***

## Props

Die Komponente akzeptiert die folgenden Props über `ThunderPhoneWidgetProps`:

| Prop             | Typ                                                            | Erforderlich | Standard                                  | Beschreibung                                                                                                                                                                            |
| ---------------- | -------------------------------------------------------------- | ------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publishableKey` | `string`                                                       | Ja           | --                                        | Veröffentlichbarer API-Schlüssel (`pk_live_...`) aus den Entwicklereinstellungen. Der Agent wird automatisch anhand der Widget-Konfiguration des Schlüssels aufgelöst.                  |
| `theme`          | `'light' \| 'dark'`                                            | Nein         | `'light'`                                 | Farbschema. Wendet die Klasse `tp--light` oder `tp--dark` auf das Stammelement des Widgets an.                                                                                          |
| `primaryColor`   | `string`                                                       | Nein         | `'#000000'` (hell) / `'#ffffff'` (dunkel) | CSS-Farbzeichenfolge, die als Akzentfarbe verwendet wird (Anrufschaltfläche, Wellenform, aktive Indikatoren).                                                                           |
| `title`          | `string`                                                       | Nein         | `'Voice assistant'`                       | Text, der in der Widget-Leiste angezeigt wird.                                                                                                                                          |
| `position`       | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | Nein         | `'bottom-right'`                          | Feste Viewport-Position für das Widget.                                                                                                                                                 |
| `apiBase`        | `string`                                                       | Nein         | `'https://api.thunderphone.com/v1'`       | Überschreibung der API-Basis-URL.                                                                                                                                                       |
| `language`       | `string`                                                       | Nein         | --                                        | Sprachüberschreibung pro Sitzung – ein Sprachcode oder Gebietsschema wie `en`, `es` oder `fr-FR`. Wenn nicht festgelegt, wird die konfigurierte Sprache des Agenten verwendet.          |
| `voice`          | `string`                                                       | Nein         | --                                        | Stimmenüberschreibung pro Sitzung – ein Stimmenname wie `maria`. Wenn nicht festgelegt, wird die konfigurierte Stimme des Agenten verwendet.                                            |
| `context`        | `string`                                                       | Nein         | --                                        | Faktischer Seiten- oder Website-Kontext pro Sitzung, der an den Agenten übergeben wird (z. B. Details der Seite, die der Besucher betrachtet). Serverseitig auf 12.000 Zeichen gekürzt. |
| `onConnect`      | `() => void`                                                   | Nein         | --                                        | Wird aufgerufen, wenn die Sprachsitzung erfolgreich verbunden wird.                                                                                                                     |
| `onDisconnect`   | `() => void`                                                   | Nein         | --                                        | Wird aufgerufen, wenn die Sitzung endet.                                                                                                                                                |
| `onError`        | `(error) => void`                                              | Nein         | --                                        | Wird bei Fehlern aufgerufen. Das Objekt `error` verfügt über die Felder `error` (Code) und `message`.                                                                                   |
| `className`      | `string`                                                       | Nein         | --                                        | Zusätzlicher CSS-Klassenname, der auf den Widget-Container angewendet wird.                                                                                                             |
| `ringtone`       | `boolean \| string`                                            | Nein         | `false`                                   | Gibt während des Verbindungsaufbaus einen Klingelton wieder. `true` für den Standardklingelton oder eine URL-Zeichenfolge für benutzerdefiniertes Audio.                                |

***

## Beispiele

### Dunkles Design mit benutzerdefinierter Farbe

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

### Benutzerdefinierte Position

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

### Sprache, Stimme und Kontext pro Sitzung

Die Props `language`, `voice` und `context` werden beim Start eines Anrufs an die Sitzungsanfrage (`POST /widget/session`) weitergeleitet und überschreiben für diese Sitzung die konfigurierten Standardwerte des Agenten:

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

Verwenden Sie `context`, um dem Agenten Faktenwissen über die Seite zu geben, auf der sich der Besucher befindet – Produktdetails, Preise oder seitenspezifische FAQs. Der Wert wird serverseitig auf 12.000 Zeichen gekürzt.

### Mit Ereignis-Callbacks

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

### Mit benutzerdefiniertem 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;
}
```

Eine Übersicht aller verfügbaren CSS-Klassen und benutzerdefinierten Eigenschaften finden Sie im [Styling-Leitfaden](/de/widget/styling).

### Mit Klingelton

Spielen Sie einen Telefonklingelton ab, während die Verbindung hergestellt wird:

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

Verwenden Sie einen benutzerdefinierten Klingelton, indem Sie eine URL zu einer Audiodatei übergeben:

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

Der Klingelton wird wiederholt, während sich das Widget im Status `connecting` befindet, und blendet sanft aus, wenn der Agent verbunden wird.

### Mit benutzerdefinierter API-Basis

<Tip>
  Sie müssen `apiBase` nur festlegen, wenn Sie einen selbst gehosteten oder Proxy-API-Endpunkt verwenden. Standardmäßig wird `https://api.thunderphone.com/v1` verwendet.
</Tip>

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

***

## Fehlerbehandlung

Wenn der Callback `onError` ausgelöst wird, erhält er ein Fehlerobjekt mit zwei Feldern:

| Feld      | Typ      | Beschreibung                       |
| --------- | -------- | ---------------------------------- |
| `error`   | `string` | Maschinenlesbarer Fehlercode       |
| `message` | `string` | Menschenlesbare Fehlerbeschreibung |

Häufige Fehlercodes umfassen nicht zulässige Domains, nicht gefundene Agenten und ungültige API-Schlüssel.

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Headless Hook" icon="code" href="/de/widget/headless-hook">
    Benötigen Sie vollständige Kontrolle über die Benutzeroberfläche? Verwenden Sie stattdessen den Hook `useThunderPhone`.
  </Card>

  <Card title="Styling" icon="palette" href="/de/widget/styling">
    Passen Sie Farben, Größen und Layout mit benutzerdefinierten CSS-Eigenschaften an.
  </Card>
</CardGroup>