React-component - ThunderPhone

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

npm install @thunderphone/widget

Basisgebruik

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

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

Je moet het CSS-bestand importeren om de widget correct te renderen. Zonder dit bestand heeft de widget geen opmaak.

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

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

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:

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

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

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

Zie de stylinggids voor alle beschikbare CSS-klassen en aangepaste eigenschappen.

Met beltoon

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

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:

<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

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.

<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

Headless Hook

Wil je volledige controle over de UI? Gebruik dan de useThunderPhone-hook.

Styling

Pas kleuren, formaten en lay-out aan met aangepaste CSS-eigenschappen.

​Installatie

​Basisgebruik

​Props

​Voorbeelden

​Donker thema met aangepaste kleur

​Aangepaste positie

​Taal, stem en context per sessie

​Met eventcallbacks

​Met aangepaste styling

​Met beltoon

​Met aangepaste API-basis

​Foutafhandeling

​Volgende stappen

Headless Hook

Styling

Installatie

Basisgebruik

Props

Voorbeelden

Donker thema met aangepaste kleur

Aangepaste positie

Taal, stem en context per sessie

Met eventcallbacks

Met aangepaste styling

Met beltoon

Met aangepaste API-basis

Foutafhandeling

Volgende stappen