---
title: "Widget thoại có thể nhúng"
description: "Thêm tác nhân AI thoại vào bất kỳ trang web nào chỉ với vài dòng mã"
---

Tiện ích giọng nói nhúng ThunderPhone cho phép khách truy cập website của bạn trò chuyện trực tiếp với tác nhân AI từ trình duyệt. Không cần gọi điện -- người dùng chỉ cần nhấp vào nút và bắt đầu cuộc trò chuyện bằng giọng nói theo thời gian thực do ThunderPhone cung cấp.

Tiện ích hiển thị dưới dạng thanh kính mờ thích ứng với giao diện sáng và tối, có màu nhấn và vị trí tùy chỉnh. Tiện ích được phân phối dưới dạng gói npm `@thunderphone/widget` và cũng có sẵn qua CDN cho các môi trường không dùng bundler.

<Frame>
  <img src="/images/widget-showcase.png" alt="ThunderPhone widget in light and dark themes with various accent colors" />
</Frame>

## Điều kiện tiên quyết

Trước khi nhúng tiện ích, hãy hoàn tất ba bước sau trong [Bảng điều khiển ThunderPhone](https://app.thunderphone.com):

<Steps>
<Step title="Tạo tiện ích web">
  Vào **Tiện ích web** trong bảng điều khiển và tạo một tiện ích. Chọn tác nhân AI bạn muốn hiển thị. Mỗi tiện ích có khóa có thể công khai riêng (`pk_live_...`), an toàn để đưa vào mã phía máy khách; tác nhân AI được xác định từ khóa này.
</Step>

<Step title="Cấu hình miền được phép">
  Trên cùng tiện ích đó, thêm các miền nơi tiện ích sẽ được nhúng. Có hỗ trợ ký tự đại diện (ví dụ: `*.example.com`). Danh sách này ngăn tiện ích hoạt động khi ai đó sao chép khóa của bạn sang trang khác; đây không phải là xác thực, vì một script bên ngoài trình duyệt có thể gửi bất kỳ tiêu đề `Origin` nào. `localhost` không tự động được cho phép trong môi trường production: hãy thêm nó vào danh sách để kiểm thử cục bộ với API production.
</Step>

<Step title="Chọn ghi đè của trình duyệt">
  Nếu trang của bạn đặt `language`, `voice` hoặc `context`, hãy bật từng mục trong **Ghi đè của trình duyệt**. Tiện ích mới không chấp nhận mục nào, và yêu cầu phiên chứa một thiết lập đang tắt sẽ thất bại với `400 override_not_allowed`. Xem [Ghi đè của trình duyệt](/vi/guides/embed-web-widget).
</Step>
</Steps>

<Warning>
  Khóa có thể công khai (`pk_live_...`) **không** giống với token API bí mật của bạn. Khóa có thể công khai được thiết kế để sử dụng phía client và chỉ áp dụng cho các phiên tiện ích trên những miền được phép của bạn. Không bao giờ sử dụng token API bí mật trong mã phía client.
</Warning>

<Note>
  Phiên tiện ích kết thúc sau 30 phút theo mặc định, hoặc sớm hơn nếu thời lượng cuộc gọi tối đa của chính tác nhân AI ngắn hơn. Thay đổi giới hạn cho từng khóa bằng `max_call_duration_seconds` trên [khóa có thể công khai](/api-reference/publishable-keys) (tối đa 6 giờ), hoặc đặt thành `null` để dùng giới hạn của chính tác nhân AI.
</Note>

---

## Bắt đầu nhanh

Cài đặt gói:

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

Thêm tiện ích vào ứng dụng của bạn:

```tsx
import { ThunderPhoneWidget } from '@thunderphone/widget'
import '@thunderphone/widget/style.css'

function App() {
  return (
    <ThunderPhoneWidget
      publishableKey="pk_live_your_publishable_key"
      theme="dark"
      primaryColor="#8b5cf6"
    />
  )
}
```

Vậy là xong. Người dùng của bạn sẽ thấy một thanh cuộc gọi kính mờ kết nối họ với tác nhân AI của bạn chỉ bằng một lần nhấp.

---

## Tùy chỉnh

Tiện ích có bốn prop về giao diện:

| Prop | Mặc định | Mô tả |
|------|---------|-------------|
| `theme` | `'light'` | `'light'` cho kính trắng, `'dark'` cho kính tối |
| `primaryColor` | `'#000000'` (sáng) / `'#ffffff'` (tối) | Màu nhấn cho nút bắt đầu, dạng sóng và chỉ báo đang kết nối |
| `title` | `'Voice assistant'` | Văn bản hiển thị trong tiện ích |
| `position` | `'bottom-right'` | Góc khung nhìn: `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'` |

<CodeGroup>
```tsx Light theme (default)
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
/>
```

```tsx Dark theme with custom color
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  primaryColor="#8b5cf6"
  title="Ask our AI"
/>
```
</CodeGroup>

Ba prop khác tùy chỉnh phiên thay vì giao diện — tất cả đều được chuyển tiếp đến yêu cầu phiên khi cuộc gọi bắt đầu. Mỗi prop chỉ hoạt động khi publishable key của widget cho phép trong **Ghi đè trình duyệt**; nếu không, yêu cầu phiên sẽ thất bại với `400 override_not_allowed`:

| Prop | Mô tả |
|------|-------------|
| `language` | Ghi đè ngôn ngữ theo phiên -- một mã hoặc locale như `en`, `es` hoặc `fr-FR` |
| `voice` | Ghi đè giọng nói theo phiên -- tên giọng nói như `maria` |
| `context` | Ngữ cảnh thực tế của trang hoặc website được truyền đến tác nhân (được cắt bớt phía máy chủ còn 12.000 ký tự) |

Xem [tham chiếu thành phần React](/vi/widget/react) để biết bảng prop đầy đủ.

Để có giao diện hoàn toàn tùy chỉnh, hãy sử dụng [headless hook](/vi/widget/headless-hook) để quản lý phiên giọng nói trong khi bạn xây dựng giao diện riêng. Hook này cung cấp mức âm thanh theo thời gian thực để xây dựng các hình ảnh trực quan phản ứng với âm thanh.

Mỗi cuộc trò chuyện trên widget là một cuộc gọi. Cuộc gọi này được tính vào [giới hạn cuộc gọi đồng thời](/api-reference/introduction#call-limits) của tổ chức bạn (mặc định 20 cuộc gọi đang diễn ra, dùng chung với cuộc gọi điện thoại và các cuộc gọi khác) và giới hạn widget là 25 phiên hoạt động (hoặc giới hạn cuộc gọi đồng thời của bạn, nếu cao hơn). Khi đạt một trong hai giới hạn, cuộc trò chuyện mới không thể bắt đầu cho đến khi một cuộc gọi kết thúc.

---

## Tùy chọn tích hợp

Chọn phương thức tích hợp phù hợp với stack của bạn:

<CardGroup cols={3}>
  <Card title="Thành phần React" icon="react" href="/vi/widget/react">
    Thành phần UI dựng sẵn với nút điều khiển cuộc gọi và hiển thị trạng thái tích hợp. Import, truyền props, hoàn tất.
  </Card>
  <Card title="Hook Headless" icon="code" href="/vi/widget/headless-hook">
    Toàn quyền kiểm soát UI. Hook `useThunderPhone` quản lý phiên thoại trong khi bạn xây dựng giao diện riêng.
  </Card>
  <Card title="CDN / Thẻ Script" icon="globe" href="/vi/widget/cdn-script-tag">
    Không cần bundler. Tải widget qua thẻ script cho trang tĩnh, WordPress và các môi trường không dùng React khác.
  </Card>
</CardGroup>

---

## Tùy chỉnh giao diện

Widget đi kèm giao diện sáng và tối tích hợp, được điều khiển bằng prop `theme`, cùng màu nhấn được điều khiển bằng prop `primaryColor`. Để tùy chỉnh sâu hơn, bạn có thể ghi đè các thuộc tính tùy chỉnh và class CSS. Xem [hướng dẫn tùy chỉnh giao diện](/vi/widget/styling) để biết chi tiết.

<Note>
  Cần hỗ trợ? Liên hệ với chúng tôi tại [support@thunderphone.com](mailto:support@thunderphone.com)
</Note>