React-komponent - ThunderPhone

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

Du må importere CSS-filen for at widgeten skal gjengis riktig. Uten den vil widgeten være uten stilsetting.

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

Du trenger bare å angi apiBase hvis du bruker et selvhostet eller proxybasert API-endepunkt. Standardverdien peker til https://api.thunderphone.com/v1.

<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.

​Installasjon

​Grunnleggende bruk

​Rekvisitter

​Eksempler

​Mørkt tema med egendefinert farge

​Egendefinert plassering

​Språk, stemme og kontekst per økt

​Med hendelsestilbakekall

​Med egendefinert styling

​Med ringetone

​Med egendefinert API-base

​Feilhåndtering

​Neste steg

Headless Hook

Stilsetting

Installasjon

Grunnleggende bruk

Rekvisitter

Eksempler

Mørkt tema med egendefinert farge

Egendefinert plassering

Språk, stemme og kontekst per økt

Med hendelsestilbakekall

Med egendefinert styling

Med ringetone

Med egendefinert API-base

Feilhåndtering

Neste steg