> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hook headless

> Crea un'interfaccia vocale completamente personalizzata con l'hook React useThunderPhone

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

```bash theme={null}
npm install @thunderphone/widget
```

<Note>
  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`.
</Note>

***

## Utilizzo di base

```tsx theme={null}
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}
    </>
  )
}
```

<Warning>
  **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à.
</Warning>

***

## 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.                                          |

<Note>
  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.
</Note>

***

## 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

```tsx theme={null}
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

```tsx theme={null}
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:

```tsx theme={null}
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>
  )
}
```

<Warning>
  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.
</Warning>

***

## 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

```tsx theme={null}
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:

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>