React-komponent

Bygg inn ThunderPhone-stemmewidgeten i en React-applikasjon

ThunderPhoneWidget-komponenten gjengir en glassmorfisk anropslinje med innebygde kontroller for å dempe lyd, avslutte samtalen og vise tilkoblingsstatus. Det er den raskeste måten å legge til stemme-AI i en React-app.

Installasjon

npm install @thunderphone/widget

Grunnleggende bruk

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

Rekvisitter

Komponenten godtar følgende rekvisitter via ThunderPhoneWidgetProps:

Rekvisitt	Type	Påkrevd	Standard	Beskrivelse
`publishableKey`	`string`	Ja	--	Publiserbar API-nøkkel (`pk_live_...`) fra Utviklerinnstillinger. Agenten løses automatisk fra nøkkelens widgetkonfigurasjon.
`theme`	`'light' \| 'dark'`	Nei	`'light'`	Fargeskjema. Bruker klassen `tp--light` eller `tp--dark` på widgetens rotelement.
`primaryColor`	`string`	Nei	`'#000000'` (lys) / `'#ffffff'` (mørk)	CSS-fargestreng som brukes som aksentfarge (anropsknapp, bølgeform, aktive indikatorer).
`title`	`string`	Nei	`'Voice assistant'`	Tekst som vises i widgetlinjen.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nei	`'bottom-right'`	Fast plassering i visningsområdet for widgeten.
`apiBase`	`string`	Nei	`'https://api.thunderphone.com/v1'`	Overstyring av API-base-URL.
`language`	`string`	Nei	--	Overstyring av språk per økt -- en språkkode eller lokalitet, for eksempel `en`, `es` eller `fr-FR`. Når den ikke er angitt, brukes agentens konfigurerte språk.
`voice`	`string`	Nei	--	Overstyring av stemme per økt -- et stemmenavn som `maria`. Når den ikke er angitt, brukes agentens konfigurerte stemme.
`context`	`string`	Nei	--	Faktabasert side- eller nettstedskontekst per økt som sendes til agenten (for eksempel detaljer om siden den besøkende ser på). Avkortes på serversiden til 12 000 tegn.
`onConnect`	`() => void`	Nei	--	Kalles når stemmeøkten kobles til.
`onDisconnect`	`() => void`	Nei	--	Kalles når økten avsluttes.
`onError`	`(error) => void`	Nei	--	Kalles ved feil. `error`-objektet har feltene `error` (kode) og `message`.
`className`	`string`	Nei	--	Ekstra CSS-klassenavn som brukes på widgetbeholderen.
`ringtone`	`boolean \| string`	Nei	`false`	Spill av ringetone under tilkobling. `true` for standardringetonen, eller en URL-streng for egendefinert lyd.

Eksempler

Mørkt tema med egendefinert farge

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

Egendefinert plassering

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

Språk, stemme og kontekst per økt

Proppene language, voice og context videresendes til øktforespørselen (POST /widget/session) når et anrop starter, og overstyrer agentens konfigurerte standardverdier for den aktuelle økten:

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

Bruk context til å gi agenten faktakunnskap om siden den besøkende er på -- produktdetaljer, priser eller side-spesifikke vanlige spørsmål. Den avkortes på serversiden til 12 000 tegn.

Med hendelsestilbakekall

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 egendefinert 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 stilguiden for alle tilgjengelige CSS-klasser og egendefinerte egenskaper.

Med ringetone

Spill av en telefonringelyd mens tilkoblingen opprettes:

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

Bruk en egendefinert ringetone ved å sende inn URL-en til en lydfil:

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

Ringetonen gjentas mens widgeten er i tilstanden connecting, og tones jevnt ut når agenten kobler til.

Med egendefinert API-base

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

Feilhåndtering

Når tilbakekallet onError utløses, mottar det et feilobjekt med to felt:

Felt	Type	Beskrivelse
`error`	`string`	Maskinlesbar feilkode
`message`	`string`	Menneskelesbar feilbeskrivelse

Vanlige feilkoder omfatter domenet er ikke tillatt, agenten ble ikke funnet og ugyldig API-nøkkel.

Neste steg

Headless Hook

Trenger du full kontroll over brukergrensesnittet? Bruk useThunderPhone-hooken i stedet.

Stilsetting

Tilpass farger, størrelser og layout med egendefinerte CSS-egenskaper.