Компонент 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_...`) из настроек разработчика. Ассистент определяется автоматически по конфигурации виджета, связанной с ключом.
`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, и плавно затихает, когда агент подключается.

С пользовательским базовым URL 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-хук

Нужен полный контроль над интерфейсом? Используйте хук useThunderPhone.

Стилизация

Настройте цвета, размеры и макет с помощью пользовательских свойств CSS.

​Установка

​Базовое использование

​Свойства

​Примеры

​Тёмная тема с пользовательским цветом

​Пользовательское расположение

​Язык, голос и контекст для каждого сеанса

​С обработчиками событий

​С пользовательскими стилями

​С рингтоном

​С пользовательским базовым URL API

​Обработка ошибок

​Следующие шаги

Headless-хук

Стилизация

Установка

Базовое использование

Свойства

Примеры

Тёмная тема с пользовательским цветом

Пользовательское расположение

Язык, голос и контекст для каждого сеанса

С обработчиками событий

С пользовательскими стилями

С рингтоном

С пользовательским базовым URL API

Обработка ошибок

Следующие шаги