Open in

Komponenta React

Vložte hlasový widget ThunderPhone do aplikace React

Komponenta ThunderPhoneWidget vykresluje skleněný panel hovoru s integrovanými ovládacími prvky pro ztlumení, ukončení hovoru a zobrazení stavu připojení. Je to nejrychlejší způsob, jak přidat hlasovou AI do aplikace React.

Instalace

npm install @thunderphone/widget

Základní použití

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

Vlastnosti

Komponenta přijímá následující vlastnosti prostřednictvím ThunderPhoneWidgetProps:

Vlastnost	Typ	Povinné	Výchozí	Popis
`publishableKey`	`string`	Ano	--	Publikovatelný klíč API (`pk_live_...`) z části Webové widgety v ovládacím panelu. Agent se automaticky určí z konfigurace widgetu daného klíče.
`theme`	`'light' \| 'dark'`	Ne	`'light'`	Barevné schéma. Na kořenový prvek widgetu použije třídu `tp--light` nebo `tp--dark`.
`primaryColor`	`string`	Ne	`'#000000'` (světlé) / `'#ffffff'` (tmavé)	Řetězec barvy CSS použitý jako zvýrazňující barva (tlačítko volání, průběh zvuku, aktivní indikátory).
`title`	`string`	Ne	`'Voice assistant'`	Text zobrazený v liště widgetu.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ne	`'bottom-right'`	Pevná pozice widgetu ve výřezu.
`apiBase`	`string`	Ne	`'https://api.thunderphone.com/v1'`	Přepsání základní adresy URL API.
`language`	`string`	Ne	--	Přepsání jazyka pro jednotlivou relaci – kód jazyka nebo národní prostředí, například `en`, `es` nebo `fr-FR`. Pokud není nastaveno, použije se jazyk nakonfigurovaný pro agenta. Vyžaduje `language` v části přepsání v prohlížeči daného klíče.
`voice`	`string`	Ne	--	Přepsání hlasu pro jednotlivou relaci – název hlasu, například `maria`. Pokud není nastaveno, použije se hlas nakonfigurovaný pro agenta. Vyžaduje `voice` v části přepsání v prohlížeči daného klíče.
`context`	`string`	Ne	--	Věcný kontext stránky nebo webu pro jednotlivou relaci předaný agentovi (například podrobnosti o stránce, kterou návštěvník zobrazuje). Na serveru se zkrátí na 12 000 znaků. Vyžaduje `context` v části přepsání v prohlížeči daného klíče.
`onConnect`	`() => void`	Ne	--	Volá se po úspěšném připojení hlasové relace.
`onDisconnect`	`() => void`	Ne	--	Volá se po ukončení relace.
`onError`	`(error) => void`	Ne	--	Volá se při chybách. Objekt `error` obsahuje pole `error` (kód) a `message`.
`className`	`string`	Ne	--	Další název třídy CSS použitý pro kontejner widgetu.
`ringtone`	`boolean \| string`	Ne	`false`	Při připojování přehraje vyzváněcí tón. `true` pro výchozí vyzváněcí tón nebo řetězec URL pro vlastní zvuk.

Příklady

Tmavý motiv s vlastní barvou

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

Vlastní pozice

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

Jazyk, hlas a kontext pro relaci

Vlastnosti language, voice a context se při zahájení hovoru předávají do požadavku relace (POST /widget/session) a pro danou relaci přepisují nakonfigurované výchozí hodnoty agenta. Každou používanou vlastnost povolte v části Přepsání v prohlížeči pro widget na dashboardu (nebo v allowed_overrides klíče). Nové widgety nepovolují žádné přepsání a požadavek relace obsahující nepovolené přepsání selže s 400 override_not_allowed; viz Přepsání v prohlížeči.

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

Pomocí context poskytněte agentovi faktické informace o stránce, na které se návštěvník nachází – podrobnosti o produktu, ceny nebo časté dotazy specifické pro danou stránku. Agent jej považuje za obsah stránky, nikoli za pokyny. Na straně serveru je zkrácen na 12 000 znaků.

Se zpětnými voláními událostí

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

S vlastním stylem

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

Všechny dostupné třídy CSS a vlastní vlastnosti najdete v průvodci stylováním.

S vyzváněním

Během navazování spojení přehrávejte zvuk vyzvánění telefonu:

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

Vlastní vyzvánění použijte předáním adresy URL zvukového souboru:

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

Vyzvánění se opakuje, dokud je widget ve stavu connecting, a po připojení agenta plynule utichne.

S vlastní základní adresou API

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

Zpracování chyb

Po spuštění zpětného volání onError obdrží objekt chyby se dvěma poli:

Pole	Typ	Popis
`error`	`string`	Strojově čitelný kód chyby
`message`	`string`	Uživatelsky čitelný popis chyby

Mezi běžné kódy chyb patří nepovolená doména, nenalezený agent a neplatný klíč API.

Další kroky

Headless hook

Potřebujete plnou kontrolu nad uživatelským rozhraním? Použijte místo toho hook useThunderPhone.

Styly

Přizpůsobte barvy, velikosti a rozvržení pomocí vlastních vlastností CSS.