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

# Einbettbares Sprach-Widget

> Fügen Sie mit wenigen Codezeilen einen Sprach-KI-Agenten zu jeder Website hinzu

Das einbettbare Sprach-Widget von ThunderPhone ermöglicht Ihren Website-Besuchern, direkt im Browser mit einem KI-Agenten zu sprechen. Kein Telefonanruf erforderlich – Nutzer klicken auf eine Schaltfläche und starten eine Echtzeit-Sprachunterhaltung mit ThunderPhone.

Das Widget wird als Leiste in Glasoptik dargestellt, die sich an helle und dunkle Designs anpasst, mit anpassbaren Akzentfarben und Positionierung. Es wird als npm-Paket `@thunderphone/widget` bereitgestellt und ist auch über CDN für Umgebungen ohne Bundler verfügbar.

<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="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</Frame>

## Voraussetzungen

Bevor Sie das Widget einbetten, führen Sie diese drei Schritte im [ThunderPhone Dashboard](https://app.thunderphone.com) aus:

<Steps>
  <Step title="Veröffentlichbaren API-Schlüssel erstellen">
    Gehen Sie in den Dashboard-Einstellungen zu **Entwickler** und erstellen Sie einen veröffentlichbaren Schlüssel. Veröffentlichbare Schlüssel beginnen mit `pk_live_` und können sicher in clientseitigem Code verwendet werden.
  </Step>

  <Step title="Zulässige Domains konfigurieren">
    Fügen Sie in denselben Entwickler-Einstellungen die Domains hinzu, auf denen das Widget eingebettet wird. `localhost` ist für die Entwicklung immer zulässig. Platzhalter werden unterstützt, z. B. `*.example.com`.
  </Step>

  <Step title="Web-Widget erstellen">
    Gehen Sie im Dashboard zu **Web-Widgets** und erstellen Sie ein Widget. Wählen Sie den Agenten aus, den Sie verfügbar machen möchten, sowie den zu verwendenden veröffentlichbaren Schlüssel. Der Agent wird automatisch anhand Ihrer Konfiguration des veröffentlichbaren Schlüssels aufgelöst.
  </Step>
</Steps>

<Warning>
  Veröffentlichbare Schlüssel (`pk_live_...`) sind **nicht** dasselbe wie Ihre geheimen API-Tokens. Veröffentlichbare Schlüssel sind für die clientseitige Nutzung vorgesehen und auf Widget-Sitzungen in Ihren zulässigen Domains beschränkt. Verwenden Sie Ihren geheimen API-Token niemals in clientseitigem Code.
</Warning>

***

## Schnellstart

Installieren Sie das Paket:

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

Fügen Sie das Widget in Ihre App ein:

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

Das ist alles. Ihre Nutzer sehen eine Anrufleiste in Glasoptik, die sie mit einem einzigen Klick mit Ihrem KI-Agenten verbindet.

***

## Anpassung

Das Widget verfügt über vier Props für das Erscheinungsbild:

| Prop           | Standard                                  | Beschreibung                                                                       |
| -------------- | ----------------------------------------- | ---------------------------------------------------------------------------------- |
| `theme`        | `'light'`                                 | `'light'` für weißes Glas, `'dark'` für dunkles Glas                               |
| `primaryColor` | `'#000000'` (hell) / `'#ffffff'` (dunkel) | Akzentfarbe für die Startschaltfläche, Wellenform und Verbindungsanzeige           |
| `title`        | `'Voice assistant'`                       | Im Widget angezeigter Text                                                         |
| `position`     | `'bottom-right'`                          | Ecke des Viewports: `'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>

Drei weitere Props passen die Sitzung statt des Erscheinungsbilds an – alle werden beim Start eines Anrufs an die Sitzungsanfrage weitergeleitet:

| Prop       | Beschreibung                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------- |
| `language` | Sprachüberschreibung pro Sitzung – ein Code oder Gebietsschema wie `en`, `es` oder `fr-FR`                           |
| `voice`    | Sprachüberschreibung pro Sitzung – ein Stimmenname wie `maria`                                                       |
| `context`  | Faktischer Seiten- oder Website-Kontext, der an den Agenten übergeben wird (serverseitig auf 12.000 Zeichen gekürzt) |

In der [React-Komponentenreferenz](/de/widget/react) finden Sie die vollständige Props-Tabelle.

Für eine vollständig angepasste Benutzeroberfläche verwenden Sie den [Headless-Hook](/de/widget/headless-hook), um die Sprachsitzung zu verwalten, während Sie Ihre eigene Oberfläche erstellen. Der Hook stellt Audiopegel in Echtzeit bereit, um audioreaktive Visualisierungen zu erstellen.

***

## Integrationsoptionen

Wählen Sie die Integrationsmethode, die zu Ihrem Stack passt:

<CardGroup cols={3}>
  <Card title="React-Komponente" icon="react" href="/de/widget/react">
    Vorgefertigte UI-Komponente mit integrierten Anrufsteuerungen und Statusanzeige. Importieren, Props übergeben, fertig.
  </Card>

  <Card title="Headless Hook" icon="code" href="/de/widget/headless-hook">
    Vollständige Kontrolle über die UI. Der Hook `useThunderPhone` verwaltet die Sprachsitzung, während Sie Ihre eigene Oberfläche erstellen.
  </Card>

  <Card title="CDN / Script-Tag" icon="globe" href="/de/widget/cdn-script-tag">
    Kein Bundler erforderlich. Laden Sie das Widget über ein Script-Tag für statische Websites, WordPress und andere Nicht-React-Umgebungen.
  </Card>
</CardGroup>

***

## Styling

Das Widget verfügt über integrierte helle und dunkle Designs, die über die Prop `theme` gesteuert werden, sowie über eine Akzentfarbe, die über die Prop `primaryColor` gesteuert wird. Für umfassendere Anpassungen können Sie CSS-Custom-Properties und Klassen überschreiben. Details finden Sie im [Styling-Leitfaden](/de/widget/styling).

<Note>
  Benötigen Sie Hilfe? Kontaktieren Sie uns unter [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>