---
title: "Thực hiện cuộc gọi đi (API)"
description: "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
Gọi cho cả danh sách? Tính năng
[**Chiến dịch**](/vi/guides/outbound-campaigns) của bảng điều khiển
(`/dashboard/campaigns`) nhận CSV liên hệ và xử lý khung giờ gọi
theo múi giờ, đồng thời và chính sách thử lại cho bạn. Hướng dẫn này đề cập
đến từng cuộc gọi lập trình riêng lẻ.
## Điều kiện tiên quyết
Sử dụng số bạn sở hữu thông qua một
[kết nối VoIP](/api-reference/voip-connections), 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](/vi/guides/bring-your-own-numbers).
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).
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`](/api-reference/billing#get-billing-account) 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:
```bash
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:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` chỉ có nghĩa là yêu cầu đã được chấp nhận — cuộc gọi
**chưa được kết nối**. Thăm dò
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
để xem trạng thái trực tiếp (`in_progress` → `completed` / `failed`).
## 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`](/vi/webhooks/call-incoming):
```bash
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`](/vi/webhooks/events) —
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 đó:
```json
{
"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ý
| Lỗi | Cách khắc phục |
|-------|-----|
| `402 Payment Required` | Nạp thêm vào số dư hoặc bật nạp tự động |
| `400` với `code: destination_not_allowed` | ThunderPhone không gọi đến số đó: số không hợp lệ, số khẩn cấp, số tính phí cao, mã ngắn hoặc quốc gia bị trừng phạt. Từ số ThunderPhone, chỉ có thể gọi đến số thông thường tại Mỹ và Canada (không bao gồm số tính phí cao). `reason` cho biết trường hợp nào; xem [điểm đến bị chặn](/api-reference/outbound-calls#blocked-destinations) |
| `409` với `retryable: false` cho số ThunderPhone | Làm theo `code`: yêu cầu gọi đi trên trang Số điện thoại, chờ xét duyệt đang chờ xử lý hoặc sử dụng số đủ điều kiện khác |
| `429` với `code: platform_outbound_daily_limit_reached` | Tổ chức đã sử dụng hết cuộc gọi đi hôm nay từ số ThunderPhone. Chờ đến `resets_at` (00:00 UTC), yêu cầu giới hạn cao hơn trên trang Số điện thoại hoặc gọi từ số trên kết nối VoIP của riêng bạn |
| `429` với `code: concurrent_call_limit_reached` | Tổ chức đang có số cuộc gọi diễn ra bằng [giới hạn cuộc gọi đồng thời](/api-reference/introduction#call-limits) (mặc định là 20, bao gồm cuộc gọi đến, gọi đi, web và kiểm thử). Thử lại sau số giây trong header `Retry-After` hoặc khi một cuộc gọi kết thúc; gửi email đến support@thunderphone.com để tăng giới hạn |
| `429` với `code: same_number_too_soon` | Bạn đã gọi cùng `to_number` chưa đến 10 giây trước. Thử lại sau số giây trong header `Retry-After` |
| `409` với `retryable: false` cho số VoIP của khách hàng | Khắc phục trạng thái được nêu trong `code`; nếu xác minh thất bại, chạy [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| Xung đột idempotency `409` | Chỉ dùng lại khóa với yêu cầu đã chuẩn hóa ban đầu hoặc gửi khóa mới |
| `404 from_number is not registered to this organization` | Xác nhận `from_number` khớp với số điện thoại đang hoạt động trong tổ chức của bạn. Số đang được cấp phát, cấp phát thất bại, đang thu hồi hoặc đã thu hồi cũng trả về phản hồi này |
| `500` chỉ có trường `detail` | Chưa cấu hình trung kế gọi đi. Liên hệ bộ phận hỗ trợ; đây không phải vấn đề về trạng thái số mà bạn có thể tự khắc phục |
| `502 Bad Gateway` | Lỗi SIP / LiveKit tạm thời; có thể thử lại an toàn |
Xem [tài liệu tham chiếu cuộc gọi đi](/api-reference/outbound-calls#error-responses)
để 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`:
```json
{
"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
Mọi trường yêu cầu và mã lỗi.
Truyền trực tiếp các cuộc gọi đi đã hoàn tất đến hệ thống của bạn.
Tự động nạp lại để cuộc gọi đi không bao giờ thất bại do số dư.
Chạy thử tác nhân AI gọi đi trước khi triển khai thực tế.