Headless Hook - ThunderPhone

Хук useThunderPhone предоставляет полный контроль над пользовательским интерфейсом, пока ThunderPhone управляет голосовым сеансом, маршрутизацией аудио и состоянием подключения. Используйте его, если нужен полностью кастомный UI — собственные кнопки, макеты, анимации и брендинг, — пока ThunderPhone берёт на себя всю внутреннюю работу.

Когда использовать Headless-хук

Готовый компонент ThunderPhoneWidget покрывает большинство сценариев, но используйте headless-хук, если вам нужны:

Полностью кастомный интерфейс звонка, соответствующий дизайн-системе вашего приложения
Визуализации, реагирующие на аудио в реальном времени (волновые формы, сферы, пульсирующие индикаторы)
Кастомные сценарии звонка, например формы перед звонком, опросы после звонка или встроенный чат рядом с голосовым взаимодействием
Интеграция с существующей библиотекой компонентов (Material UI, Chakra, Radix и т. д.)

Установка

npm install @thunderphone/widget

Headless-хук не требует импортировать @thunderphone/widget/style.css, поскольку вы создаёте собственный UI. Однако всё равно необходимо установить тот же пакет @thunderphone/widget.

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

import { useThunderPhone } from '@thunderphone/widget'

function CustomCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  const handleClick = () => {
    if (phone.state === 'connected') {
      phone.disconnect()
    } else {
      phone.connect()
    }
  }

  return (
    <>
      <button onClick={handleClick} disabled={phone.state === 'connecting'}>
        {phone.state === 'connecting'
          ? 'Connecting...'
          : phone.state === 'connected'
            ? 'End call'
            : 'Start call'}
      </button>
      {phone.audio}
    </>
  )
}

Необходимо отрендерить phone.audio где-либо в дереве компонентов. Это невидимый элемент React, который управляет базовым аудиоподключением. Если его не добавить, аудио не будет воспроизводиться, а сеанс не будет работать.

Параметры

Передавайте эти параметры в useThunderPhone через UseThunderPhoneOptions:

Параметр	Тип	Обязательный	По умолчанию	Описание
`publishableKey`	`string`	Да	—	Публикуемый ключ API (`pk_live_...`). Агент автоматически определяется по конфигурации виджета, связанной с ключом.
`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` (код) и `message`.
`ringtone`	`boolean \| string`	Нет	`false`	Воспроизводить мелодию звонка при подключении. `true` для стандартной мелодии или URL-строка для кастомного аудио.

Хук не имеет интерфейса: он не принимает свойства оформления ThunderPhoneWidget (theme, primaryColor, title, position, className). Их передача вызывает ошибку TypeScript — всё представление вы реализуете самостоятельно.

Возвращаемое значение

Хук возвращает объект UseThunderPhoneReturn:

Свойство	Тип	Описание
`state`	`'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'`	Текущее состояние подключения.
`connect`	`() => void`	Запустить голосовой сеанс.
`disconnect`	`() => void`	Завершить текущий сеанс.
`toggleMute`	`() => void`	Включить или выключить отключение микрофона.
`isMuted`	`boolean`	Отключён ли микрофон в данный момент.
`error`	`string \| undefined`	Сообщение об ошибке, когда состояние — `'error'`.
`agentName`	`string \| undefined`	Отображаемое имя подключённого агента.
`audioLevel`	`number`	Устарело — всегда `0`. Статический заполнитель, сохранённый для обратной совместимости; он никогда не обновляется. Вместо этого читайте `audioLevelRef.current`.
`audioLevelRef`	`React.RefObject<number>`	Изменяемая ссылка, содержащая уровень звука в реальном времени (0—1) — более высокий из уровня голоса агента и микрофона посетителя — обновляемый на каждом кадре анимации вне цикла рендеринга React. Читайте `audioLevelRef.current` внутри циклов `requestAnimationFrame` для плавной анимации без рывков или получайте значение через интервалы, когда оно требуется в состоянии React.
`audio`	`ReactNode`	Невидимый элемент, который обрабатывает аудиоподключение — его необходимо отрендерить.

Интерфейс, реагирующий на аудио

Ссылка audioLevelRef предоставляет уровни аудио с частотой кадров без запуска повторного рендеринга React, поэтому она идеально подходит для плавной визуализации волновой формы, пульсирующих сфер или любой анимации, связанной с разговором. Уровень отражает более громкий источник: голос агента или микрофон посетителя.

Пример волновой формы

import { useRef, useEffect } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function WaveformCall() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const canvasRef = useRef<HTMLCanvasElement>(null)

  useEffect(() => {
    if (phone.state !== 'connected') return
    const canvas = canvasRef.current
    if (!canvas) return
    const ctx = canvas.getContext('2d')!

    let animId: number
    const draw = () => {
      const level = phone.audioLevelRef.current ?? 0
      ctx.clearRect(0, 0, canvas.width, canvas.height)

      // Draw bars that react to audio level
      const barCount = 24
      const barWidth = canvas.width / barCount
      for (let i = 0; i < barCount; i++) {
        const distance = Math.abs(i - barCount / 2) / (barCount / 2)
        const height = level * canvas.height * (1 - distance * 0.6)
        const y = (canvas.height - height) / 2
        ctx.fillStyle = '#0ea5e9'
        ctx.fillRect(i * barWidth + 1, y, barWidth - 2, height)
      }

      animId = requestAnimationFrame(draw)
    }
    animId = requestAnimationFrame(draw)
    return () => cancelAnimationFrame(animId)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div>
      {phone.state === 'connected' && (
        <canvas ref={canvasRef} width={240} height={80} />
      )}
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'End call' : 'Start call'}
      </button>
      {phone.audio}
    </div>
  )
}

Пример пульсирующей сферы

import { useRef, useEffect } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function PulsingOrb() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const orbRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (phone.state !== 'connected') return
    let animId: number
    const animate = () => {
      const level = phone.audioLevelRef.current ?? 0
      if (orbRef.current) {
        const scale = 1 + level * 0.5
        orbRef.current.style.transform = `scale(${scale})`
        orbRef.current.style.opacity = `${0.6 + level * 0.4}`
      }
      animId = requestAnimationFrame(animate)
    }
    animId = requestAnimationFrame(animate)
    return () => cancelAnimationFrame(animId)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div style={{ textAlign: 'center' }}>
      <div
        ref={orbRef}
        style={{
          width: 80,
          height: 80,
          borderRadius: '50%',
          background: '#0ea5e9',
          margin: '20px auto',
          transition: 'transform 0.05s ease-out',
        }}
      />
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'End call' : 'Call'}
      </button>
      {phone.audio}
    </div>
  )
}

Пример индикатора речи

Для интерфейса, рендерируемого React и меняющегося в зависимости от громкости — например, бейджа «говорит» на основе порогового значения — считывайте audioLevelRef.current через интервалы и сохраняйте результат в состоянии:

import { useEffect, useState } from 'react'
import { useThunderPhone } from '@thunderphone/widget'

function SpeakingBadge() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
  const [speaking, setSpeaking] = useState(false)

  useEffect(() => {
    if (phone.state !== 'connected') {
      setSpeaking(false)
      return
    }
    const interval = setInterval(() => {
      setSpeaking((phone.audioLevelRef.current ?? 0) > 0.1)
    }, 100)
    return () => clearInterval(interval)
  }, [phone.state, phone.audioLevelRef])

  return (
    <div>
      {phone.state === 'connected' && (
        <span>{speaking ? 'Speaking' : 'Listening'}</span>
      )}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'End call' : 'Start call'}
      </button>
      {phone.audio}
    </div>
  )
}

Всегда считывайте уровни из audioLevelRef.current. Число audioLevel в возвращаемом объекте устарело и всегда равно 0 — любая логика, основанная на нём, будет незаметно получать ноль.

Конечный автомат

Свойство state проходит следующий жизненный цикл:

idle --> connecting --> connected --> disconnected --> idle (after 1.5s)
                  \
                   --> error (stays until connect() is called again)

Состояние	Описание
`idle`	Нет активной сессии. Готово к вызову `connect()`.
`connecting`	Сессия устанавливается. Отключите кнопку звонка в этом состоянии.
`connected`	Голосовая сессия активна. Пользователь разговаривает с агентом.
`disconnected`	Сессия корректно завершена. Через 1,5 секунды автоматически возвращается к `idle`.
`error`	Что-то пошло не так. Проверьте сообщение в `phone.error`. Состояние не сбрасывается само по себе — повторный вызов `connect()` запускает новую попытку и сбрасывает ошибку.

Примеры

С элементом управления отключением микрофона

import { useThunderPhone } from '@thunderphone/widget'

function CallWithMute() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div>
      {phone.state === 'connected' && (
        <div>
          <p>Talking to {phone.agentName ?? 'Agent'}</p>
          <button onClick={phone.toggleMute}>
            {phone.isMuted ? 'Unmute' : 'Mute'}
          </button>
          <button onClick={phone.disconnect}>End call</button>
        </div>
      )}

      {phone.state !== 'connected' && (
        <button
          onClick={phone.connect}
          disabled={phone.state === 'connecting'}
        >
          {phone.state === 'connecting' ? 'Connecting...' : 'Call support'}
        </button>
      )}

      {phone.state === 'error' && (
        <p style={{ color: 'red' }}>{phone.error}</p>
      )}

      {phone.audio}
    </div>
  )
}

С рингтоном

Воспроизводите звук звонка во время подключения, чтобы имитировать телефонный вызов:

import { useThunderPhone } from '@thunderphone/widget'

function PhoneCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
    ringtone: true, // or a custom URL: 'https://example.com/ringtone.mp3'
  })

  return (
    <>
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connecting'
          ? 'Ringing...'
          : phone.state === 'connected'
            ? 'Hang up'
            : 'Call'}
      </button>
      {phone.audio}
    </>
  )
}

Рингтон воспроизводится по кругу в состоянии connecting и постепенно затихает, когда агент подключается. Передайте true, чтобы использовать встроенный рингтон по умолчанию, или строку URL, чтобы использовать собственный аудиофайл.

С обратными вызовами событий

import { useThunderPhone } from '@thunderphone/widget'

function TrackedCallButton() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
    onConnect: () => {
      analytics.track('call_started')
    },
    onDisconnect: () => {
      analytics.track('call_ended')
    },
    onError: (error) => {
      analytics.track('call_error', { code: error.error, message: error.message })
    },
  })

  return (
    <>
      <button
        onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}
        disabled={phone.state === 'connecting'}
      >
        {phone.state === 'connected' ? 'Hang up' : 'Talk to AI'}
      </button>
      {phone.audio}
    </>
  )
}

Полностью пользовательский интерфейс

import { useThunderPhone } from '@thunderphone/widget'

function FullCustomUI() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })

  return (
    <div className="call-panel">
      <div className="call-status">
        {phone.state === 'idle' && <span>Ready</span>}
        {phone.state === 'connecting' && <span className="pulse">Connecting...</span>}
        {phone.state === 'connected' && (
          <span>On call with {phone.agentName}</span>
        )}
        {phone.state === 'error' && <span className="error">{phone.error}</span>}
      </div>

      <div className="call-controls">
        {phone.state === 'connected' ? (
          <>
            <button className="mute-btn" onClick={phone.toggleMute}>
              {phone.isMuted ? 'Unmute' : 'Mute'}
            </button>
            <button className="end-btn" onClick={phone.disconnect}>
              End
            </button>
          </>
        ) : (
          <button
            className="start-btn"
            onClick={phone.connect}
            disabled={phone.state === 'connecting'}
          >
            Start call
          </button>
        )}
      </div>

      {/* Required -- handles audio under the hood */}
      {phone.audio}
    </div>
  )
}

Советы

Всегда рендерьте phone.audio

Элемент phone.audio невидим, но обязателен. Разместите его в любом месте JSX — он не рендерит видимый DOM, но внутренне управляет аудиосоединением WebRTC.

Отключайте кнопку во время подключения

Состояние connecting может длиться 1–3 секунды. Отключайте кнопку звонка в этом состоянии, чтобы предотвратить повторные попытки подключения.

Корректно обрабатывайте состояние ошибки

Когда состояние равно error, покажите пользователю phone.error и оставьте кнопку звонка включённой. Хук не выходит из состояния error самостоятельно — повторный вызов connect() запускает новую попытку и очищает предыдущую ошибку.

Используйте колбэки для побочных эффектов

Колбэки onConnect, onDisconnect и onError идеально подходят для аналитики, логирования или запуска другой логики приложения без опроса состояния.

Считывайте уровни аудио из audioLevelRef

audioLevelRef — единственный источник уровня аудио в реальном времени. Считывайте audioLevelRef.current внутри requestAnimationFrame для плавных анимаций, таких как волновые формы (чтение ref не вызывает повторный рендеринг), или считывайте его с интервалом и сохраняйте результат в состоянии для интерфейса, рендеримого React. Число audioLevel устарело и всегда равно 0 — не стройте на нём логику.

​Когда использовать Headless-хук

​Установка

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

​Параметры

​Возвращаемое значение

​Интерфейс, реагирующий на аудио

​Пример волновой формы

​Пример пульсирующей сферы

​Пример индикатора речи

​Конечный автомат

​Примеры

​С элементом управления отключением микрофона

​С рингтоном

​С обратными вызовами событий

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

​Советы

Когда использовать Headless-хук

Установка

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

Параметры

Возвращаемое значение

Интерфейс, реагирующий на аудио

Пример волновой формы

Пример пульсирующей сферы

Пример индикатора речи

Конечный автомат

Примеры

С элементом управления отключением микрофона

С рингтоном

С обратными вызовами событий

Полностью пользовательский интерфейс

Советы