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ừ chính mã của bạn — cho các quy trình 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 bạn. Các trường hợp sử dụng điển hình:

• 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. Chọn số hỗ trợ gọi đi

   Sử dụng số bạn sở hữu thông qua một kết nối VoIP, hoặc yêu cầu quyền sử dụng số ThunderPhone của bạn cho cuộc gọi đi từ trang Số điện thoại. Số ThunderPhone ban đầu chỉ nhận cuộc gọi đến. ThunderPhone xét duyệt từng yêu cầu thủ công; sau khi được phê duyệt, các số đó có thể thực hiện cuộc gọi đến giới hạn hằng ngày được phê duyệt (đặt lại lúc 00:00 UTC) và chạy chiến dịch, đồng thời bạn có thể yêu cầu giới hạn cao hơn. Số VoIP của khách hàng không có giới hạn hằng ngày, vì vậy chúng tôi khuyến nghị dùng chúng cho cuộc gọi đi. Xem Mang số của riêng bạn.

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

   Prompt theo hướng gọi đi thường bắt đầu bằng việc tác nhân AI tự giới thiệu và nêu mục đích — "Chào, đây là Acme gọi để xác nhận lịch hẹn của bạn vào 3 giờ chiều 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 hoặc bật tự động nạp lại trong Tổ chức → Cài đặt thanh toán trên bảng điều khiển. Khóa sk_live_ của bạn có thể kiểm tra số dư bằng GET /v1/billing nhưng không thể nạp tiền hoặc thay đổi chế độ tự động nạp lại.

Thực hiện cuộc gọi bằng tác nhân AI đã lưu#

Cách đơn giản nhất — tham chiếu tác nhân AI theo 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":   "+14155552671",
    "agent_id":    12
  }'

Phản hồi:

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

Thực hiện cuộc gọi bằng 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":   "+14155552671",
    "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 — 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} mỗi vài giây; bản ghi bao gồm end_reason, duration_seconds và URL bản ghi sau khi cuộc gọi kết thúc.

Nếu tác nhân AI của bạn được thiết lập để trích xuất dữ liệu có cấu trúc sau cuộc gọi, dữ liệu đó sẽ được gửi riêng sau khi quá trình hoàn tất kết thúc.

Truyền biến theo từng cuộc gọi cho tác nhân AI đã lưu#

Tác nhân AI đã lưu có thể sử dụng các placeholder như {{name}} hoặc {{name|there}} trong văn bản prompt. Khi bạn thực hiện cuộc gọi đi với agent_id, hãy truyền variables chứa các giá trị cho cuộc gọi đó:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Sử dụng giá trị chuỗi được khóa theo tên placeholder. Các biến này áp dụng cho tác nhân AI đã lưu; ví dụ config nội tuyến trong hướng dẫn này không sử dụng chúng.

Các chế độ lỗi cần xử lý#

Xem tài liệu tham chiếu cuộc gọi đi để biết danh sách mã điều kiện hợp lệ ổn định đầy đủ và cả hai dạng phản hồi 409. Nếu một số đang hoạt động trở nên không đủ điều kiện sau khi yêu cầu được chấp nhận nhưng trước khi cuộc gọi được thực hiện, lần kiểm tra cuối cùng sẽ trả về payload 409 không thể thử lại.

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":   "+14155552671",
  "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 giây (15 phút).

Bước tiếp theo#