Headless Hook - ThunderPhone

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

Коли використовувати Headless-хук

Готовий компонент ThunderPhoneWidget покриває більшість випадків використання, але використовуйте Headless-хук, коли вам потрібно:

Повністю кастомний UI дзвінка, що відповідає дизайн-системі вашого застосунку
Візуалізації, що реагують на аудіо (форми хвиль, сфери, пульсуючі індикатори) на основі аудіорівнів у реальному часі
Кастомні сценарії дзвінків, як-от форми перед дзвінком, опитування після дзвінка або вбудований чат поруч із голосовим спілкуванням
Інтеграція з наявною бібліотекою компонентів (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`	Невидимий елемент, який обробляє аудіопідключення — його потрібно рендерити.

Аудіореактивний UI

Реф 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>
  )
}

Приклад індикатора мовлення

Для UI, що рендериться 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}
    </>
  )
}

Повністю власний UI

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 не спричиняє повторного рендерингу), або вимірюйте його через інтервали та зберігайте результат у стані для UI, який рендерить React. Число audioLevel застаріло й завжди дорівнює 0 — не будуйте на ньому логіку.

​Коли використовувати Headless-хук

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

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

​Параметри

​Значення, що повертається

​Аудіореактивний UI

​Приклад хвильової форми

​Приклад пульсуючої сфери

​Приклад індикатора мовлення

​Машина станів

​Приклади

​З керуванням вимкненням звуку

​З рингтоном

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

​Повністю власний UI

​Поради

Коли використовувати Headless-хук

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

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

Параметри

Значення, що повертається

Аудіореактивний UI

Приклад хвильової форми

Приклад пульсуючої сфери

Приклад індикатора мовлення

Машина станів

Приклади

З керуванням вимкненням звуку

З рингтоном

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

Повністю власний UI

Поради