Skip to main content
Khi một cuộc gọi đến đến một số không có tác nhân được chỉ định, hoặc một phiên tiện ích web bắt đầu trên một khóa công khai ở chế độ mode="webhook", ThunderPhone gửi một yêu cầu telephony.incoming / web.incoming chặn đến URL webhook cũ của bạn và chờ tối đa 10 giây để nhận phản hồi cấu hình. Sử dụng trao đổi này để chọn linh hoạt prompt, giọng nói và công cụ cho từng cuộc gọi — xem hướng dẫn cấu hình cuộc gọi động để biết quy trình hoàn chỉnh.
Các điểm cuối webhook đã đăng ký cũng nhận telephony.incoming / web.incoming — cho mọi cuộc gọi đến và phiên web, dù đã cấu hình tác nhân hay chưa — nhưng các lần gửi đó là thông báo gửi đi không chờ phản hồi với event_id, không bao giờ chặn. Chỉ webhook URL đơn cũ mới thực hiện trao đổi cấu hình trên trang này. Cấu trúc thông báo điểm cuối có trong danh mục sự kiện.
Trao đổi chặn không có phương án dự phòng: nếu handler của bạn trả về trạng thái không phải 2xx, hết thời gian chờ hoặc trả về cấu hình không xác thực được, cuộc gọi sẽ bị từ chối (cuộc gọi điện thoại không kết nối; yêu cầu phiên tiện ích thất bại với 502/422). Phản hồi nhanh — người gọi đang nghe chuông chờ trong khi bạn đưa ra quyết định.

Payload yêu cầu

Đối với cuộc gọi điện thoại (telephony.incoming):
Đối với phiên tiện ích web (web.incoming), data xác định trang nhúng thay vì số điện thoại:
Tiện ích ở chế độ webhook gửi yêu cầu này đến webhook_url riêng của khóa công khai khi được thiết lập, hoặc dùng URL webhook cấp tổ chức nếu không có. Trong cả hai trường hợp, yêu cầu được ký bằng secret webhook của tổ chức.

Lược đồ phản hồi

Trả về một đối tượng JSON mô tả cấu hình tác nhân AI cho cuộc gọi này. promptvoice là bắt buộc; mọi trường khác là tùy chọn.
Các khóa cấp cao nhất không xác định sẽ bị bỏ qua một cách im lặng — tên trường bị gõ sai không khiến cấu hình bị từ chối, nhưng cũng không được áp dụng. Thứ tự phát lời và max_hold_seconds không được chấp nhận ở đây; chúng chỉ có thể được cấu hình trên chính Tác nhân AI.
promptvoice là bắt buộc, việc trả về {} hoặc bất kỳ phản hồi nào không vượt qua bước xác thực sẽ từ chối cuộc gọi với 422 — không có phương án dự phòng tác nhân AI tĩnh trên đường dẫn này (một số điện thoại hoặc khóa ở chế độ webhook không có tác nhân AI được gán).

Giới hạn kích thước phản hồi

Phản hồi cấu hình bị giới hạn ở mức 5 MiB. Nếu một trình xử lý trả về phản hồi lớn hơn, kể cả với trạng thái 2xx, ThunderPhone sẽ báo cáo rằng phản hồi đã vượt quá giới hạn và từ chối cuộc gọi hoặc phiên tiện ích. Chỉ giữ trong phản hồi các trường cần thiết để thiết lập cuộc gọi; thay vào đó, hãy lưu trữ dữ liệu lớn phía sau công cụ hàm hoặc một dịch vụ khác thay vì nhúng dữ liệu đó vào cấu hình.

Ví dụ về trình xử lý


Phản hồi có công cụ hàm

Đính kèm công cụ để tác nhân AI có thể gọi API của bạn trong khi trò chuyện:
Yêu cầu đến endpoint công cụ được ký bằng cùng secret webhook của tổ chức đã ký trao đổi này. Xem Công cụ hàm để biết cấu trúc chính xác và định dạng yêu cầu đã ký.

Bảng tham khảo nhanh cấp sản phẩm


Liên quan

telephony.complete / web.complete

Sự kiện kết thúc cuộc gọi không chặn.

Công cụ hàm

Schema JSON đầy đủ cho tools[] và hợp đồng endpoint đã ký.

Endpoint webhook

Đăng ký nhiều URL cho telephony.incoming / web.incoming.

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

Mẫu cho prompt, công cụ và kiểm thử A/B theo từng người gọi.