Компонент React

Компонент ThunderPhoneWidget відображає скляну панель дзвінка з вбудованими елементами керування для вимкнення мікрофона, завершення дзвінка та відображення статусу підключення. Це найшвидший спосіб додати голосовий ШІ до React-застосунку.

Встановлення

npm install @thunderphone/widget

Базове використання

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
    />
  )
}

Ви повинні імпортувати CSS-файл, щоб віджет відображався правильно. Без нього віджет буде без стилізації.

Властивості

Компонент приймає такі властивості через ThunderPhoneWidgetProps:

Властивість	Тип	Обов’язково	За замовчуванням	Опис
`publishableKey`	`string`	Так	—	Публічний API-ключ (`pk_live_...`) із налаштувань Developers. Агент визначається автоматично з конфігурації віджета ключа.
`theme`	`'light' \| 'dark'`	Ні	`'light'`	Колірна схема. Застосовує клас `tp--light` або `tp--dark` до кореневого елемента віджета.
`primaryColor`	`string`	Ні	`'#000000'` (світла) / `'#ffffff'` (темна)	Рядок кольору CSS, що використовується як акцентний колір (кнопка дзвінка, хвильова форма, активні індикатори).
`title`	`string`	Ні	`'Voice assistant'`	Текст, що відображається на панелі віджета.
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	Ні	`'bottom-right'`	Фіксована позиція віджета у вікні перегляду.
`apiBase`	`string`	Ні	`'https://api.thunderphone.com/v1'`	Перевизначення базової URL-адреси API.
`language`	`string`	Ні	—	Перевизначення мови для сеансу — код мови або локаль, наприклад `en`, `es` чи `fr-FR`. Якщо не задано, використовується налаштована мова агента.
`voice`	`string`	Ні	—	Перевизначення голосу для сеансу — назва голосу, наприклад `maria`. Якщо не задано, використовується налаштований голос агента.
`context`	`string`	Ні	—	Фактичний контекст сторінки або сайту для сеансу, що передається агенту (наприклад, відомості про сторінку, яку переглядає відвідувач). На сервері скорочується до 12 000 символів.
`onConnect`	`() => void`	Ні	—	Викликається, коли голосовий сеанс успішно підключено.
`onDisconnect`	`() => void`	Ні	—	Викликається після завершення сеансу.
`onError`	`(error) => void`	Ні	—	Викликається у разі помилок. Об’єкт `error` має поля `error` (код) і `message`.
`className`	`string`	Ні	—	Додаткова назва CSS-класу, що застосовується до контейнера віджета.
`ringtone`	`boolean \| string`	Ні	`false`	Відтворювати мелодію дзвінка під час підключення. `true` для стандартної мелодії або рядок URL для власного аудіо.

Приклади

Темна тема з користувацьким кольором

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

Користувацьке розташування

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      position="bottom-left"
    />
  )
}

Мова, голос і контекст для кожного сеансу

Властивості language, voice і context передаються в запит сеансу (POST /widget/session) на початку виклику, перевизначаючи налаштовані за замовчуванням параметри агента для цього сеансу:

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

Використовуйте context, щоб надати агенту фактичні відомості про сторінку, на якій перебуває відвідувач: деталі продукту, ціни або поширені запитання, специфічні для сторінки. На сервері його буде скорочено до 12 000 символів.

Зі зворотними викликами подій

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

З користувацьким стилем

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

Перегляньте посібник зі стилізації, щоб дізнатися про всі доступні CSS-класи та користувацькі властивості.

Із мелодією дзвінка

Відтворюйте звук телефонного дзвінка під час встановлення з’єднання:

import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function PhoneWidget() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      ringtone={true}
    />
  )
}

Використовуйте користувацьку мелодію дзвінка, передавши URL аудіофайлу:

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

Мелодія дзвінка відтворюється циклічно, поки віджет перебуває в стані connecting, і плавно згасає, коли агент підключається.

Із користувацькою базою API

Налаштовувати apiBase потрібно лише якщо ви використовуєте самостійно розгорнуту або проксійовану кінцеву точку API. За замовчуванням використовується https://api.thunderphone.com/v1.

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

Обробка помилок

Коли спрацьовує зворотний виклик onError, він отримує об’єкт помилки з двома полями:

Поле	Тип	Опис
`error`	`string`	Машинозчитуваний код помилки
`message`	`string`	Зрозумілий для людини опис помилки

Поширені коди помилок включають недозволений домен, агента не знайдено та недійсний ключ API.

Наступні кроки

Headless Hook

Потрібен повний контроль над інтерфейсом? Натомість використовуйте хук useThunderPhone.

Стилізація

Налаштовуйте кольори, розміри та компонування за допомогою користувацьких властивостей CSS.

​Встановлення

​Базове використання

​Властивості

​Приклади

​Темна тема з користувацьким кольором

​Користувацьке розташування

​Мова, голос і контекст для кожного сеансу

​Зі зворотними викликами подій

​З користувацьким стилем

​Із мелодією дзвінка

​Із користувацькою базою API

​Обробка помилок

​Наступні кроки

Headless Hook

Стилізація

Встановлення

Базове використання

Властивості

Приклади

Темна тема з користувацьким кольором

Користувацьке розташування

Мова, голос і контекст для кожного сеансу

Зі зворотними викликами подій

З користувацьким стилем

Із мелодією дзвінка

Із користувацькою базою API

Обробка помилок

Наступні кроки