Headless Hook - ThunderPhone

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

Hook bez interfejsu nie wymaga importowania @thunderphone/widget/style.css, ponieważ tworzysz własny interfejs. Musisz jednak nadal zainstalować ten sam pakiet @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}
    </>
  )
}

Musisz wyrenderować phone.audio w dowolnym miejscu drzewa komponentów. To niewidoczny element React, który zarządza bazowym połączeniem audio. Jeśli go pominiesz, dźwięk nie będzie odtwarzany, a sesja nie będzie działać.

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.

Hook jest bez interfejsu: nie akceptuje właściwości wyglądu ThunderPhoneWidget (theme, primaryColor, title, position, className). Przekazanie ich powoduje błąd TypeScript — prezentację tworzysz w całości samodzielnie.

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

Zawsze odczytuj poziomy z audioLevelRef.current. Liczba audioLevel w obiekcie zwracanym jest przestarzała i zawsze ma wartość 0 — każda logika oparta na niej będzie bezgłośnie odczytywać zero.

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.

​Kiedy używać hooka bez interfejsu

​Instalacja

​Podstawowe użycie

​Opcje

​Wartość zwracana

​Interfejs reagujący na dźwięk

​Przykład fali dźwiękowej

​Przykład pulsującej kuli

​Przykład wskaźnika mówienia

​Maszyna stanów

​Przykłady

​Ze sterowaniem wyciszeniem

​Z dzwonkiem

​Z wywołaniami zwrotnymi zdarzeń

​W pełni niestandardowy interfejs

​Wskazówki

Kiedy używać hooka bez interfejsu

Instalacja

Podstawowe użycie

Opcje

Wartość zwracana

Interfejs reagujący na dźwięk

Przykład fali dźwiękowej

Przykład pulsującej kuli

Przykład wskaźnika mówienia

Maszyna stanów

Przykłady

Ze sterowaniem wyciszeniem

Z dzwonkiem

Z wywołaniami zwrotnymi zdarzeń

W pełni niestandardowy interfejs

Wskazówki