Hook headless - ThunderPhone

L’hook useThunderPhone ti offre il controllo completo sull’interfaccia utente mentre ThunderPhone gestisce la sessione vocale, il routing audio e lo stato della connessione. Usalo quando vuoi una UI completamente personalizzata — con pulsanti, layout, animazioni e branding propri — mentre ThunderPhone gestisce tutto dietro le quinte.

Quando usare l’hook Headless

Il componente predefinito ThunderPhoneWidget copre la maggior parte dei casi d’uso, ma usa l’hook headless quando ti serve:

Un’interfaccia di chiamata completamente personalizzata che corrisponda al design system della tua app
Visualizzazioni reattive all’audio (forme d’onda, sfere, indicatori pulsanti) basate sui livelli audio in tempo reale
Flussi di chiamata personalizzati, come moduli prima della chiamata, sondaggi dopo la chiamata o chat inline accanto alla voce
Integrazione in una libreria di componenti esistente (Material UI, Chakra, Radix, ecc.)

Installazione

npm install @thunderphone/widget

L’hook headless non richiede l’importazione di @thunderphone/widget/style.css, poiché fornisci la tua UI. Devi comunque installare lo stesso pacchetto @thunderphone/widget.

Utilizzo di base

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

Devi eseguire il rendering di phone.audio in un punto qualsiasi dell’albero dei componenti. È un elemento React invisibile che gestisce la connessione audio sottostante. Se lo ometti, l’audio non verrà riprodotto e la sessione non funzionerà.

Opzioni

Passa queste opzioni a useThunderPhone tramite UseThunderPhoneOptions:

Opzione	Tipo	Obbligatorio	Predefinito	Descrizione
`publishableKey`	`string`	Sì	—	Chiave API pubblicabile (`pk_live_...`). L’agente viene risolto automaticamente dalla configurazione del widget della chiave.
`apiBase`	`string`	No	`'https://api.thunderphone.com/v1'`	Sostituzione dell’URL di base dell’API.
`language`	`string`	No	—	Sostituzione della lingua per sessione — un codice lingua o una lingua locale come `en`, `es` o `fr-FR`. Se non impostata, viene applicata la lingua configurata dell’agente.
`voice`	`string`	No	—	Sostituzione della voce per sessione — un nome di voce come `maria`. Se non impostata, viene applicata la voce configurata dell’agente.
`context`	`string`	No	—	Contesto fattuale della pagina o del sito per sessione passato all’agente. Troncato lato server a 12.000 caratteri.
`onConnect`	`() => void`	No	—	Chiamata quando la sessione vocale si connette.
`onDisconnect`	`() => void`	No	—	Chiamata al termine della sessione.
`onError`	`(error) => void`	No	—	Chiamata in caso di errori. L’errore ha i campi `error` (codice) e `message`.
`ringtone`	`boolean \| string`	No	`false`	Riproduce una suoneria durante la connessione. `true` per la suoneria predefinita oppure una stringa URL per un audio personalizzato.

L’hook è headless: non accetta le proprietà di aspetto di ThunderPhoneWidget (theme, primaryColor, title, position, className). Passarle genera un errore TypeScript — la presentazione è interamente tua da creare.

Valore restituito

L’hook restituisce un oggetto UseThunderPhoneReturn:

Proprietà	Tipo	Descrizione
`state`	`'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'`	Stato attuale della connessione.
`connect`	`() => void`	Avvia una sessione vocale.
`disconnect`	`() => void`	Termina la sessione corrente.
`toggleMute`	`() => void`	Attiva o disattiva il silenziamento del microfono.
`isMuted`	`boolean`	Indica se il microfono è attualmente silenziato.
`error`	`string \| undefined`	Messaggio di errore quando lo stato è `'error'`.
`agentName`	`string \| undefined`	Nome visualizzato dell’agente connesso.
`audioLevel`	`number`	Deprecato — sempre `0`. Un segnaposto statico mantenuto per la retrocompatibilità; non si aggiorna mai. Leggi invece `audioLevelRef.current`.
`audioLevelRef`	`React.RefObject<number>`	Un ref mutabile che contiene il livello audio in tempo reale (0—1) — il più alto tra la voce dell’agente e il microfono del visitatore — aggiornato a ogni frame di animazione, al di fuori del ciclo di rendering di React. Leggi `audioLevelRef.current` all’interno dei loop `requestAnimationFrame` per animazioni fluide e senza scatti, oppure campionalo a intervalli quando ti serve il valore nello stato di React.
`audio`	`ReactNode`	Elemento invisibile che gestisce la connessione audio — deve essere renderizzato.

Interfaccia utente reattiva all’audio

La ref audioLevelRef fornisce livelli audio al frame rate senza attivare nuovi rendering di React, risultando ideale per visualizzazioni di forme d’onda fluide, sfere pulsanti o qualsiasi animazione collegata alla conversazione. Il livello riflette la sorgente più alta tra la voce dell’agente e il microfono del visitatore.

Esempio di forma d’onda

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

Esempio di sfera pulsante

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

Esempio di indicatore di conversazione

Per un’interfaccia utente renderizzata da React che cambia in base al volume — ad esempio un badge “sta parlando” basato su una soglia — campiona audioLevelRef.current a intervalli e salva il risultato nello stato:

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

Leggi sempre i livelli da audioLevelRef.current. Il numero audioLevel nell’oggetto restituito è deprecato e sempre 0 — qualsiasi logica basata su di esso leggerà silenziosamente zero.

Macchina a stati

La proprietà state segue questo ciclo di vita:

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

Stato	Descrizione
`idle`	Nessuna sessione attiva. Pronto a chiamare `connect()`.
`connecting`	La sessione è in fase di avvio. Disabilita il pulsante di chiamata durante questo stato.
`connected`	La sessione vocale è attiva. L’utente sta parlando con l’agente.
`disconnected`	La sessione si è conclusa correttamente. Torna automaticamente a `idle` dopo 1,5 secondi.
`error`	Si è verificato un problema. Controlla `phone.error` per il messaggio. Lo stato non si cancella da solo — chiamare di nuovo `connect()` avvia un nuovo tentativo e reimposta l’errore.

Esempi

Con controllo del microfono

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

Con suoneria

Riproduci un suono di squillo durante la connessione per simulare una chiamata telefonica:

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

La suoneria viene riprodotta in loop durante lo stato connecting e sfuma quando l’agente si connette. Passa true per usare la suoneria predefinita integrata oppure una stringa URL per usare il tuo file audio.

Con callback degli eventi

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

Interfaccia utente completamente personalizzata

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

Suggerimenti

Esegui sempre il rendering di phone.audio

L’elemento phone.audio è invisibile ma obbligatorio. Inseriscilo ovunque nel tuo JSX — non esegue il rendering di alcun DOM visibile, ma gestisce internamente la connessione audio WebRTC.

Disabilita il pulsante durante la connessione

Lo stato connecting può durare 1-3 secondi. Disabilita il pulsante di chiamata durante questo stato per evitare tentativi di connessione duplicati.

Gestisci correttamente lo stato di errore

Quando lo stato è error, mostra phone.error all’utente e mantieni abilitato il pulsante di chiamata. L’hook non esce autonomamente dallo stato error — chiamare di nuovo connect() avvia un nuovo tentativo e cancella l’errore precedente.

Usa i callback per gli effetti collaterali

I callback onConnect, onDisconnect e onError sono ideali per analisi, registrazione dei log o per attivare altra logica dell’applicazione senza eseguire il polling dello stato.

Leggi i livelli audio da audioLevelRef

audioLevelRef è l’unica fonte live dei livelli audio. Leggi audioLevelRef.current all’interno di requestAnimationFrame per animazioni fluide come le forme d’onda (la lettura di una ref non causa nuovi rendering), oppure campionalo a intervalli e memorizza il risultato nello stato per un’interfaccia utente renderizzata da React. Il numero audioLevel è deprecato ed è sempre 0 — non basare alcuna logica su di esso.

​Quando usare l’hook Headless

​Installazione

​Utilizzo di base

​Opzioni

​Valore restituito

​Interfaccia utente reattiva all’audio

​Esempio di forma d’onda

​Esempio di sfera pulsante

​Esempio di indicatore di conversazione

​Macchina a stati

​Esempi

​Con controllo del microfono

​Con suoneria

​Con callback degli eventi

​Interfaccia utente completamente personalizzata

​Suggerimenti

Quando usare l’hook Headless

Installazione

Utilizzo di base

Opzioni

Valore restituito

Interfaccia utente reattiva all’audio

Esempio di forma d’onda

Esempio di sfera pulsante

Esempio di indicatore di conversazione

Macchina a stati

Esempi

Con controllo del microfono

Con suoneria

Con callback degli eventi

Interfaccia utente completamente personalizzata

Suggerimenti