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

# Nhúng tiện ích web

> Thêm tác nhân AI giọng nói vào trang marketing hoặc hỗ trợ của bạn — không cần số điện thoại.

Tiện ích web cho phép khách truy cập trang web của bạn trò chuyện bằng cách nhấp để nói
với một tác nhân AI, sử dụng micrô của trình duyệt. Đây là một
SDK JavaScript / React riêng biệt với [tài liệu tham khảo SDK](/vi/widget/overview)
riêng — hướng dẫn này tập trung vào thiết lập phía ThunderPhone mà tiện ích cần.

<Note>
  Bạn có thể thực hiện tất cả việc này mà không cần cURL: trang dashboard
  **Tiện ích web** (`/dashboard/web-widgets`) tạo tiện ích, thiết lập chế độ
  và tác nhân, quản lý miền được phép, đồng thời cung cấp cho bạn đoạn mã nhúng.
</Note>

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

<Steps>
  <Step title="Tạo tác nhân AI">
    Tác nhân AI có prompt và giọng nói sẽ chạy phiên tiện ích. Đặt
    `widget_enabled: true` (mặc định).
  </Step>

  <Step title="Quyết định chế độ định tuyến">
    * `mode="agent"` — một tác nhân AI tĩnh cho mỗi khóa. Đơn giản nhất.
    * `mode="webhook"` — máy chủ của bạn chọn tác nhân AI cho từng khách truy cập thông qua
      một [`web.incoming` webhook](/vi/webhooks/call-incoming). Dùng tùy chọn này cho
      người dùng đã đăng nhập, kiểm thử A/B hoặc định tuyến theo từng trang.
  </Step>

  <Step title="Liệt kê miền được phép">
    Khóa có thể xuất bản bị khóa theo origin. Bạn phải nêu tên mọi hostname
    sẽ nhúng tiện ích. `localhost` / `127.0.0.1` luôn được
    phép trong quá trình phát triển cục bộ.
  </Step>
</Steps>

## Tạo khóa có thể xuất bản

<CodeGroup>
  ```bash Static agent theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Marketing site (prod)",
      "mode":            "agent",
      "agent_id":        12,
      "allowed_domains": ["example.com", "*.example.com"]
    }'
  ```

  ```bash Dynamic via webhook theme={null}
  curl -X POST https://api.thunderphone.com/v1/publishable-key \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name":            "Support (dynamic)",
      "mode":            "webhook",
      "webhook_url":     "https://example.com/thunderphone/widget-hook",
      "allowed_domains": ["support.example.com"]
    }'
  ```
</CodeGroup>

Phản hồi bao gồm một `key` bắt đầu bằng `pk_live_...`. **Khóa có thể xuất bản
công khai theo thiết kế** — an toàn để đưa vào gói front-end của bạn.
Xem [tài liệu tham khảo khóa có thể xuất bản](/api-reference/publishable-keys) để biết
tất cả trường.

<Warning>
  `allowed_domains` phải chứa ít nhất một mục. `*.example.com`
  khớp với các miền phụ (ví dụ: `api.example.com`) nhưng **không** khớp với
  miền gốc. Ký tự đại diện trần như `*` hoặc `*.*` sẽ bị từ chối.
</Warning>

## Thêm tiện ích vào trang web của bạn

Ba tùy chọn tích hợp được trình bày trong
[tài liệu SDK tiện ích](/vi/widget/overview):

<CardGroup cols={3}>
  <Card title="Thành phần React" icon="react" href="/vi/widget/react">
    `<ThunderPhoneWidget publishableKey="pk_live_..." />`.
  </Card>

  <Card title="Hook headless" icon="circle-nodes" href="/vi/widget/headless-hook">
    `useThunderPhone()` cho giao diện người dùng tùy chỉnh.
  </Card>

  <Card title="Thẻ script CDN" icon="code" href="/vi/widget/cdn-script-tag">
    `ThunderPhone.mount({...})` cho các trang web không dùng bundler.
  </Card>
</CardGroup>

Cả ba đều nhận cùng `publishableKey` và hiển thị nút mic
cùng phần tử âm thanh trong cuộc gọi.

`context` của tiện ích bị cắt ngắn ở 12.000 ký tự (khoảng 3.400
token của văn bản tiếng Anh thông thường) và được tính vào
[phụ phí kích thước prompt](/vi/guides/billing-and-topups).

## Webhook chế độ tiện ích

Khi `mode="webhook"`, ThunderPhone gọi `webhook_url` của bạn khi mỗi
phiên bắt đầu với payload `web.incoming`. Trả về cấu hình tác nhân AI
bạn muốn chạy cho khách truy cập đó — cấu hình này tuân theo cùng
[lược đồ phản hồi](/vi/webhooks/call-incoming) như cuộc gọi
điện thoại:

```json theme={null}
{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}
```

Bạn có thể kết hợp ngữ cảnh từ phiên riêng của mình (khách hàng nào đang duyệt,
họ đang ở trang nào) vào prompt, và thay đổi tác nhân AI theo từng đợt triển khai.

## Theo dõi phiên

Phiên widget xuất hiện trong
[`GET /v1/calls`](/api-reference/calls#list-calls) với
`direction="widget"` — cùng bản chép lời, bản ghi âm, đánh giá và
thanh toán như cuộc gọi điện thoại. Lọc theo `direction` để xây dựng
bảng điều khiển chỉ dành cho widget.

***

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Tài liệu tham khảo SDK widget" icon="window-maximize" href="/vi/widget/overview">
    Chi tiết tích hợp React / hook / CDN.
  </Card>

  <Card title="Cấu hình động cho từng cuộc gọi" icon="bolt" href="/vi/guides/dynamic-call-config">
    Triển khai luồng `mode="webhook"` từ đầu đến cuối.
  </Card>

  <Card title="Tài liệu tham khảo khóa có thể công khai" icon="key" href="/api-reference/publishable-keys">
    Mọi trường trên tài nguyên khóa.
  </Card>

  <Card title="API phiên mic" icon="microphone" href="/api-reference/mic-sessions">
    Bỏ qua widget; điều khiển LiveKit trực tiếp cho UI tùy chỉnh.
  </Card>
</CardGroup>