---
title: "Headless Hook"
description: "สร้าง UI เสียงแบบกำหนดเองได้อย่างเต็มรูปแบบด้วย React hook useThunderPhone"
---

ฮุก `useThunderPhone` ช่วยให้คุณควบคุมอินเทอร์เฟซผู้ใช้ได้อย่างสมบูรณ์ ขณะที่ ThunderPhone จัดการเซสชันเสียง การกำหนดเส้นทางเสียง และสถานะการเชื่อมต่อ ใช้ฮุกนี้เมื่อคุณต้องการ UI ที่ปรับแต่งได้ทั้งหมด -- ปุ่ม เลย์เอาต์ แอนิเมชัน และแบรนด์ของคุณเอง -- โดยให้ ThunderPhone จัดการทุกอย่างเบื้องหลัง

## เมื่อควรใช้ Headless Hook

คอมโพเนนต์ `ThunderPhoneWidget` ที่สร้างไว้ล่วงหน้าครอบคลุมกรณีใช้งานส่วนใหญ่ แต่ให้ใช้ headless hook เมื่อคุณต้องการ:

- UI สำหรับการโทรที่ปรับแต่งได้ทั้งหมดและสอดคล้องกับระบบการออกแบบของแอป
- ภาพแสดงผลที่ตอบสนองต่อเสียง (รูปคลื่น ทรงกลม ตัวบ่งชี้แบบกะพริบ) ที่ขับเคลื่อนด้วยระดับเสียงแบบเรียลไทม์
- โฟลว์การโทรแบบกำหนดเอง เช่น ฟอร์มก่อนโทร แบบสำรวจหลังโทร หรือแชตในบรรทัดควบคู่กับเสียง
- การผสานรวมเข้ากับไลบรารีคอมโพเนนต์ที่มีอยู่ (Material UI, Chakra, Radix เป็นต้น)

---

## การติดตั้ง

```bash
npm install @thunderphone/widget
```

<Note>
  headless hook **ไม่**จำเป็นต้องนำเข้า `@thunderphone/widget/style.css` เนื่องจากคุณเป็นผู้สร้าง UI เอง อย่างไรก็ตาม คุณยังต้องติดตั้งแพ็กเกจ `@thunderphone/widget` เดียวกัน
</Note>

---

## การใช้งานพื้นฐาน

```tsx
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 element ที่มองไม่เห็นซึ่งจัดการการเชื่อมต่อเสียงเบื้องหลัง หากไม่ใส่องค์ประกอบนี้ จะไม่มีเสียงเล่นและเซสชันจะไม่ทำงาน
</Warning>

---

## ตัวเลือก

ส่งตัวเลือกเหล่านี้ไปยัง `useThunderPhone` ผ่าน `UseThunderPhoneOptions`:

| ตัวเลือก | ประเภท | จำเป็น | ค่าเริ่มต้น | คำอธิบาย |
|--------|------|----------|---------|-------------|
| `publishableKey` | `string` | ใช่ | -- | คีย์ API แบบเผยแพร่ได้ (`pk_live_...`) ระบบจะเลือกเอเจนต์โดยอัตโนมัติจากการกำหนดค่า widget ของคีย์ |
| `apiBase` | `string` | ไม่ | `'https://api.thunderphone.com/v1'` | แทนที่ URL ฐานของ API |
| `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>
  ฮุกนี้เป็นแบบ headless: **ไม่**รับพร็อพสำหรับลักษณะที่ปรากฏของ `ThunderPhoneWidget` (`theme`, `primaryColor`, `title`, `position`, `className`) การส่งพร็อพเหล่านี้จะทำให้เกิดข้อผิดพลาด TypeScript -- คุณเป็นผู้สร้างส่วนการนำเสนอทั้งหมดเอง
</Note>

---

## ค่าส่งกลับ

ฮุกจะส่งกลับออบเจ็กต์ `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) -- ค่าที่ดังกว่าระหว่างเสียงของเอเจนต์และไมโครโฟนของผู้เข้าชม -- ซึ่งอัปเดตในทุกเฟรมแอนิเมชัน นอกวงจรการเรนเดอร์ของ React อ่าน `audioLevelRef.current` ภายในลูป `requestAnimationFrame` เพื่อให้แอนิเมชันลื่นไหลไม่กระตุก หรือสุ่มตัวอย่างตามช่วงเวลาเมื่อต้องการค่าในสถานะ React |
| `audio` | `ReactNode` | องค์ประกอบที่มองไม่เห็นซึ่งจัดการการเชื่อมต่อเสียง -- **ต้องเรนเดอร์** |

---

## UI ที่ตอบสนองต่อเสียง

ref `audioLevelRef` ช่วยให้คุณรับระดับเสียงตามเฟรมเรตได้โดยไม่ทริกเกอร์การเรนเดอร์ React ใหม่ จึงเหมาะอย่างยิ่งสำหรับการขับเคลื่อนการแสดงผลรูปคลื่นที่ลื่นไหล ทรงกลมที่เต้นเป็นจังหวะ หรือแอนิเมชันใดก็ตามที่เชื่อมโยงกับการสนทนา ระดับนี้จะสะท้อนเสียงที่ดังกว่า ระหว่างเสียงของเอเจนต์กับไมโครโฟนของผู้เข้าชม

### ตัวอย่างรูปคลื่น

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

### ตัวอย่างตัวบ่งชี้การพูด

สำหรับ UI ที่เรนเดอร์ด้วย React ซึ่งเปลี่ยนแปลงตามระดับเสียง เช่น ป้าย "กำลังพูด" ที่อิงตามค่าเกณฑ์ ให้สุ่มตัวอย่าง `audioLevelRef.current` ตามช่วงเวลาและเก็บผลลัพธ์ไว้ในสถานะ:

```tsx
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` ในออบเจ็กต์ที่ส่งกลับมานั้น **เลิกใช้แล้วและมีค่าเป็น `0` เสมอ** -- ตรรกะใดก็ตามที่สร้างบนค่านี้จะอ่านค่าเป็นศูนย์โดยไม่มีการแจ้งเตือน
</Warning>

---

## สถานะของระบบ

พร็อพเพอร์ตี `state` เป็นไปตามวงจรสถานะดังนี้:

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

| สถานะ | คำอธิบาย |
|-------|-------------|
| `idle` | ไม่มีเซสชันที่กำลังใช้งาน พร้อมเรียก `connect()` |
| `connecting` | กำลังสร้างเซสชัน ปิดใช้งานปุ่มโทรระหว่างสถานะนี้ |
| `connected` | เซสชันเสียงกำลังใช้งาน ผู้ใช้กำลังพูดคุยกับเอเจนต์ |
| `disconnected` | เซสชันสิ้นสุดอย่างสมบูรณ์ ระบบจะเปลี่ยนกลับไปที่ `idle` โดยอัตโนมัติหลังจาก 1.5 วินาที |
| `error` | เกิดข้อผิดพลาด ตรวจสอบข้อความที่ `phone.error` สถานะจะไม่ถูกล้างเอง -- การเรียก `connect()` อีกครั้งจะเริ่มการลองใหม่และรีเซ็ตข้อผิดพลาด |

## ตัวอย่าง

### พร้อมการควบคุมการปิดเสียง

```tsx
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
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
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
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="ใช้ callback สำหรับผลกระทบข้างเคียง">
    callback `onConnect` `onDisconnect` และ `onError` เหมาะอย่างยิ่งสำหรับการวิเคราะห์ การบันทึกล็อก หรือการเรียกใช้ตรรกะแอปพลิเคชันอื่นโดยไม่ต้องตรวจสอบสถานะซ้ำ
  </Accordion>

  <Accordion title="อ่านระดับเสียงจาก audioLevelRef">
    `audioLevelRef` เป็นแหล่งข้อมูลระดับเสียงแบบสดเพียงแหล่งเดียว อ่าน `audioLevelRef.current` ภายใน `requestAnimationFrame` เพื่อสร้างแอนิเมชันที่ลื่นไหล เช่น รูปคลื่น (การอ่าน ref จะไม่ทำให้เกิดการเรนเดอร์ซ้ำ) หรือสุ่มตัวอย่างตามช่วงเวลาและเก็บผลลัพธ์ไว้ใน state สำหรับ UI ที่ React เรนเดอร์ ตัวเลข `audioLevel` เลิกใช้แล้วและมีค่าเป็น `0` เสมอ -- อย่าสร้างตรรกะโดยอิงกับค่านี้
  </Accordion>
</AccordionGroup>