Skip to main content
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 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.
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.

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

1

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

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

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

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

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 để biết tất cả trường.
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.

​
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:

Thành phần React

<ThunderPhoneWidget publishableKey="pk_live_..." />.

Hook headless

useThunderPhone() cho giao diện người dùng tùy chỉnh.

Thẻ script CDN

ThunderPhone.mount({...}) cho các trang web không dùng bundler.
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.

​
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 như cuộc gọi điện thoại:
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 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

Tài liệu tham khảo SDK widget

Chi tiết tích hợp React / hook / CDN.

Cấu hình động cho từng cuộc gọi

Triển khai luồng mode="webhook" từ đầu đến cuối.

Tài liệu tham khảo khóa có thể công khai

Mọi trường trên tài nguyên khóa.

API phiên mic

Bỏ qua widget; điều khiển LiveKit trực tiếp cho UI tùy chỉnh.