Headless Hook - ThunderPhone

Hook useThunderPhone cho phép bạn kiểm soát hoàn toàn giao diện người dùng, trong khi ThunderPhone quản lý phiên thoại, định tuyến âm thanh và trạng thái kết nối. Sử dụng hook này khi bạn muốn có UI tùy chỉnh hoàn toàn — với các nút, bố cục, hiệu ứng động và thương hiệu riêng — trong khi ThunderPhone xử lý mọi thứ phía sau.

Khi nào nên sử dụng Hook không giao diện

Component ThunderPhoneWidget dựng sẵn đáp ứng hầu hết trường hợp sử dụng, nhưng hãy dùng hook không giao diện khi bạn cần:

UI cuộc gọi tùy chỉnh hoàn toàn, phù hợp với hệ thống thiết kế của ứng dụng
Hình ảnh trực quan phản ứng theo âm thanh (dạng sóng, quả cầu, chỉ báo nhấp nháy) được điều khiển bởi mức âm thanh theo thời gian thực
Luồng cuộc gọi tùy chỉnh như biểu mẫu trước cuộc gọi, khảo sát sau cuộc gọi hoặc chat nội tuyến cùng với thoại
Tích hợp vào thư viện component hiện có (Material UI, Chakra, Radix, v.v.)

Cài đặt

npm install @thunderphone/widget

Hook không giao diện không yêu cầu import @thunderphone/widget/style.css vì bạn tự cung cấp UI. Tuy nhiên, bạn vẫn phải cài đặt cùng package @thunderphone/widget.

Cách sử dụng cơ bản

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

Bạn phải render phone.audio ở đâu đó trong cây component của mình. Đây là một phần tử React vô hình quản lý kết nối âm thanh nền tảng. Nếu bỏ qua, âm thanh sẽ không phát và phiên sẽ không hoạt động.

Tùy chọn

Truyền các tùy chọn này vào useThunderPhone thông qua UseThunderPhoneOptions:

Tùy chọn	Kiểu	Bắt buộc	Mặc định	Mô tả
`publishableKey`	`string`	Có	—	API key có thể công khai (`pk_live_...`). Tác nhân AI được xác định tự động từ cấu hình widget của key.
`apiBase`	`string`	Không	`'https://api.thunderphone.com/v1'`	Ghi đè URL cơ sở API.
`language`	`string`	Không	—	Ghi đè ngôn ngữ theo từng phiên — mã ngôn ngữ hoặc locale như `en`, `es` hoặc `fr-FR`. Khi không đặt, ngôn ngữ đã cấu hình của tác nhân AI sẽ được áp dụng.
`voice`	`string`	Không	—	Ghi đè giọng nói theo từng phiên — tên giọng nói như `maria`. Khi không đặt, giọng nói đã cấu hình của tác nhân AI sẽ được áp dụng.
`context`	`string`	Không	—	Ngữ cảnh thực tế của trang hoặc website theo từng phiên được truyền đến tác nhân AI. Được cắt ngắn phía máy chủ xuống còn 12.000 ký tự.
`onConnect`	`() => void`	Không	—	Được gọi khi phiên thoại kết nối.
`onDisconnect`	`() => void`	Không	—	Được gọi khi phiên kết thúc.
`onError`	`(error) => void`	Không	—	Được gọi khi xảy ra lỗi. Lỗi có các trường `error` (mã) và `message`.
`ringtone`	`boolean \| string`	Không	`false`	Phát nhạc chuông trong khi kết nối. `true` dùng nhạc chuông mặc định, hoặc chuỗi URL cho âm thanh tùy chỉnh.

Hook này không giao diện: nó không chấp nhận các prop về giao diện của ThunderPhoneWidget (theme, primaryColor, title, position, className). Truyền các prop này sẽ gây lỗi TypeScript — phần trình bày hoàn toàn do bạn xây dựng.

Giá trị trả về

Hook trả về một đối tượng UseThunderPhoneReturn:

Thuộc tính	Loại	Mô tả
`state`	`'idle' \| 'connecting' \| 'connected' \| 'disconnected' \| 'error'`	Trạng thái kết nối hiện tại.
`connect`	`() => void`	Bắt đầu phiên thoại.
`disconnect`	`() => void`	Kết thúc phiên hiện tại.
`toggleMute`	`() => void`	Bật/tắt chế độ tắt tiếng microphone.
`isMuted`	`boolean`	Cho biết microphone hiện đang bị tắt tiếng hay không.
`error`	`string \| undefined`	Thông báo lỗi khi trạng thái là `'error'`.
`agentName`	`string \| undefined`	Tên hiển thị của tác nhân AI đã kết nối.
`audioLevel`	`number`	Đã ngừng hỗ trợ — luôn là `0`. Đây là giá trị giữ chỗ tĩnh để tương thích ngược; giá trị này không bao giờ cập nhật. Thay vào đó, hãy đọc `audioLevelRef.current`.
`audioLevelRef`	`React.RefObject<number>`	Một ref có thể thay đổi chứa mức âm thanh theo thời gian thực (0—1) — mức lớn hơn giữa giọng nói của tác nhân AI và microphone của khách truy cập — được cập nhật ở mỗi khung hình hoạt ảnh, bên ngoài chu kỳ render của React. Đọc `audioLevelRef.current` trong các vòng lặp `requestAnimationFrame` để có hoạt ảnh mượt mà, không giật, hoặc lấy mẫu theo khoảng thời gian khi bạn cần giá trị trong state của React.
`audio`	`ReactNode`	Phần tử vô hình xử lý kết nối âm thanh — bắt buộc phải render.

Giao diện phản hồi theo âm thanh

Ref audioLevelRef cung cấp mức âm thanh theo tốc độ khung hình mà không kích hoạt React render lại, nên rất phù hợp để điều khiển trực quan hóa dạng sóng mượt mà, các quả cầu nhấp nhô hoặc bất kỳ hoạt ảnh nào gắn với cuộc trò chuyện. Mức này phản ánh âm thanh nào lớn hơn: giọng nói của tác nhân AI hoặc microphone của khách truy cập.

Ví dụ dạng sóng

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

Ví dụ quả cầu nhấp nhô

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

Ví dụ chỉ báo đang nói

Đối với giao diện được React render thay đổi theo âm lượng — chẳng hạn như nhãn “đang nói” dựa trên ngưỡng — hãy lấy mẫu audioLevelRef.current theo một khoảng thời gian và lưu kết quả vào 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>
  )
}

Luôn đọc mức từ audioLevelRef.current. Số audioLevel trên đối tượng trả về đã không còn được dùng và luôn là 0 — mọi logic xây dựng dựa trên nó sẽ âm thầm đọc giá trị bằng không.

Máy trạng thái

Thuộc tính state tuân theo vòng đời sau:

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

Trạng thái	Mô tả
`idle`	Không có phiên hoạt động. Sẵn sàng gọi `connect()`.
`connecting`	Phiên đang được thiết lập. Vô hiệu hóa nút gọi trong trạng thái này.
`connected`	Phiên thoại đang hoạt động. Người dùng đang nói chuyện với tác nhân AI.
`disconnected`	Phiên đã kết thúc bình thường. Tự động chuyển lại `idle` sau 1,5 giây.
`error`	Đã xảy ra lỗi. Kiểm tra `phone.error` để xem thông báo. Trạng thái này không tự xóa — việc gọi lại `connect()` sẽ bắt đầu một lần thử mới và đặt lại lỗi.

Ví dụ

Với điều khiển tắt tiếng

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

Với nhạc chuông

Phát âm thanh đổ chuông trong khi kết nối để mô phỏng cuộc gọi điện thoại:

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

Nhạc chuông sẽ lặp lại trong trạng thái connecting và nhỏ dần khi tác nhân AI kết nối. Truyền true để dùng nhạc chuông mặc định tích hợp sẵn hoặc truyền chuỗi URL để dùng tệp âm thanh của riêng bạn.

Với callback sự kiện

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

Giao diện tùy chỉnh hoàn toàn

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

Mẹo

Luôn render phone.audio

Phần tử phone.audio không hiển thị nhưng bắt buộc. Đặt phần tử này ở bất kỳ đâu trong JSX của bạn — phần tử không render DOM hiển thị nhưng quản lý kết nối âm thanh WebRTC nội bộ.

Vô hiệu hóa nút khi đang kết nối

Trạng thái connecting có thể kéo dài 1-3 giây. Vô hiệu hóa nút gọi trong trạng thái này để ngăn các lần thử kết nối trùng lặp.

Xử lý trạng thái lỗi một cách hợp lý

Khi trạng thái là error, hãy hiển thị phone.error cho người dùng và giữ nút gọi của bạn ở trạng thái bật. Hook không tự thoát khỏi trạng thái error — việc gọi lại connect() sẽ bắt đầu một lần thử mới và xóa lỗi trước đó.

Dùng callback cho các tác dụng phụ

Các callback onConnect, onDisconnect và onError phù hợp cho phân tích, ghi log hoặc kích hoạt logic ứng dụng khác mà không cần thăm dò trạng thái.

Đọc mức âm thanh từ audioLevelRef

audioLevelRef là nguồn mức âm thanh trực tiếp duy nhất. Đọc audioLevelRef.current bên trong requestAnimationFrame để tạo hiệu ứng mượt mà như dạng sóng (đọc ref không gây render lại), hoặc lấy mẫu theo khoảng thời gian và lưu kết quả vào state cho UI do React render. Số audioLevel đã bị ngừng sử dụng và luôn là 0 — không xây dựng logic dựa trên nó.

​Khi nào nên sử dụng Hook không giao diện

​Cài đặt

​Cách sử dụng cơ bản

​Tùy chọn

​Giá trị trả về

​Giao diện phản hồi theo âm thanh

​Ví dụ dạng sóng

​Ví dụ quả cầu nhấp nhô

​Ví dụ chỉ báo đang nói

​Máy trạng thái

​Ví dụ

​Với điều khiển tắt tiếng

​Với nhạc chuông

​Với callback sự kiện

​Giao diện tùy chỉnh hoàn toàn

​Mẹo

Khi nào nên sử dụng Hook không giao diện

Cài đặt

Cách sử dụng cơ bản

Tùy chọn

Giá trị trả về

Giao diện phản hồi theo âm thanh

Ví dụ dạng sóng

Ví dụ quả cầu nhấp nhô

Ví dụ chỉ báo đang nói

Máy trạng thái

Ví dụ

Với điều khiển tắt tiếng

Với nhạc chuông

Với callback sự kiện

Giao diện tùy chỉnh hoàn toàn

Mẹo