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

Kết nối Twilio, Telnyx, SignalWire, Vonage, Plivo và bất kỳ SIP trunk nào khác qua SIP, 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ố đó.

Các số ThunderPhone đã được phê duyệt có thể thực hiện cuộc gọi đi và chạy chiến dịch. Nếu bạn muốn sử dụng các số do mình sở hữu thông qua nhà cung cấp VoIP riêng, hướng dẫn này sẽ chỉ cho bạn quy trình kết nối: 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 mà bạn truyền vào bước tạo để thông tin xác thực không bị tính phí hai lần khi kiểm tra.

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 trong phản hồi sẽ là fail và checks sẽ cho biết bước nào gặp lỗi. Hãy sửa cấu hình phía nhà cung cấp (gán trunk, danh sách cho phép IP, 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 với status="connected". Thông tin xác thực được lưu trữ 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 tiếp theo — để xoay vòng, hãy chạy một lệnh test mới và PATCH với bằng chứng mới.

Tài khoản con Twilio#

Một kết nối Twilio được liên kết với duy nhất một tài khoản Twilio có Account SID và Auth Token mà kết nối đó lưu giữ. Twilio lưu số điện thoại và SIP trunk trong từng tài khoản phụ, vì vậy kết nối được tạo bằng tài khoản cha chỉ có thể thấy các số của chính tài khoản cha, và không thể chuyển một kết nối hiện có sang tài khoản phụ khác sau này.

Để truy cập các số trong tài khoản con, hãy tạo một kết nối cho mỗi tài khoản con. Bảng điều khiển sẽ thực hiện việc này cho bạn: khi bạn kết nối một tài khoản cha có tài khoản con đang hoạt động, hộp thoại thiết lập sẽ liệt kê chúng, bạn chọn những tài khoản muốn dùng và ThunderPhone tạo một kết nối (và một SIP trunk) trong từng tài khoản. Cùng quy trình này cũng có sẵn qua API:

# Discover active subaccounts visible to the parent credentials
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credentials": {"accountSid": "ACparent...", "authToken": "..."}}'

{
  "discovery_id": "7c1e...",
  "parent": { "sid": "ACparent...", "friendly_name": "Acme" },
  "subaccounts": [
    { "sid": "ACsupport...", "friendly_name": "Acme Support", "already_connected": false, "connection_id": null },
    { "sid": "ACsales...",   "friendly_name": "Acme Sales",   "already_connected": true,  "connection_id": 5 }
  ]
}

# Create a connection for each selected subaccount
curl -X POST https://api.thunderphone.com/v1/voip-connections/twilio/subaccounts/connect \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discovery_id": "7c1e...", "subaccount_sids": ["ACsupport..."]}'

Phản hồi có một hàng cho mỗi tài khoản con với status là created, skipped (đã kết nối) hoặc failed, kèm theo error mà bạn có thể xử lý. Các hàng độc lập với nhau, vì vậy lỗi ở một tài khoản con không bao giờ chặn các tài khoản khác, và discovery_id vẫn có hiệu lực trong 30 phút để bạn chỉ cần thử lại hàng bị lỗi. Token tài khoản con được đọc từ Twilio tại thời điểm khám phá và lưu trên kết nối mới; chúng không bao giờ được API trả về. Mỗi kết nối mới sau đó nhập và xác minh số điện thoại giống hệt như kết nối bạn đã tạo thủ công. Thêm "enable_transfers": true để cũng bật chuyển cuộc gọi cho SIP trunk của mỗi kết nối mới; lỗi tại đó được báo trong test_result.transfer_enable_error của kết nối đó và không làm hàng bị lỗ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 nằm trong 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 lần nhập sẽ tạo một tài nguyên số điện thoại trong tổ chức của bạn với number_type="voip" và status="provisioning".

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

Việc nhập đăng ký số ở trạng thái khả dụng; để thực sự định tuyến cuộc gọi qua số đó, bạn cần xác minh. Với kết nối nhà cung cấp (Twilio, Telnyx), thao tác này sẽ kiểm tra lại thông tin xác thực của nhà cung cấp và khả năng truy cập SIP. Với kết nối SIP thủ công, hệ thống trước tiên thử một cuộc gọi tự kiểm tra vòng lặp: ThunderPhone thực hiện một cuộc gọi thăm dò ngắn từ số đó, qua SIP trunk của bạn, quay lại chính số đó. Nếu cách này không xác minh được đường gọi đến, hệ thống chuyển sang một cuộc gọi thăm dò ngắn từ số đó, qua SIP trunk của bạn, tới một số ThunderPhone. Các kiểm tra này xác thực tên người dùng, mật khẩu, phương thức truyền, định tuyến cuộc gọi đi và phân phối cuộc gọi đến của trunk. Nhà mạng của bạn tính phí các cuộc gọi này như mọi cuộc gọi khác.

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ố điện thoại chuyển sang status="active". Một số điện thoại trong tài khoản Telnyx của riêng bạn vẫn tiếp tục nhận cuộc gọi đến khi cuộc gọi kiểm tra thất bại hoặc cuộc gọi đi chưa được thiết lập: số đó chuyển sang status="active" với voip_verification_status được đặt thành unverified, và phản hồi sẽ nêu lý do. Khi thất bại, phản hồi nêu rõ điều gì đã thất bại — với trunk thủ công, đó là phản hồi SIP của nhà cung cấp, ví dụ "đã từ chối thông tin xác thực của ThunderPhone (SIP 401)" hoặc "không thể định tuyến cuộc gọi (SIP 404)" — hãy khắc phục (thông tin xác thực, IP nguồn được phép, cấu hình trunk bị thiếu trong bảng điều khiển của nhà cung cấp) rồi gọi lại.

Với kết nối SIP thủ công có trong danh sách cho phép, kiểm tra cuộc gọi đến cũng sẽ thất bại nếu các IP nguồn được phép đó chặn một cuộc gọi đến thực tế.

5. Gán tác nhân AI và nhậ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 / đi giống như với số ThunderPhone. Xem Xử lý cuộc gọi đến và Thực hiện cuộc gọi đi.

Thay đổi thông tin xác thực#

Khi khóa nhà cung cấp thay đổi, 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#