React-komponent - ThunderPhone

Komponenten ThunderPhoneWidget renderar ett glasliknande samtalsfält med inbyggda kontroller för att stänga av ljudet, avsluta samtalet och visa anslutningsstatus. Det är det snabbaste sättet att lägga till röst-AI i en React-app.

Installation

npm install @thunderphone/widget

Grundläggande användning

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

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

Du måste importera CSS-filen för att widgeten ska renderas korrekt. Utan den saknar widgeten formatering.

Egenskaper

Komponenten accepterar följande egenskaper via ThunderPhoneWidgetProps:

Egenskap	Typ	Krävs	Standard	Beskrivning
`publishableKey`	`string`	Ja	—	Publicerbar API-nyckel (`pk_live_...`) från utvecklarinställningarna. Agenten fastställs automatiskt från nyckelns widgetkonfiguration.
`theme`	`'light' \| 'dark'`	Nej	`'light'`	Färgschema. Tillämpar klassen `tp--light` eller `tp--dark` på widgetens rotelement.
`primaryColor`	`string`	Nej	`'#000000'` (ljust) / `'#ffffff'` (mörkt)	CSS-färgsträng som används som accentfärg (samtalsknapp, vågform, aktiva indikatorer).
`title`	`string`	Nej	`'Voice assistant'`	Text som visas i widgetfältet.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nej	`'bottom-right'`	Fast position i visningsområdet för widgeten.
`apiBase`	`string`	Nej	`'https://api.thunderphone.com/v1'`	Åsidosättning av API-bas-URL.
`language`	`string`	Nej	—	Åsidosättning av språk per session — en språkkod eller språkvariant, till exempel `en`, `es` eller `fr-FR`. När den inte är angiven används agentens konfigurerade språk.
`voice`	`string`	Nej	—	Åsidosättning av röst per session — ett röstnamn som `maria`. När den inte är angiven används agentens konfigurerade röst.
`context`	`string`	Nej	—	Faktabaserad sid- eller webbplatskontext per session som skickas till agenten (till exempel information om sidan som besökaren visar). Trunkeras på serversidan till 12 000 tecken.
`onConnect`	`() => void`	Nej	—	Anropas när röstsessionen ansluts.
`onDisconnect`	`() => void`	Nej	—	Anropas när sessionen avslutas.
`onError`	`(error) => void`	Nej	—	Anropas vid fel. Objektet `error` har fälten `error` (kod) och `message`.
`className`	`string`	Nej	—	Ytterligare CSS-klassnamn som tillämpas på widgetbehållaren.
`ringtone`	`boolean \| string`	Nej	`false`	Spela en ringsignal medan anslutningen upprättas. `true` för standardringsignalen eller en URL-sträng för anpassat ljud.

Exempel

Mörkt tema med anpassad färg

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

Anpassad position

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, röst och kontext per session

Propparna language, voice och context skickas vidare till sessionsbegäran (POST /widget/session) när ett samtal startar och åsidosätter agentens konfigurerade standardvärden för den sessionen:

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

Använd context för att ge agenten faktakunskap om sidan som besökaren är på – produktinformation, priser eller vanliga frågor som är specifika för sidan. Den trunkeras på serversidan till 12 000 tecken.

Med händelseåteranrop

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 anpassad stil

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 för alla tillgängliga CSS-klasser och anpassade egenskaper.

Med ringsignal

Spela upp ett telefonringsignal medan anslutningen upprättas:

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

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Använd en anpassad ringsignal genom att ange en URL till en ljudfil:

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

Ringsignalen upprepas medan widgeten är i tillståndet connecting och tonas ut mjukt när agenten ansluter.

Med anpassad API-bas

Du behöver bara ange apiBase om du använder en egenhostad eller proxybaserad API-slutpunkt. Standardvärdet pekar på https://api.thunderphone.com/v1.

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

Felhantering

När återanropet onError utlöses får det ett felobjekt med två fält:

Fält	Typ	Beskrivning
`error`	`string`	Maskinläsbar felkod
`message`	`string`	Människoläsbar felbeskrivning

Vanliga felkoder omfattar domän ej tillåten, agent hittades inte och ogiltig API-nyckel.

Nästa steg

Headless-hook

Behöver du full kontroll över användargränssnittet? Använd hooken useThunderPhone i stället.

Stilsättning

Anpassa färger, storlekar och layout med anpassade CSS-egenskaper.

​Installation

​Grundläggande användning

​Egenskaper

​Exempel

​Mörkt tema med anpassad färg

​Anpassad position

​Språk, röst och kontext per session

​Med händelseåteranrop

​Med anpassad stil

​Med ringsignal

​Med anpassad API-bas

​Felhantering

​Nästa steg

Headless-hook

Stilsättning

Installation

Grundläggande användning

Egenskaper

Exempel

Mörkt tema med anpassad färg

Anpassad position

Språk, röst och kontext per session

Med händelseåteranrop

Med anpassad stil

Med ringsignal

Med anpassad API-bas

Felhantering

Nästa steg