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

npm install @thunderphone/widget

Grundlegende Verwendung

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'
 
function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

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

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

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:

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

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

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

.my-custom-widget .tp-button--end {
  background-color: #e74c3c;
}

Eine Übersicht aller verfügbaren CSS-Klassen und benutzerdefinierten Eigenschaften finden Sie im Styling-Leitfaden.

Mit Klingelton

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

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:

<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

<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

Headless Hook

Benötigen Sie vollständige Kontrolle über die Benutzeroberfläche? Verwenden Sie stattdessen den Hook useThunderPhone.

Styling

Passen Sie Farben, Größen und Layout mit benutzerdefinierten CSS-Eigenschaften an.