Developer cookbook

Mang số của riêng bạn (VoIP, API)

Kết nối Twilio hoặc Telnyx — hoặc bất kỳ SIP trunk nào — nhập các số điện thoại bạn đã sở hữu và để tác nhân AI ThunderPhone trả lời cũng như thực hiện cuộc gọi trên các số đó.

Số demo phù hợp để tạo mẫu thử, nhưng lưu lượng production nên sử dụng số bạn sở hữu thông qua nhà cung cấp VoIP của riêng mình. Hướng dẫn này trình bày quy trình ba bước: kiểm tra thông tin xác thực → tạo kết nối → nhập số → xác minh.

Nhà cung cấp được hỗ trợ#

1. Kiểm tra thông tin xác thực#

Trước khi tạo kết nối VoIP được lưu, hãy kiểm tra thông tin xác thực của nhà cung cấp để xác nhận chúng hoạt động. Thao tác này trả về một verification_evidence_id để bạn truyền vào bước tạo, nhằm tránh bị tính phí kiểm tra thông tin xác thực hai lần.

curl -X POST https://api.thunderphone.com/v1/voip-connections/test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider":    "telnyx",
    "credentials": { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":  { "domain": "acme.sip.telnyx.com" }
  }'

{
  "status": "pass",
  "verification_evidence_id": "b9a2...",
  "suggested_connection_name": "Telnyx: Acme Main (+15550001234)",
  "checks": {
    "credentials_valid": true,
    "inbound_reachable": true,
    "outbound_authorized": true
  }
}

Nếu bất kỳ kiểm tra nào thất bại, status của phản hồi sẽ là fail và checks sẽ cho biết bước nào gặp lỗi. Khắc phục cấu hình phía nhà cung cấp (gán trunk, danh sách cho phép IP, ủy quyền gọi đi) rồi thử lại.

2. Tạo kết nối#

Truyền verification_evidence_id bạn vừa nhận được:

curl -X POST https://api.thunderphone.com/v1/voip-connections \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":         "Acme Telnyx Main",
    "provider":     "telnyx",
    "setup_method": "api_key",
    "credentials":  { "apiKey": "KEY...", "connectionId": "123456" },
    "sip_config":   { "domain": "acme.sip.telnyx.com" },
    "verification_evidence_id": "b9a2..."
  }'

Phản hồi là một đối tượng VoipConnection ở status="connected". Thông tin xác thực được lưu phía máy chủ và không bao giờ được trả về dưới dạng văn bản thuần trong các yêu cầu GET sau đó — để xoay vòng, hãy chạy test mới và PATCH bằng bằng chứng mới.

3. Liệt kê và nhập số#

Kiểm tra các số mà thông tin xác thực của bạn có thể thấy nhưng chưa thuộc một tổ chức ThunderPhone:

curl https://api.thunderphone.com/v1/voip-connections/5/available-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Sau đó nhập các số bạn muốn:

curl -X POST https://api.thunderphone.com/v1/voip-connections/5/import-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers": ["+15550001234", "+15550009999"]}'

Mỗi số được nhập sẽ trở thành một tài nguyên số điện thoại trong tổ chức của bạn với source="voip" và status="provisioning".

4. Xác minh từng số đã nhập#

Việc nhập sẽ đăng ký số là có sẵn; để thực sự định tuyến cuộc gọi qua số đó, cần xác minh hai chiều (kiểm tra quay số đến + thăm dò ủy quyền gọi đi).

curl -X POST https://api.thunderphone.com/v1/phone-numbers/{id}/verify-voip \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Khi thành công, voip_verification_status chuyển thành verified và số chuyển sang status="active". Khi thất bại, phản hồi sẽ nêu rõ mục nào không thành công — hãy khắc phục (thường là thiếu gán trunk trong bảng điều khiển của nhà cung cấp) rồi gọi lại.

5. Gán tác nhân và thực hiện cuộc gọi#

Sau khi số được xác minh, bạn gán tác nhân AI cho cuộc gọi đến / gọi đi giống như với số demo. Xem Xử lý cuộc gọi đến và Thực hiện cuộc gọi đi.

Luân phiên thông tin xác thực#

Khi khóa của nhà cung cấp được luân phiên, hãy chạy lại quy trình kiểm tra rồi cập nhật:

# 1. Test the new credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/test ...
 
# 2. PATCH the connection with the new evidence
curl -X PATCH https://api.thunderphone.com/v1/voip-connections/{id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "apiKey": "NEW_KEY..." },
    "verification_evidence_id": "fresh-evidence-id"
  }'

Kết nối vẫn được giữ nguyên — không cần nhập lại số.

Bước tiếp theo#