Developer cookbook

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

   Tác nhân có prompt và giọng nói sẽ chạy phiên tiện ích. Đặt widget_enabled: true (mặc định).

2. Chọn chế độ định tuyến
   • mode="agent" — một tác nhân 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 cho từng khách truy cập qua một webhook web.incoming. Dùng chế độ này cho người dùng đã đăng nhập, thử nghiệm A/B hoặc định tuyến theo từng trang.
3. Liệt kê miền được phép

   Khóa có thể công khai bị giới hạn theo nguồn. Bạn phải nêu mọi tên máy chủ 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ể 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"]
  }'

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.

context của tiện ích bị cắt ở 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 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#