Komponenta React - ThunderPhone

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

Abyste se widget vykreslil správně, musíte importovat soubor CSS. Bez něj widget nebude mít žádné styly.

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 nastavení pro vývojáře. 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žívaný jako zvýrazňující barva (tlačítko hovoru, průběh zvuku, aktivní indikátory).
`title`	`string`	Ne	`'Voice assistant'`	Text zobrazený v panelu widgetu.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ne	`'bottom-right'`	Pevná pozice widgetu ve výřezu stránky.
`apiBase`	`string`	Ne	`'https://api.thunderphone.com/v1'`	Přepsání základní adresy URL API.
`language`	`string`	Ne	—	Přepsání jazyka pro relaci – kód jazyka nebo národní prostředí, například `en`, `es` nebo `fr-FR`. Pokud není nastaveno, použije se nakonfigurovaný jazyk agenta.
`voice`	`string`	Ne	—	Přepsání hlasu pro relaci – název hlasu, například `maria`. Pokud není nastaveno, použije se nakonfigurovaný hlas agenta.
`context`	`string`	Ne	—	Věcný kontext stránky nebo webu pro relaci předaný agentovi (například podrobnosti o stránce, kterou návštěvník zobrazuje). Na straně serveru je zkrácen na 12 000 znaků.
`onConnect`	`() => void`	Ne	—	Volá se po úspěšném připojení hlasové relace.
`onDisconnect`	`() => void`	Ne	—	Volá se při 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ý na kontejner widgetu.
`ringtone`	`boolean \| string`	Ne	`false`	Při připojování přehraje vyzváněcí tón. Hodnota `true` použije výchozí vyzváněcí tón, případně můžete zadat ř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í požadavku relace (POST /widget/session) a pro tuto relaci přepisují nakonfigurované výchozí hodnoty agenta:

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. Na straně serveru se zkracuje 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

apiBase stačí nastavit pouze v případě, že používáte vlastní hostovaný nebo proxy koncový bod API. Výchozí hodnota ukazuje na https://api.thunderphone.com/v1.

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

​Instalace

​Základní použití

​Vlastnosti

​Příklady

​Tmavý motiv s vlastní barvou

​Vlastní pozice

​Jazyk, hlas a kontext pro relaci

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

​S vlastním stylem

​S vyzváněním

​S vlastní základní adresou API

​Zpracování chyb

​Další kroky

Headless hook

Styly

Instalace

Základní použití

Vlastnosti

Příklady

Tmavý motiv s vlastní barvou

Vlastní pozice

Jazyk, hlas a kontext pro relaci

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

S vlastním stylem

S vyzváněním

S vlastní základní adresou API

Zpracování chyb

Další kroky