Nhúng tiện ích web

Thêm một tác nhân AI giọng nói vào trang marketing hoặc hỗ trợ của bạn chỉ với một thẻ script — khách truy cập trò chuyện trực tiếp với tác nhân đó từ trình duyệt, không cần số điện thoại.

Tiện ích web cung cấp cho khách truy cập trang của bạn một cuộc trò chuyện nhấp để nói với một tác nhân AI, sử dụng microphone 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.

Đ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 widget. Đặt widget_enabled: true (mặc định).

2. Chọn 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 mỗi khách truy cập thông qua webhook web.incoming. Dùng cách 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ê các miền được phép

   Nêu mọi hostname sẽ nhúng widget. Trình duyệt gửi origin của trang cùng mỗi yêu cầu phiên, vì vậy danh sách này ngăn khóa của bạn hoạt động khi ai đó sao chép khóa sang một trang khác. Đây không phải là xác thực: một script bên ngoài trình duyệt có thể gửi bất kỳ header Origin nào. localhost không tự động được cho phép trong môi trường production; để kiểm thử cục bộ với API production, hãy thêm localhost vào danh sách.

4. Chọn các ghi đè của trình duyệt

   Quyết định các cài đặt phiên mà trang của bạn có thể gửi. Khóa mới không chấp nhận ghi đè nào; xem Ghi đè của trình duyệt.

Tạo khóa có thể công khai#

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"],
    "allowed_overrides": ["context"]
  }'

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"]
  }'

Phản hồi bao gồm một key bắt đầu bằng pk_live_.... Khóa có thể công khai được thiết kế để công khai — 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ể công khai để biết toàn bộ trường.

Thêm tiện ích vào trang 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:

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

Ghi đè từ trình duyệt#

Widget có thể gửi bốn tùy chọn cho mỗi phiên từ trang:

Khóa có thể công khai của bạn là công khai, nên bất kỳ ai có khóa đều có thể gửi các cài đặt này, kể cả từ một script giả mạo miền của bạn. Vì vậy, từng cài đặt đều bị tắt cho đến khi bạn cho phép chúng trên khóa: chọn trong mục Ghi đè trên trình duyệt khi tạo hoặc chỉnh sửa widget trên dashboard, hoặc đặt allowed_overrides thông qua API khóa có thể công khai. Chỉ cho phép những gì trang của bạn thực sự gửi.

Yêu cầu phiên mang một tùy chọn mà khóa không cho phép sẽ thất bại với 400 và nêu tên tùy chọn đó:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

Kiểm tra này áp dụng ở cả hai chế độ. Trong chế độ webhook, một tùy chọn được phép cũng được chuyển tiếp đến webhook web.incoming của bạn (context đến dưới dạng website_context). Các khóa được tạo trước khi tùy chọn này tồn tại cho phép cả bốn tùy chọn, vì vậy các bản nhúng hiện có vẫn hoạt động; hãy tắt những tùy chọn bạn không dùng.

context của widget 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. Tác nhân AI được hướng dẫn coi đây là nội dung trang, không phải chỉ dẫn.

Webhook chế độ tiện ích#

Khi mode="webhook", ThunderPhone gọi webhook_url của bạn mỗi khi phiên bắt đầu với payload web.incoming. Trả về cấu hình tác nhân 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:

{
  "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 context từ phiên của riêng 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 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ó cùng bản ghi, bản ghi âm, chấm điểm 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#