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

> 使用 useThunderPhone React Hook 构建完全自定义的语音 UI

`useThunderPhone` Hook 让您能够完全掌控用户界面，同时由 ThunderPhone 管理语音会话、音频路由和连接状态。当您需要完全自定义的 UI——包括自己的按钮、布局、动画和品牌风格——同时希望 ThunderPhone 在底层处理一切时，请使用它。

## 何时使用无头 Hook

预构建的 `ThunderPhoneWidget` 组件可满足大多数使用场景，但在您需要以下功能时，应使用无头 Hook：

* 与您的应用设计系统匹配的完全自定义通话 UI
* 由实时音频电平驱动的音频响应式可视化效果（波形、光球、脉冲指示器）
* 自定义通话流程，例如通话前表单、通话后问卷，或与语音并列的内嵌聊天
* 集成到现有组件库中（Material UI、Chakra、Radix 等）

***

## 安装

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

<Note>
  由于您需要提供自己的 UI，无头 Hook **不**要求导入 `@thunderphone/widget/style.css`。不过，您仍必须安装相同的 `@thunderphone/widget` 包。
</Note>

***

## 基本用法

```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>
  \*\*您必须在组件树中的某处渲染 `phone.audio`。\*\*它是一个不可见的 React 元素，用于管理底层音频连接。如果省略它，将不会播放音频，且会话无法正常工作。
</Warning>

***

## 选项

通过 `UseThunderPhoneOptions` 将以下选项传递给 `useThunderPhone`：

| 选项               | 类型                  | 必填 | 默认值                                 | 描述                                                          |
| ---------------- | ------------------- | -- | ----------------------------------- | ----------------------------------------------------------- |
| `publishableKey` | `string`            | 是  | --                                  | 可发布 API 密钥（`pk_live_...`）。系统会根据该密钥的组件配置自动解析智能体。             |
| `apiBase`        | `string`            | 否  | `'https://api.thunderphone.com/v1'` | 覆盖 API 基础 URL。                                              |
| `language`       | `string`            | 否  | --                                  | 按会话覆盖语言——语言代码或区域设置，例如 `en`、`es` 或 `fr-FR`。未设置时，将应用智能体配置的语言。 |
| `voice`          | `string`            | 否  | --                                  | 按会话覆盖语音——语音名称，例如 `maria`。未设置时，将应用智能体配置的语音。                  |
| `context`        | `string`            | 否  | --                                  | 按会话传递给智能体的事实性页面或网站上下文。服务端会将其截断为 12,000 个字符。                 |
| `onConnect`      | `() => void`        | 否  | --                                  | 语音会话连接时调用。                                                  |
| `onDisconnect`   | `() => void`        | 否  | --                                  | 会话结束时调用。                                                    |
| `onError`        | `(error) => void`   | 否  | --                                  | 发生错误时调用。错误包含 `error`（代码）和 `message` 字段。                     |
| `ringtone`       | `boolean \| string` | 否  | `false`                             | 连接期间播放铃声。使用 `true` 播放默认铃声，或使用 URL 字符串指定自定义音频。               |

<Note>
  此 Hook 为无头 Hook：它**不**接受 `ThunderPhoneWidget` 的外观属性（`theme`、`primaryColor`、`title`、`position`、`className`）。传入这些属性会导致 TypeScript 错误——界面呈现完全由您构建。
</Note>

***

## 返回值

该 Hook 返回一个 `UseThunderPhoneReturn` 对象：

| 属性              | 类型                                                                   | 描述                                                                                                                                                                         |
| --------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`         | `'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'` | 当前连接状态。                                                                                                                                                                    |
| `connect`       | `() => void`                                                         | 开始语音会话。                                                                                                                                                                    |
| `disconnect`    | `() => void`                                                         | 结束当前会话。                                                                                                                                                                    |
| `toggleMute`    | `() => void`                                                         | 切换麦克风静音状态。                                                                                                                                                                 |
| `isMuted`       | `boolean`                                                            | 麦克风当前是否处于静音状态。                                                                                                                                                             |
| `error`         | `string \| undefined`                                                | 当状态为 `'error'` 时的错误消息。                                                                                                                                                     |
| `agentName`     | `string \| undefined`                                                | 已连接智能体的显示名称。                                                                                                                                                               |
| `audioLevel`    | `number`                                                             | **已弃用——始终为 `0`。** 为保持向后兼容而保留的静态占位符；它不会更新。请改为读取 `audioLevelRef.current`。                                                                                                    |
| `audioLevelRef` | `React.RefObject<number>`                                            | 包含实时音频级别（0--1）的可变 ref——取智能体语音和访客麦克风中较响的一方——在每个动画帧更新，位于 React 渲染周期之外。为实现流畅、无卡顿的动画，请在 `requestAnimationFrame` 循环内读取 `audioLevelRef.current`；当您需要在 React 状态中使用该值时，请按固定时间间隔采样。 |
| `audio`         | `ReactNode`                                                          | 处理音频连接的不可见元素——**必须渲染**。                                                                                                                                                    |

***

## 音频响应式 UI

`audioLevelRef` ref 可为您提供帧率级别的音频音量，而不会触发 React 重新渲染，因此非常适合驱动流畅的波形可视化、脉冲光球或任何与对话关联的动画。该音量反映语音智能体声音和访客麦克风中音量较高的一方。

### 波形示例

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

### 脉冲光球示例

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

### 说话状态指示器示例

对于会随音量变化的 React 渲染 UI——例如基于阈值的“说话中”徽章——请按固定间隔读取 `audioLevelRef.current`，并将结果存储在状态中：

```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>
  始终从 `audioLevelRef.current` 读取音量。返回对象上的 `audioLevel` 数值<strong>已弃用且始终为 `0`</strong>——任何基于它构建的逻辑都会在无提示的情况下读取到零。
</Warning>

***

## 状态机

`state` 属性遵循以下生命周期：

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

| 状态             | 描述                                                                          |
| -------------- | --------------------------------------------------------------------------- |
| `idle`         | 没有活动会话。可以调用 `connect()`。                                                    |
| `connecting`   | 正在建立会话。在此状态期间禁用呼叫按钮。                                                        |
| `connected`    | 语音会话处于活动状态。用户正在与智能体交谈。                                                      |
| `disconnected` | 会话已正常结束。1.5 秒后自动转换回 `idle`。                                                 |
| `error`        | 出现问题。请查看 `phone.error` 获取错误消息。该状态**不会**自行清除——再次调用 `connect()` 会发起新的尝试并重置错误。 |

***

## 示例

### 使用静音控制

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

### 使用铃声

在连接期间播放响铃声，以模拟电话呼叫：

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

铃声会在 `connecting` 状态期间循环播放，并在智能体接通时淡出。传入 `true` 可使用内置默认铃声，或传入 URL 字符串以使用您自己的音频文件。

### 使用事件回调

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

### 完全自定义 UI

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

***

## 提示

<AccordionGroup>
  <Accordion title="始终渲染 phone.audio">
    `phone.audio` 元素不可见，但必不可少。将其放在 JSX 中的任意位置——它不会渲染可见的 DOM，但会在内部管理 WebRTC 音频连接。
  </Accordion>

  <Accordion title="连接时禁用按钮">
    `connecting` 状态可能持续 1-3 秒。在此状态期间禁用通话按钮，以防止重复连接尝试。
  </Accordion>

  <Accordion title="妥善处理错误状态">
    当状态为 `error` 时，向用户显示 `phone.error`，并保持通话按钮可用。该 Hook 不会自行离开 `error` 状态——再次调用 `connect()` 会发起新的尝试并清除之前的错误。
  </Accordion>

  <Accordion title="使用回调处理副作用">
    `onConnect`、`onDisconnect` 和 `onError` 回调非常适合用于分析、日志记录，或触发其他应用逻辑，而无需轮询状态。
  </Accordion>

  <Accordion title="从 audioLevelRef 读取音频级别">
    `audioLevelRef` 是唯一的实时音频级别来源。对于波形等流畅动画，请在 `requestAnimationFrame` 中读取 `audioLevelRef.current`（读取 ref 不会导致重新渲染）；或者按固定间隔采样并将结果存储在状态中，以用于由 React 渲染的 UI。`audioLevel` 数值已弃用，且始终为 `0`——请勿基于它构建逻辑。
  </Accordion>
</AccordionGroup>