> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sử dụng số điện thoại 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 — và nhập số điện thoại từ tài khoản hiện có của bạn.
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.
```bash theme={null}
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" }
}'
```
```json Response theme={null}
{
"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:
```bash theme={null}
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](/api-reference/voip-connections#connection-object)
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:
```bash theme={null}
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:
```bash theme={null}
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](/api-reference/phone-numbers)
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).
```bash theme={null}
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](/vi/guides/handle-inbound-calls) và
[Thực hiện cuộc gọi đi](/vi/guides/place-outbound-calls).
## 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:
```bash theme={null}
# 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
Mọi trường trong phản hồi kết nối, bằng chứng và nhập.
Gán tác nhân AI, chuyển giữa các tổ chức, giải phóng số.
Giờ bạn đã sở hữu số, hãy bắt đầu thực hiện cuộc gọi đi.