Developer cookbook

Thực hiện cuộc gọi đi (API)

Kích hoạt cuộc gọi đi do tác nhân AI thực hiện từ mã của riêng bạn — cho các luồng khảo sát, theo dõi hoặc xác nhận.

Cuộc gọi đi cho phép bạn cung cấp số đích và cấu hình tác nhân AI cho ThunderPhone để AI thực hiện cuộc gọi thay mặt bạn. Các trường hợp sử dụng phổ biến:

• Xác nhận lịch hẹn
• Gọi lại khảo sát
• Theo dõi "lần thử thứ hai" sau cuộc gọi nhỡ
• Thông báo kiểu điều phối

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

1. Cung cấp số VoIP

   Cuộc gọi đi yêu cầu bạn sở hữu from_number thông qua một kết nối VoIP. Số demo chỉ dùng cho cuộc gọi đến. Xem Sử dụng số điện thoại của riêng bạn.

2. Tạo tác nhân AI

   Prompt dành cho cuộc gọi đi thường bắt đầu bằng việc tác nhân tự giới thiệu và nêu mục đích — "Chào bạn, đây là Acme gọi để xác nhận lịch hẹn của bạn vào 3 giờ chiều ngày mai…" Đặt outbound_speak_order thành agent_first (mặc định).

3. Duy trì số dư dương

   Cuộc gọi đi trả về 402 Payment Required nếu số dư ≤ $0.00. Nạp tiền qua POST /v1/billing/top-up hoặc bật tự động nạp lại.

Thực hiện cuộc gọi với tác nhân đã lưu#

Cách đơn giản nhất — tham chiếu tác nhân bằng id:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

Phản hồi:

{ "call_id": 987654321, "status": "initiated" }

Thực hiện cuộc gọi với cấu hình nội tuyến#

Nếu bạn muốn dùng prompt một lần không đáng để lưu thành tác nhân AI, hãy truyền config thay thế. Cấu trúc này khớp với schema phản hồi của webhook call.incoming:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Theo dõi cuộc gọi#

Song song đó, đăng ký webhook telephony.complete — đây là cách nhanh nhất để biết cuộc gọi đã kết thúc. Nếu bạn không thể nhận webhook đến, hãy thăm dò GET /v1/calls/{call_id} vài giây một lần; bản ghi sẽ bao gồm end_reason, duration_seconds và URL bản ghi âm sau khi cuộc gọi kết thúc.

Các lỗi cần xử lý#

Kiểm soát thời gian chờ#

Các cuộc gọi đi kéo dài do người nhận phản hồi chậm (cây IVR, hàng đợi) có thể được giới hạn bằng max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Tác nhân AI sẽ ngắt cuộc gọi nếu không nhận được âm thanh từ người trong N giây gần nhất. Mặc định là 900 (15 phút).

Bước tiếp theo#