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

# Widget thoại có thể nhúng

> 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="https://mintcdn.com/thunderphone/4XhPaCl4RGfyS7_M/images/widget-showcase.png?fit=max&auto=format&n=4XhPaCl4RGfyS7_M&q=85&s=17fea4fe853f3548b9b2628c9d4c4fc0" alt="ThunderPhone widget in light and dark themes with various accent colors" width="1200" height="800" data-path="images/widget-showcase.png" />
</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 khóa API có thể công khai">
    Vào **Nhà phát triển** trong phần cài đặt bảng điều khiển và tạo một khóa có thể công khai. Khóa có thể công khai bắt đầu bằng `pk_live_` và an toàn để đưa vào mã phía client.
  </Step>

  <Step title="Cấu hình miền được phép">
    Trong cùng phần cài đặt Nhà phát triển, thêm các miền nơi tiện ích sẽ được nhúng. `localhost` luôn được cho phép để phát triển. Hỗ trợ ký tự đại diện (ví dụ: `*.example.com`).
  </Step>

  <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 bạn muốn cung cấp và khóa có thể công khai để sử dụng. Tác nhân được xác định tự động từ cấu hình khóa có thể công khai của bạn.
  </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>

***

## Bắt đầu nhanh

Cài đặt gói:

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

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

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

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

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

***

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