Componentă React - ThunderPhone

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

Trebuie să importați fișierul CSS pentru ca widgetul să fie redat corect. Fără acesta, widgetul nu va avea stilizare.

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ă

Trebuie să setați apiBase doar dacă utilizați un endpoint API autogăzduit sau proxy. Valoarea implicită indică spre https://api.thunderphone.com/v1.

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

​Instalare

​Utilizare de bază

​Proprietăți

​Exemple

​Temă întunecată cu culoare personalizată

​Poziție personalizată

​Limbă, voce și context pentru fiecare sesiune

​Cu callback-uri pentru evenimente

​Cu stilizare personalizată

​Cu ton de apel

​Cu bază API personalizată

​Gestionarea erorilor

​Pașii următori

Hook headless

Stilizare

Instalare

Utilizare de bază

Proprietăți

Exemple

Temă întunecată cu culoare personalizată

Poziție personalizată

Limbă, voce și context pentru fiecare sesiune

Cu callback-uri pentru evenimente

Cu stilizare personalizată

Cu ton de apel

Cu bază API personalizată

Gestionarea erorilor

Pașii următori