---
title: "Einbettbares Sprach-Widget"
description: "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.
## Voraussetzungen
Bevor Sie das Widget einbetten, führen Sie diese drei Schritte im [ThunderPhone Dashboard](https://app.thunderphone.com) aus:
Navigieren Sie im Dashboard zu **Web Widgets** und erstellen Sie ein Widget. Wählen Sie den Sprachagenten aus, den Sie bereitstellen möchten. Jedes Widget hat einen eigenen veröffentlichbaren Schlüssel (`pk_live_...`), der sicher in clientseitigem Code verwendet werden kann; der Sprachagent wird über den Schlüssel aufgelöst.
Fügen Sie im selben Widget die Domains hinzu, auf denen es eingebettet wird. Platzhalter werden unterstützt (z. B. `*.example.com`). Die Liste verhindert, dass das Widget funktioniert, wenn jemand Ihren Schlüssel auf eine andere Website kopiert; sie ist keine Authentifizierung, da ein Skript außerhalb eines Browsers jeden beliebigen `Origin`-Header senden kann. `localhost` ist in der Produktion nicht automatisch zulässig: Fügen Sie es zur Liste hinzu, um lokal gegen die Produktions-API zu testen.
Wenn Ihre Seite `language`, `voice` oder `context` festlegt, aktivieren Sie jede Option unter **Browser overrides**. Neue Widgets akzeptieren keine, und eine Sitzungsanfrage mit einer deaktivierten Einstellung schlägt mit `400 override_not_allowed` fehl. Siehe [Browser-Überschreibungen](/de/guides/embed-web-widget).
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.
Widget-Sitzungen enden standardmäßig nach 30 Minuten oder früher, wenn die maximale Anrufdauer des Sprachagenten kürzer ist. Ändern Sie das Limit pro Schlüssel mit `max_call_duration_seconds` für den [veröffentlichbaren Schlüssel](/api-reference/publishable-keys) (bis zu 6 Stunden), oder setzen Sie es auf `null`, um das eigene Limit des Sprachagenten zu verwenden.
---
## Schnellstart
Installieren Sie das Paket:
```bash
npm install @thunderphone/widget
```
Fügen Sie das Widget in Ihre App ein:
```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
function App() {
return (
)
}
```
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'` |
```tsx Light theme (default)
```
```tsx Dark theme with custom color
```
Drei weitere Props passen die Sitzung statt des Erscheinungsbilds an -- sie werden alle beim Start eines Anrufs an die Sitzungsanfrage weitergeleitet. Jede funktioniert nur, wenn der veröffentlichbare Schlüssel des Widgets sie unter **Browser-Überschreibungen** erlaubt; andernfalls schlägt die Sitzungsanfrage mit `400 override_not_allowed` fehl:
| 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.
Jede Widget-Unterhaltung ist ein Anruf. Sie wird auf das [Limit für gleichzeitige Anrufe](/api-reference/introduction#call-limits) Ihrer Organisation angerechnet (standardmäßig 20 laufende Anrufe, geteilt mit Telefon- und anderen Anrufen) sowie auf ein Widget-Limit von 25 aktiven Sitzungen (oder Ihr Limit für gleichzeitige Anrufe, falls dieses höher ist). Bei Erreichen eines der beiden Limits kann keine neue Unterhaltung starten, bis ein Anruf endet.
---
## Integrationsoptionen
Wählen Sie die Integrationsmethode, die zu Ihrem Stack passt:
Vorgefertigte UI-Komponente mit integrierten Anrufsteuerungen und Statusanzeige. Importieren, Props übergeben, fertig.
Vollständige Kontrolle über die UI. Der Hook `useThunderPhone` verwaltet die Sprachsitzung, während Sie Ihre eigene Oberfläche erstellen.
Kein Bundler erforderlich. Laden Sie das Widget über ein Script-Tag für statische Websites, WordPress und andere Nicht-React-Umgebungen.
---
## 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).
Benötigen Sie Hilfe? Kontaktieren Sie uns unter [support@thunderphone.com](mailto:support@thunderphone.com)