Sử dụng số điện thoại của riêng bạn (VoIP, API)

Số demo phù hợp để tạo mẫu thử, nhưng lưu lượng production nên dùng các số bạn sở hữu thông qua nhà cung cấp VoIP của riêng bạn. 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.

Dashboard có phiên bản hướng dẫn cho toàn bộ quy trình này trong Kết nối → VoIP (/dashboard/voip-connections): thiết lập hướng dẫn Telnyx hướng dẫn tạo tài khoản và API key, luồng kết nối tài khoản hiện có, cùng biểu mẫu SIP thủ công có trình tạo hướng dẫn thiết lập AI.

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

Nhà cung cấp	id `provider`	Ghi chú
Twilio	`twilio`	API key + secret
Telnyx	`telnyx`	API key; có onboarding hướng dẫn (`setup_method: guided_telnyx`)
SignalWire	`signalwire`	Sắp ra mắt — hiện kết nối qua SIP thủ công
Vonage	`vonage`	Sắp ra mắt — hiện kết nối qua SIP thủ công
SIP thủ công	`manual`	Bất kỳ SIP trunk nào — dùng cấu hình của riêng bạn

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

Trước khi tạo kết nối VoIP được lưu trữ, 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" }
  }'

Response

{
  "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ỳ bước 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. 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 ra) 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 ở 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 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ể truy cập nhưng chưa có trong 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ẽ 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à khả dụng; để 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ử nghiệm ủ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õ thành phần gặp lỗi — 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 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 / 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 chuyển thông tin xác thực

Khi khóa nhà cung cấp được luân chuyể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

Tham chiếu kết nối VoIP

Mọi trường trong phản hồi kết nối, bằng chứng và nhập.

Tham chiếu số điện thoại

Gán tác nhân AI, chuyển giữa các tổ chức, giải phóng số.

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

Giờ bạn đã sở hữu số, hãy bắt đầu thực hiện cuộc gọi đi.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Sử dụng số điện thoại của riêng bạn (VoIP, API)

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

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

2. Tạo kết nối

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

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

5. Gán tác nhân AI và nhận cuộc gọi

Luân chuyển thông tin xác thực

Bước tiếp theo

Tham chiếu kết nối VoIP

Tham chiếu số điện thoại

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

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

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

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

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

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

​5. Gán tác nhân AI và nhận cuộc gọi

​Luân chuyển thông tin xác thực

​Bước tiếp theo

Tham chiếu kết nối VoIP

Tham chiếu số điện thoại

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

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

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

2. Tạo kết nối

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

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

5. Gán tác nhân AI và nhận cuộc gọi

Luân chuyển thông tin xác thực

Bước tiếp theo