---
title: "Xử lý cuộc gọi đến (API)"
description: "Toàn diện: cấu hình tác nhân AI, gán tác nhân đó cho một số điện thoại, nhận cuộc gọi và kiểm tra bản chép lời."
---
Tự tay xây dựng tác nhân đầu tiên? Dashboard hướng dẫn chính xác
quy trình này — xây dựng tác nhân, thêm số, mô phỏng, xem lại — bằng
trình hướng dẫn từng bước. Bắt đầu tại
[khởi động nhanh trên dashboard](/vi/quickstart-dashboard).
Quy trình chuẩn để "trả lời điện thoại bằng AI", ngay từ terminal của bạn.
Bạn sẽ:
1. Tạo tác nhân với prompt và giọng nói.
2. Cấp phát (hoặc mang đến) một số điện thoại và gán tác nhân làm
trình xử lý cuộc gọi đến.
3. Gọi đến số đó. Quan sát nhật ký cuộc gọi, bản chép lời và bản ghi âm.
Tổng số lệnh gọi API: bốn. Tổng thời gian: dưới năm phút.
## 1. Tạo tác nhân
Một tác nhân AI kết hợp prompt, giọng nói và gói sản phẩm sẽ điều hành
cuộc gọi. Bạn cũng có thể đặt các giới hạn cuộc gọi như `max_call_duration_seconds`
và `ring_duration_seconds` trên tác nhân AI. Tác nhân AI cũng hỗ trợ `intro_clip`
và `intro_ring_count` để phát lời giới thiệu ghi âm sẵn và tối đa hai hồi chuông trước khi
tác nhân AI bắt đầu nói. Tác nhân AI mới cũng cần có múi giờ.
Xem [Tác nhân AI](/api-reference/agents) để biết mọi trường cấu hình; cấu hình
tối thiểu là:
```bash
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Support",
"prompt": "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
"voice": "john",
"product": "spark"
}'
```
Lưu `id` được trả về — bạn sẽ cần nó ở bước 2.
Chọn `spark` cho Hỏi đáp đơn giản với chi phí thấp nhất, chọn `bolt` khi
tốc độ là quan trọng nhất. Nâng cấp lên `storm-base-with-ack` khi prompt của bạn
cần suy luận sâu hơn và có thể chấp nhận khoảng đệm nửa giây trong khi
mô hình suy nghĩ. Xem
[các gói sản phẩm](/api-reference/agents#product-tiers-at-a-glance).
## 2. Lấy số điện thoại
Nếu bạn chỉ cần một số để gọi thử, hãy lấy một số ThunderPhone
từ nhóm số của ThunderPhone:
```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'
```
Phản hồi bao gồm `id` và `number` theo định dạng E.164. Các số ThunderPhone
bắt đầu ở `status="provisioning"` và chuyển thành `active` trong vài
giây — thăm dò
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
để theo dõi quá trình chuyển đổi nếu bạn cần.
Các số ThunderPhone ban đầu chỉ nhận cuộc gọi đến. Quản trị viên tổ chức có thể yêu cầu
gọi ra từ trang Số điện thoại. ThunderPhone xem xét thủ công từng
yêu cầu; sau khi được phê duyệt, các số có thể thực hiện cuộc gọi và chạy
chiến dịch. Số VoIP của khách hàng không thay đổi.
## 3. Gán tác nhân
Liên kết tác nhân ở bước 1 với hướng cuộc gọi đến của số:
```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
Vậy là xong — số đã hoạt động. Sau khi gọi ra được phê duyệt cho tổ chức của bạn,
bạn cũng có thể đặt `outbound_agent_id` trong cùng PATCH. Cho đến lúc đó,
API sẽ từ chối phép gán này với mã `400`.
Nếu bạn định tuyến cuộc gọi đến qua webhook cấu hình thay vì `inbound_agent_id` cố định, webhook đó giờ đây có thể trả về `timezone` theo từng cuộc gọi cùng với `agent_id` và `variables`.
## 4. Nhận cuộc gọi
Gọi đến số từ điện thoại của bạn. Tác nhân sẽ bắt máy, tự giới thiệu
theo prompt của bạn và cuộc trò chuyện bắt đầu.
Trong khi cuộc gọi đang diễn ra, nó xuất hiện trong
[`GET /v1/calls`](/api-reference/calls#list-calls) với
`status="in_progress"`. Khi cuộc gọi kết thúc, bản ghi được cập nhật với
`end_reason`, `duration_seconds`, `billable_minutes` và (cuối cùng)
URL bản ghi âm cùng điểm đánh giá AI.
Cuộc gọi đến được tính vào
[giới hạn cuộc gọi đồng thời](/api-reference/introduction#call-limits) của tổ chức bạn (mặc định 20
cuộc gọi đang diễn ra, dùng chung với cuộc gọi đi, web và thử nghiệm). Cuộc gọi đến khi đã đạt giới hạn sẽ bị từ chối trước khi tác nhân AI
trả lời và bị ngắt, không bị tính phí, đồng thời được ghi nhận là cuộc gọi thất bại với lý do kết thúc
`concurrent_call_limit_reached`. Gửi email đến support@thunderphone.com nếu bạn
cần giới hạn cao hơn.
## 5. Kiểm tra kết quả
Lấy danh sách cuộc gọi gần đây:
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Lấy bản chép lời:
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Và URL bản ghi âm (có chữ ký, thời hạn ngắn):
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Nếu bạn đã đăng ký
[webhook `telephony.complete`](/vi/webhooks/events),
bạn sẽ nhận được cùng dữ liệu dưới dạng POST đến máy chủ của mình — xem
[call.complete](/vi/webhooks/call-complete).
Nếu tác nhân AI của bạn đã cấu hình các trường trích xuất, payload cuộc gọi hoàn tất
cũng có thể bao gồm dữ liệu được trích xuất có cấu trúc.
---
## Bước tiếp theo
Chọn tác nhân AI khác nhau cho từng người gọi dựa trên số điện thoại hoặc
logic tùy chỉnh trong webhook.
Cho phép tác nhân AI gọi API của bạn trong lúc hội thoại.
Định tuyến trực tiếp người gọi hoặc sàng lọc điểm đến trước khi kết nối.
Truyền từng cuộc gọi đã kết thúc đến quy trình CRM / phân tích của bạn.
Tự động chấm điểm mọi cuộc gọi và chuyển những cuộc gọi bị gắn cờ để xem xét.