> ## 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.

# Thực hiện cuộc gọi đi (API)

> Kích hoạt cuộc gọi đi do tác nhân AI thực hiện từ mã của riêng bạn — cho các luồng 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 mặt bạn. Các trường hợp sử dụng phổ biến:

* 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

<Note>
  Gọi cho cả danh sách? Tính năng
  [**Chiến dịch**](/vi/guides/outbound-campaigns) của dashboard
  (`/dashboard/campaigns`) nhận CSV liên hệ và xử lý các khung giờ gọi
  theo múi giờ, mức độ đồng thời và chính sách thử lại cho bạn.
  Hướng dẫn này dành cho từng cuộc gọi lập trình riêng lẻ.
</Note>

## Điều kiện tiên quyết

<Steps>
  <Step title="Cung cấp số VoIP">
    Cuộc gọi đi yêu cầu bạn sở hữu `from_number` thông qua một
    [kết nối VoIP](/api-reference/voip-connections). Số demo chỉ dùng
    cho cuộc gọi đến. Xem
    [Sử dụng số điện thoại của riêng bạn](/vi/guides/bring-your-own-numbers).
  </Step>

  <Step title="Tạo tác nhân AI">
    Prompt dành cho cuộc gọi đi thường bắt đầu bằng việc tác nhân
    tự giới thiệu và nêu mục đích — "Chào bạn, đây là Acme gọi để
    xác nhận lịch hẹn của bạn vào 3 giờ chiều ngày mai…" Đặt
    `outbound_speak_order` thành `agent_first` (mặc định).
  </Step>

  <Step title="Duy trì số dư dương">
    Cuộc gọi đi trả về `402 Payment Required` nếu số dư ≤
    `$0.00`. Nạp tiền qua
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    hoặc bật [tự động nạp lại](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Thực hiện cuộc gọi với tác nhân đã lưu

Cách đơn giản nhất — tham chiếu tác nhân bằng id:

```bash theme={null}
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":   "+14155550199",
    "agent_id":    12
  }'
```

Phản hồi:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `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)
  để lấy trạng thái hiện tại (`in_progress` → `completed` / `failed`).
</Warning>

## Thực hiện cuộc gọi với 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 theme={null}
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":   "+14155550199",
    "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) —
đây là 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}` vài giây một lần;
bản ghi sẽ bao gồm `end_reason`, `duration_seconds` và URL bản ghi âm
sau khi cuộc gọi kết thúc.

## Các lỗi cần xử lý

| Lỗi                                                      | Cách khắc phục                                                                                              |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Nạp tiền vào số dư hoặc bật tự động nạp lại                                                                 |
| `403` gọi đi bị chặn (số demo)                           | Dùng số VoIP thay thế                                                                                       |
| `403` gọi đi bị chặn (VoIP chưa xác minh)                | Chạy [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Xác nhận `from_number` khớp với số điện thoại bạn sở hữu                                                    |
| `502 Bad Gateway`                                        | Lỗi SIP / LiveKit tạm thời; có thể thử lại an toàn                                                          |

## 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 theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "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 (15 phút).

***

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Tham chiếu cuộc gọi đi" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Mọi trường yêu cầu và mã lỗi.
  </Card>

  <Card title="Nhận call.complete" icon="bolt" href="/vi/webhooks/call-complete">
    Truyền các cuộc gọi đi đã kết thúc đến hệ thống của bạn.
  </Card>

  <Card title="Thanh toán" icon="credit-card" href="/api-reference/billing">
    Tự động nạp lại để cuộc gọi đi không bao giờ thất bại do số dư.
  </Card>

  <Card title="Kiểm thử tác nhân AI gọi đi" icon="flask" href="/vi/guides/test-agents">
    Chạy thử tác nhân AI gọi đi trước khi đưa vào môi trường production.
  </Card>
</CardGroup>