Componentă React

Integrați widgetul vocal ThunderPhone într-o aplicație React

Componenta ThunderPhoneWidget redă o bară de apel cu aspect glassmorphic, cu controale integrate pentru dezactivarea sunetului, încheierea apelului și afișarea stării conexiunii. Este cea mai rapidă modalitate de a adăuga AI vocal într-o aplicație React.

Instalare

npm install @thunderphone/widget

Utilizare de bază

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

Proprietăți

Componenta acceptă următoarele proprietăți prin ThunderPhoneWidgetProps:

Proprietate	Tip	Obligatoriu	Implicit	Descriere
`publishableKey`	`string`	Da	--	Cheie API publicabilă (`pk_live_...`) din setările Dezvoltatori. Agentul este determinat automat din configurația widgetului asociată cheii.
`theme`	`'light' \| 'dark'`	Nu	`'light'`	Schemă de culori. Aplică clasa `tp--light` sau `tp--dark` la rădăcina widgetului.
`primaryColor`	`string`	Nu	`'#000000'` (deschis) / `'#ffffff'` (închis)	Șir de culoare CSS utilizat ca culoare de accent (butonul de apel, forma de undă, indicatorii activi).
`title`	`string`	Nu	`'Voice assistant'`	Text afișat în bara widgetului.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Nu	`'bottom-right'`	Poziție fixă în fereastra de vizualizare pentru widget.
`apiBase`	`string`	Nu	`'https://api.thunderphone.com/v1'`	Suprascriere pentru URL-ul de bază al API-ului.
`language`	`string`	Nu	--	Suprascrierea limbii pentru fiecare sesiune -- un cod de limbă sau o setare regională, precum `en`, `es` sau `fr-FR`. Dacă nu este setată, se aplică limba configurată a agentului.
`voice`	`string`	Nu	--	Suprascrierea vocii pentru fiecare sesiune -- un nume de voce, precum `maria`. Dacă nu este setată, se aplică vocea configurată a agentului.
`context`	`string`	Nu	--	Context factual al paginii sau site-ului, pentru fiecare sesiune, transmis agentului (de exemplu, detalii despre pagina pe care o vizualizează vizitatorul). Este trunchiat pe partea de server la 12.000 de caractere.
`onConnect`	`() => void`	Nu	--	Apelată când sesiunea vocală se conectează cu succes.
`onDisconnect`	`() => void`	Nu	--	Apelată când sesiunea se încheie.
`onError`	`(error) => void`	Nu	--	Apelată la apariția erorilor. Obiectul `error` are câmpurile `error` (cod) și `message`.
`className`	`string`	Nu	--	Nume de clasă CSS suplimentar aplicat containerului widgetului.
`ringtone`	`boolean \| string`	Nu	`false`	Redați un ton de apel în timpul conectării. `true` pentru tonul de apel implicit sau un șir URL pentru audio personalizat.

Exemple

Temă întunecată cu culoare personalizată

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

Poziție personalizată

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

Limbă, voce și context pentru fiecare sesiune

Proprietățile language, voice și context sunt transmise cererii de sesiune (POST /widget/session) la inițierea unui apel, înlocuind valorile implicite configurate pentru agent pentru sesiunea respectivă:

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

Utilizați context pentru a oferi agentului informații factuale despre pagina pe care se află vizitatorul -- detalii despre produs, prețuri sau întrebări frecvente specifice paginii. Acesta este trunchiat pe server la 12.000 de caractere.

Cu callback-uri pentru evenimente

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

Cu stilizare personalizată

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

Consultați ghidul de stilizare pentru toate clasele CSS și proprietățile personalizate disponibile.

Cu ton de apel

Redați un sunet de telefon care sună în timp ce se stabilește conexiunea:

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

Utilizați un ton de apel personalizat transmițând un URL către un fișier audio:

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

Tonul de apel se repetă cât timp widgetul este în starea connecting și se estompează treptat atunci când agentul se conectează.

Cu bază API personalizată

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

Gestionarea erorilor

Când este declanșat callback-ul onError, acesta primește un obiect de eroare cu două câmpuri:

Câmp	Tip	Descriere
`error`	`string`	Cod de eroare care poate fi citit de mașină
`message`	`string`	Descriere de eroare care poate fi citită de utilizator

Codurile de eroare frecvente includ domeniu nepermis, agent negăsit și cheie API nevalidă.

Pașii următori

Hook headless

Aveți nevoie de control complet asupra interfeței? Folosiți în schimb hook-ul useThunderPhone.

Stilizare

Personalizați culorile, dimensiunile și aspectul cu proprietăți personalizate CSS.