Headless Hook

Stwórz w pełni niestandardowy interfejs głosowy za pomocą hooka React useThunderPhone

Hook useThunderPhone zapewnia pełną kontrolę nad interfejsem użytkownika, podczas gdy ThunderPhone zarządza sesją głosową, routingiem audio i stanem połączenia. Użyj go, gdy chcesz stworzyć w pełni niestandardowy interfejs — własne przyciski, układy, animacje i branding — a ThunderPhone zajmie się wszystkim w tle.

Kiedy używać hooka bez interfejsu

Gotowy komponent ThunderPhoneWidget obsługuje większość przypadków użycia, ale wybierz hook bez interfejsu, gdy potrzebujesz:

Całkowicie niestandardowego interfejsu połączeń zgodnego z systemem projektowym aplikacji
Wizualizacji reagujących na dźwięk (przebiegów fal, kul, pulsujących wskaźników) opartych na poziomach audio w czasie rzeczywistym
Niestandardowych przepływów połączeń, takich jak formularze przed połączeniem, ankiety po połączeniu lub czat wbudowany obok rozmowy głosowej
Integracji z istniejącą biblioteką komponentów (Material UI, Chakra, Radix itd.)

Instalacja

npm install @thunderphone/widget

Podstawowe użycie

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

Opcje

Przekaż te opcje do useThunderPhone za pomocą UseThunderPhoneOptions:

Opcja	Typ	Wymagane	Domyślnie	Opis
`publishableKey`	`string`	Tak	--	Publiczny klucz API (`pk_live_...`). Agent jest rozpoznawany automatycznie na podstawie konfiguracji widżetu klucza.
`apiBase`	`string`	Nie	`'https://api.thunderphone.com/v1'`	Zastąpienie bazowego adresu URL API.
`language`	`string`	Nie	--	Zastąpienie języka dla sesji — kod języka lub ustawienia regionalne, takie jak `en`, `es` lub `fr-FR`. Gdy nie jest ustawione, stosowany jest skonfigurowany język agenta.
`voice`	`string`	Nie	--	Zastąpienie głosu dla sesji — nazwa głosu, taka jak `maria`. Gdy nie jest ustawione, stosowany jest skonfigurowany głos agenta.
`context`	`string`	Nie	--	Kontekst faktograficzny strony lub witryny dla sesji przekazywany agentowi. Po stronie serwera skracany do 12 000 znaków.
`onConnect`	`() => void`	Nie	--	Wywoływane po połączeniu sesji głosowej.
`onDisconnect`	`() => void`	Nie	--	Wywoływane po zakończeniu sesji.
`onError`	`(error) => void`	Nie	--	Wywoływane w przypadku błędów. Błąd ma pola `error` (kod) i `message`.
`ringtone`	`boolean \| string`	Nie	`false`	Odtwarzaj dzwonek podczas łączenia. `true` oznacza domyślny dzwonek, a ciąg URL — niestandardowy dźwięk.

Wartość zwracana

Hook zwraca obiekt UseThunderPhoneReturn:

Właściwość	Typ	Opis
`state`	`'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'`	Bieżący stan połączenia.
`connect`	`() => void`	Rozpocznij sesję głosową.
`disconnect`	`() => void`	Zakończ bieżącą sesję.
`toggleMute`	`() => void`	Włącz lub wyłącz wyciszenie mikrofonu.
`isMuted`	`boolean`	Określa, czy mikrofon jest obecnie wyciszony.
`error`	`string \| undefined`	Komunikat o błędzie, gdy stan to `'error'`.
`agentName`	`string \| undefined`	Nazwa wyświetlana połączonego agenta.
`audioLevel`	`number`	Przestarzałe -- zawsze `0`. Statyczny symbol zastępczy zachowany dla kompatybilności wstecznej; nigdy się nie aktualizuje. Zamiast tego odczytuj `audioLevelRef.current`.
`audioLevelRef`	`React.RefObject<number>`	Modyfikowalny ref zawierający poziom dźwięku w czasie rzeczywistym (0--1) -- wyższy z poziomów głosu agenta i mikrofonu odwiedzającego -- aktualizowany w każdej klatce animacji, poza cyklem renderowania Reacta. Odczytuj `audioLevelRef.current` wewnątrz pętli `requestAnimationFrame`, aby uzyskać płynne animacje bez zacięć, lub próbkuj go w interwałach, gdy potrzebujesz wartości w stanie Reacta.
`audio`	`ReactNode`	Niewidoczny element obsługujący połączenie audio -- musi zostać wyrenderowany.

Interfejs reagujący na dźwięk

Referencja audioLevelRef udostępnia poziomy dźwięku z częstotliwością odświeżania klatek bez wywoływania ponownych renderowań Reacta, dzięki czemu idealnie nadaje się do płynnych wizualizacji fali dźwiękowej, pulsujących kul lub dowolnych animacji powiązanych z rozmową. Poziom odzwierciedla głośniejsze źródło: głos agenta lub mikrofon rozmówcy.

Przykład fali dźwiękowej

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

Przykład pulsującej kuli

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

Przykład wskaźnika mówienia

W przypadku interfejsu renderowanego przez Reacta, który zmienia się wraz z głośnością — na przykład etykiety „mówienie” opartej na progu — odczytuj audioLevelRef.current w interwałach i zapisuj wynik w stanie:

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

Maszyna stanów

Właściwość state ma następujący cykl życia:

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

Stan	Opis
`idle`	Brak aktywnej sesji. Gotowe do wywołania `connect()`.
`connecting`	Sesja jest nawiązywana. W tym stanie wyłącz przycisk połączenia.
`connected`	Sesja głosowa jest aktywna. Użytkownik rozmawia z agentem.
`disconnected`	Sesja zakończyła się poprawnie. Po 1,5 sekundy automatycznie przechodzi z powrotem do `idle`.
`error`	Coś poszło nie tak. Sprawdź komunikat w `phone.error`. Stan nie jest czyszczony automatycznie — ponowne wywołanie `connect()` rozpoczyna nową próbę i resetuje błąd.

Przykłady

Ze sterowaniem wyciszeniem

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

Z dzwonkiem

Odtwarzaj dźwięk dzwonienia podczas łączenia, aby symulować połączenie telefoniczne:

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

Dzwonek jest odtwarzany w pętli w stanie connecting i stopniowo cichnie, gdy agent się połączy. Przekaż true, aby użyć wbudowanego domyślnego dzwonka, lub ciąg URL, aby użyć własnego pliku audio.

Z wywołaniami zwrotnymi zdarzeń

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

W pełni niestandardowy interfejs

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

Wskazówki

Zawsze renderuj phone.audio

Element phone.audio jest niewidoczny, ale wymagany. Umieść go w dowolnym miejscu w JSX -- nie renderuje widocznego DOM, lecz wewnętrznie zarządza połączeniem audio WebRTC.

Wyłącz przycisk podczas łączenia

Stan connecting może trwać 1–3 sekundy. Wyłącz przycisk połączenia w tym stanie, aby zapobiec zduplikowanym próbom połączenia.

Prawidłowo obsłuż stan błędu

Gdy stan to error, wyświetl użytkownikowi phone.error i pozostaw włączony przycisk połączenia. Hook nie opuszcza samodzielnie stanu error -- ponowne wywołanie connect() rozpoczyna nową próbę i usuwa poprzedni błąd.

Używaj callbacków do efektów ubocznych

Callbacki onConnect, onDisconnect i onError są idealne do analityki, rejestrowania zdarzeń lub uruchamiania innej logiki aplikacji bez odpytywania stanu.

Odczytuj poziomy dźwięku z audioLevelRef

audioLevelRef jest jedynym źródłem poziomu dźwięku na żywo. Odczytuj audioLevelRef.current wewnątrz requestAnimationFrame, aby uzyskać płynne animacje, takie jak przebiegi falowe (odczyt refa nie powoduje ponownego renderowania), lub próbkuj go w interwałach i zapisuj wynik w stanie dla interfejsu renderowanego przez React. Liczba audioLevel jest przestarzała i zawsze ma wartość 0 -- nie opieraj na niej logiki.