React-komponent

Indlejr ThunderPhone-stemmekomponenten i en React-applikation

Komponenten ThunderPhoneWidget gengiver en glasmorfisk opkaldslinje med indbyggede kontrolelementer til at slå lyd fra, afslutte opkaldet og vise forbindelsesstatus. Det er den hurtigste måde at tilføje stemme-AI til en React-app.

Installation

npm install @thunderphone/widget

Grundlæggende brug

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

Egenskaber

Komponenten accepterer følgende egenskaber via ThunderPhoneWidgetProps:

Egenskab	Type	Påkrævet	Standard	Beskrivelse
`publishableKey`	`string`	Ja	--	Publicerbar API-nøgle (`pk_live_...`) fra udviklerindstillingerne. Agenten bestemmes automatisk ud fra nøglens widgetkonfiguration.
`theme`	`'light' \| 'dark'`	Nej	`'light'`	Farveskema. Anvender klassen `tp--light` eller `tp--dark` på widgettens rodelement.
`primaryColor`	`string`	Nej	`'#000000'` (lys) / `'#ffffff'` (mork)	CSS-farvestreng, der bruges som accentfarve (opkaldsknap, bolgeform, aktive indikatorer).
`title`	`string`	Nej	`'Voice assistant'`	Tekst, der vises i widgetlinjen.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nej	`'bottom-right'`	Fast position i viewporten for widgetten.
`apiBase`	`string`	Nej	`'https://api.thunderphone.com/v1'`	Tilsidesættelse af API-basis-URL.
`language`	`string`	Nej	--	Tilsidesættelse af sprog pr. session -- en sprogkode eller landestandard som `en`, `es` eller `fr-FR`. Nar den ikke er angivet, bruges agentens konfigurerede sprog.
`voice`	`string`	Nej	--	Tilsidesættelse af stemme pr. session -- et stemmenavn som `maria`. Nar den ikke er angivet, bruges agentens konfigurerede stemme.
`context`	`string`	Nej	--	Faktuel side- eller webstedskontekst pr. session, der sendes til agenten (for eksempel oplysninger om den side, den besogende ser). Afkortes pa serversiden til 12.000 tegn.
`onConnect`	`() => void`	Nej	--	Kaldes, nar stemmesessionen opretter forbindelse.
`onDisconnect`	`() => void`	Nej	--	Kaldes, nar sessionen slutter.
`onError`	`(error) => void`	Nej	--	Kaldes ved fejl. Objektet `error` har felterne `error` (kode) og `message`.
`className`	`string`	Nej	--	Yderligere CSS-klassenavn, der anvendes pa widgetbeholderen.
`ringtone`	`boolean \| string`	Nej	`false`	Afspil en ringetone under forbindelsen. Brug `true` for standardringetonen eller en URL-streng til brugerdefineret lyd.

Eksempler

Mørkt tema med brugerdefineret farve

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

Brugerdefineret placering

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

Sprog, stemme og kontekst pr. session

Propsene language, voice og context videresendes til sessionsanmodningen (POST /widget/session), når et opkald starter, og tilsidesætter agentens konfigurerede standardværdier for den pågældende session:

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

Brug context til at give agenten faktuel viden om den side, den besøgende er på -- produktoplysninger, priser eller ofte stillede spørgsmål, der er specifikke for siden. Den afkortes på serversiden til 12.000 tegn.

Med hændelses-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}`)
      }}
    />
  )
}

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

Se stylingguiden for alle tilgængelige CSS-klasser og brugerdefinerede egenskaber.

Med ringetone

Afspil en telefonringelyd, mens forbindelsen oprettes:

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

Brug en brugerdefineret ringetone ved at angive en URL til en lydfil:

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  ringtone="https://example.com/my-ringtone.mp3"
/>

Ringetonen gentages, mens widgetten er i tilstanden connecting, og toner blødt ud, når agenten opretter forbindelse.

Med brugerdefineret API-base

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  apiBase="https://your-proxy.example.com/v1"
/>

Fejlhåndtering

Når callbacken onError udløses, modtager den et fejlobjekt med to felter:

Felt	Type	Beskrivelse
`error`	`string`	Maskinlæsbar fejlkode
`message`	`string`	Menneskelæsbar fejlbeskrivelse

Almindelige fejlkoder omfatter domæne ikke tilladt, agent ikke fundet og ugyldig API-nøgle.

Næste trin

Headless-hook

Har du brug for fuld kontrol over brugergrænsefladen? Brug i stedet hooket useThunderPhone.

Styling

Tilpas farver, størrelser og layout med brugerdefinerede CSS-egenskaber.