Cách hoạt động
- Bạn đăng ký sự kiện
telephony.incoming(điện thoại) hoặcweb.incoming(widget). Cả hai đều là webhook chặn: ThunderPhone chờ tối đa 10 giây để nhận phản hồi của bạn trước khi tiếp tục cuộc gọi. - ThunderPhone gửi cho bạn
{call_id, from_number, to_number}(phiên widget mang các trường dành riêng cho widget thay vì số điện thoại — xem schema yêu cầu). - Máy chủ của bạn phản hồi bằng cấu hình tác nhân AI (prompt, giọng nói, sản phẩm, công cụ). ThunderPhone sử dụng cấu hình đó cho cuộc gọi.
- Nếu bạn trả về
{}, hết thời gian chờ hoặc gặp lỗi, tác nhân AI được gán tĩnh sẽ được dùng làm phương án dự phòng. Mặc định an toàn.
Hoạt động giống hệt cho cuộc gọi điện thoại (
telephony.incoming) và phiên
widget (web.incoming), dù được gửi đến endpoint webhook
hay webhook URL đơn cũ.1. Cấu hình đích webhook
- Cuộc gọi điện thoại
- Widget web
Đối với số điện thoại, đăng ký endpoint của bạn với Phản hồi bao gồm một
telephony.incoming:secret chỉ hiển thị một lần — hãy lưu lại; bạn sẽ dùng nó
để xác minh chữ ký.2. Triển khai handler
Ba nguyên tắc cơ bản:- Xác minh chữ ký trên mọi request (xem Xác minh chữ ký webhook). Đừng bỏ qua việc này trong môi trường dev — làm đúng một lần rồi tái sử dụng.
- Phản hồi nhanh. Mười giây là giới hạn cứng, và mỗi giây đều là khoảng lặng đối với người gọi. Thực hiện tra cứu cơ sở dữ liệu nếu cần, nhưng đừng gọi LLM hạ nguồn đồng bộ — nếu bạn muốn tạo prompt động, hãy tính trước và lưu vào bộ nhớ đệm.
- Dự phòng gọn gàng. Mọi trạng thái không mong đợi phải trả về
{}để tác nhân AI được gán tĩnh xử lý cuộc gọi.
3. Schema phản hồi
Nội dung phản hồi khớp chính xác với schema phản hồi cuộc gọi đến. Các trường thường dùng:Thứ tự nói theo từng cuộc gọi và
max_hold_seconds không có trong
phản hồi webhook. Hãy thiết lập chúng trên
Tác nhân AI mà bạn tham chiếu.Mẫu
Ngữ cảnh người dùng đã đăng nhập
Trong các widget ở chế độ webhook, trang của khách truy cập đã biết họ là ai. Gọi webhook của bạn với tham số chuỗi truy vấn mà SDK widget chuyển tiếp (?customer_id=123) và tra cứu khách hàng ở phía máy chủ.
Triển khai prompt A/B
Trước khi tự triển khai, lưu ý rằng ThunderPhone có tính năng gốc Thử nghiệm (/dashboard/experiments và tab A/B của trình xây dựng tác nhân) để xác định các biến thể, phân chia lưu lượng và so sánh kết quả theo từng biến thể — không cần webhook.
Nếu bạn vẫn cần kiểm soát ở phía webhook: băm call_id → bucket; cung cấp prompt A cho 0..49 và prompt B cho 50..99. Ghi lại bucket bạn đã chọn trong DB riêng và sau đó đối chiếu với điểm của cuộc gọi đã hoàn tất.
Định tuyến theo thời gian
Giờ làm việc → tác nhân “hỗ trợ trực tiếp”; ngoài giờ → tác nhân “ghi lời nhắn”. Chỉ cần chuyển đổi dựa trênnew Date().getUTCHours() trong trình xử lý của bạn.
Bước tiếp theo
Tham chiếu webhook cuộc gọi đến
Schema yêu cầu và phản hồi chính xác, bao gồm mọi khóa cấu hình.
Xác minh chữ ký webhook
Thiết lập HMAC chính xác một lần; tái sử dụng ở mọi nơi.
Xây dựng tích hợp công cụ
Kết hợp định tuyến động với các công cụ theo từng tác nhân.
Ngữ nghĩa phân phối
Thử lại, thứ tự, thời gian chờ.