Headless Hook - ThunderPhone

Der Hook useThunderPhone gibt Ihnen vollständige Kontrolle über die Benutzeroberfläche, während ThunderPhone die Sprachsitzung, Audio-Routing und den Verbindungsstatus verwaltet. Verwenden Sie ihn, wenn Sie eine vollständig individuelle UI wünschen — mit eigenen Schaltflächen, Layouts, Animationen und Branding — während ThunderPhone alles im Hintergrund übernimmt.

Wann Sie den Headless-Hook verwenden sollten

Die vorgefertigte Komponente ThunderPhoneWidget deckt die meisten Anwendungsfälle ab. Verwenden Sie den Headless-Hook jedoch, wenn Sie Folgendes benötigen:

Eine vollständig individuelle Anruf-UI, die zum Designsystem Ihrer App passt
Audioreaktive Visualisierungen (Wellenformen, Kugeln, pulsierende Anzeigen), die von Audiopegeln in Echtzeit gesteuert werden
Individuelle Anrufflüsse wie Formulare vor dem Anruf, Umfragen nach dem Anruf oder Inline-Chat neben der Sprachfunktion
Integration in eine bestehende Komponentenbibliothek (Material UI, Chakra, Radix usw.)

Installation

npm install @thunderphone/widget

Der Headless-Hook erfordert nicht den Import von @thunderphone/widget/style.css, da Sie Ihre eigene UI bereitstellen. Sie müssen jedoch weiterhin dasselbe Paket @thunderphone/widget installieren.

Grundlegende Verwendung

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

Sie müssen phone.audio an einer Stelle in Ihrem Komponentenbaum rendern. Es ist ein unsichtbares React-Element, das die zugrunde liegende Audioverbindung verwaltet. Wenn Sie es weglassen, wird kein Audio wiedergegeben und die Sitzung funktioniert nicht.

Optionen

Übergeben Sie diese Optionen über UseThunderPhoneOptions an useThunderPhone:

Option	Typ	Erforderlich	Standard	Beschreibung
`publishableKey`	`string`	Ja	—	Veröffentlichbarer API-Schlüssel (`pk_live_...`). Der Sprachagent wird automatisch anhand der Widget-Konfiguration des Schlüssels bestimmt.
`apiBase`	`string`	Nein	`'https://api.thunderphone.com/v1'`	Überschreibung der API-Basis-URL.
`language`	`string`	Nein	—	Sprachüberschreibung pro Sitzung — ein Sprachcode oder Gebietsschema wie `en`, `es` oder `fr-FR`. Wenn keine Angabe erfolgt, gilt die konfigurierte Sprache des Sprachagenten.
`voice`	`string`	Nein	—	Stimmenüberschreibung pro Sitzung — ein Stimmenname wie `maria`. Wenn keine Angabe erfolgt, gilt die konfigurierte Stimme des Sprachagenten.
`context`	`string`	Nein	—	Faktischer Seiten- oder Website-Kontext pro Sitzung, der an den Sprachagenten übergeben wird. Serverseitig auf 12.000 Zeichen gekürzt.
`onConnect`	`() => void`	Nein	—	Wird aufgerufen, wenn die Sprachsitzung verbunden wird.
`onDisconnect`	`() => void`	Nein	—	Wird aufgerufen, wenn die Sitzung endet.
`onError`	`(error) => void`	Nein	—	Wird bei Fehlern aufgerufen. Error verfügt über die Felder `error` (Code) und `message`.
`ringtone`	`boolean \| string`	Nein	`false`	Einen Klingelton während des Verbindungsaufbaus abspielen. `true` für den Standardklingelton oder eine URL-Zeichenfolge für eigenes Audio.

Der Hook ist Headless: Er akzeptiert nicht die Darstellungs-Props von ThunderPhoneWidget (theme, primaryColor, title, position, className). Die Übergabe dieser Props führt zu einem TypeScript-Fehler — die Darstellung erstellen Sie vollständig selbst.

Rückgabewert

Der Hook gibt ein UseThunderPhoneReturn-Objekt zurück:

Eigenschaft	Typ	Beschreibung
`state`	`'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'`	Aktueller Verbindungsstatus.
`connect`	`() => void`	Startet eine Sprachsitzung.
`disconnect`	`() => void`	Beendet die aktuelle Sitzung.
`toggleMute`	`() => void`	Schaltet die Mikrofonstummschaltung ein oder aus.
`isMuted`	`boolean`	Gibt an, ob das Mikrofon derzeit stummgeschaltet ist.
`error`	`string \| undefined`	Fehlermeldung, wenn der Status `'error'` ist.
`agentName`	`string \| undefined`	Anzeigename des verbundenen Agenten.
`audioLevel`	`number`	Veraltet — immer `0`. Ein statischer Platzhalter für Abwärtskompatibilität; er wird nie aktualisiert. Lesen Sie stattdessen `audioLevelRef.current`.
`audioLevelRef`	`React.RefObject<number>`	Eine veränderbare Ref, die den Audiopegel in Echtzeit (0—1) enthält — den höheren Wert aus der Stimme des Agenten und dem Mikrofon des Besuchers — und bei jedem Animationsframe außerhalb des React-Renderzyklus aktualisiert wird. Lesen Sie `audioLevelRef.current` innerhalb von `requestAnimationFrame`-Schleifen für flüssige Animationen ohne Ruckler, oder fragen Sie den Wert in einem Intervall ab, wenn Sie ihn im React-Status benötigen.
`audio`	`ReactNode`	Unsichtbares Element, das die Audioverbindung verarbeitet — muss gerendert werden.

Audioreaktive UI

Die Ref audioLevelRef liefert Ihnen Audiopegel mit Bildrate, ohne React-Neurenderings auszulösen. Dadurch eignet sie sich ideal für flüssige Wellenformvisualisierungen, pulsierende Kugeln oder jede Animation, die an die Unterhaltung gekoppelt ist. Der Pegel entspricht jeweils der lauteren Quelle: der Stimme des Agenten oder dem Mikrofon des Besuchers.

Wellenformbeispiel

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

Beispiel für eine pulsierende Kugel

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

Beispiel für eine Sprechindikator

Für eine von React gerenderte UI, die sich mit der Lautstärke ändert – etwa ein schwellenwertbasierter Badge für „spricht“ –, lesen Sie audioLevelRef.current in einem Intervall aus und speichern Sie das Ergebnis im State:

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

Lesen Sie Pegel immer aus audioLevelRef.current. Die Zahl audioLevel im Rückgabeobjekt ist veraltet und immer 0 – jede darauf basierende Logik liest stillschweigend null.

Zustandsautomat

Die Eigenschaft state durchläuft diesen Lebenszyklus:

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

Status	Beschreibung
`idle`	Keine aktive Sitzung. Bereit zum Aufruf von `connect()`.
`connecting`	Die Sitzung wird hergestellt. Deaktivieren Sie während dieses Status die Anruftaste.
`connected`	Die Sprachsitzung ist aktiv. Der Benutzer spricht mit dem Agenten.
`disconnected`	Die Sitzung wurde ordnungsgemäß beendet. Wechselt nach 1,5 Sekunden automatisch zurück zu `idle`.
`error`	Ein Fehler ist aufgetreten. Prüfen Sie `phone.error` auf die Meldung. Der Status wird nicht automatisch zurückgesetzt — ein erneuter Aufruf von `connect()` startet einen neuen Versuch und setzt den Fehler zurück.

Beispiele

Mit Stummschaltfunktion

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

Mit Klingelton

Spielen Sie während des Verbindungsaufbaus einen Klingelton ab, um einen Telefonanruf zu simulieren:

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

Der Klingelton wird während des Status connecting wiederholt und ausgeblendet, wenn der Agent verbunden ist. Übergeben Sie true für den integrierten Standardklingelton oder einen URL-String, um Ihre eigene Audiodatei zu verwenden.

Mit Ereignis-Callbacks

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

Vollständig benutzerdefinierte 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>
  )
}

Tipps

phone.audio immer rendern

Das Element phone.audio ist unsichtbar, aber erforderlich. Platzieren Sie es an einer beliebigen Stelle in Ihrem JSX — es rendert kein sichtbares DOM, verwaltet jedoch intern die WebRTC-Audioverbindung.

Die Schaltfläche während der Verbindung deaktivieren

Der Status connecting kann 1–3 Sekunden dauern. Deaktivieren Sie während dieses Status die Anrufschaltfläche, um doppelte Verbindungsversuche zu verhindern.

Den Fehlerstatus angemessen behandeln

Wenn der Status error ist, zeigen Sie dem Benutzer phone.error an und lassen Sie Ihre Anrufschaltfläche aktiviert. Der Hook verlässt den Status error nicht selbstständig — ein erneuter Aufruf von connect() startet einen neuen Versuch und löscht den vorherigen Fehler.

Callbacks für Seiteneffekte verwenden

Die Callbacks onConnect, onDisconnect und onError eignen sich ideal für Analysen, Protokollierung oder zum Auslösen anderer Anwendungslogik, ohne den Status abzufragen.

Audiopegel aus audioLevelRef lesen

audioLevelRef ist die einzige Live-Quelle für Audiopegel. Lesen Sie audioLevelRef.current innerhalb von requestAnimationFrame für flüssige Animationen wie Wellenformen aus (das Lesen einer Ref verursacht keine erneuten Renderings), oder fragen Sie sie in einem Intervall ab und speichern Sie das Ergebnis im Status für von React gerenderte UI. Die Zahl audioLevel ist veraltet und immer 0 — bauen Sie keine Logik darauf auf.

​Wann Sie den Headless-Hook verwenden sollten

​Installation

​Grundlegende Verwendung

​Optionen

​Rückgabewert

​Audioreaktive UI

​Wellenformbeispiel

​Beispiel für eine pulsierende Kugel

​Beispiel für eine Sprechindikator

​Zustandsautomat

​Beispiele

​Mit Stummschaltfunktion

​Mit Klingelton

​Mit Ereignis-Callbacks

​Vollständig benutzerdefinierte UI

​Tipps

Wann Sie den Headless-Hook verwenden sollten

Installation

Grundlegende Verwendung

Optionen

Rückgabewert

Audioreaktive UI

Wellenformbeispiel

Beispiel für eine pulsierende Kugel

Beispiel für eine Sprechindikator

Zustandsautomat

Beispiele

Mit Stummschaltfunktion

Mit Klingelton

Mit Ereignis-Callbacks

Vollständig benutzerdefinierte UI

Tipps