Open in

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 Widgeturi web în tabloul de bord. Agentul vocal este determinat automat din configurația widgetului asociată cheii.
`theme`	`'light' \| 'dark'`	Nu	`'light'`	Schemă de culori. Aplică clasa `tp--light` sau `tp--dark` rădăcinii widgetului.
`primaryColor`	`string`	Nu	`'#000000'` (deschis) / `'#ffffff'` (închis)	Șir de culoare CSS utilizat ca culoare de accent (buton de apel, formă de undă, indicatori 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 afișare pentru widget.
`apiBase`	`string`	Nu	`'https://api.thunderphone.com/v1'`	Suprascrierea URL-ului 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ă pentru agentul vocal. Necesită `language` în suprascrierile din browser ale cheii.
`voice`	`string`	Nu	--	Suprascrierea vocii pentru fiecare sesiune -- un nume de voce precum `maria`. Dacă nu este setată, se aplică vocea configurată pentru agentul vocal. Necesită `voice` în suprascrierile din browser ale cheii.
`context`	`string`	Nu	--	Context factual al paginii sau site-ului pentru fiecare sesiune, transmis agentului vocal (de exemplu, detalii despre pagina pe care o vizualizează vizitatorul). Este trunchiat pe server la 12.000 de caractere. Necesită `context` în suprascrierile din browser ale cheii.
`onConnect`	`() => void`	Nu	--	Este apelată când sesiunea vocală se conectează cu succes.
`onDisconnect`	`() => void`	Nu	--	Este apelată când sesiunea se încheie.
`onError`	`(error) => void`	Nu	--	Este apelată la erori. 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`	Redă 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) când începe un apel, înlocuind valorile implicite configurate ale agentului pentru sesiunea respectivă. Activați fiecare proprietate pe care o utilizați în Suprascrieri din browser pentru widget în tabloul de bord (sau în allowed_overrides al cheii). Widgeturile noi nu acceptă niciuna, iar o cerere de sesiune care include una dezactivată eșuează cu 400 override_not_allowed; consultați Suprascrieri din browser.

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. Agentul îl tratează ca pe conținutul paginii, nu ca pe instrucțiuni. 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.