> ## 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.
# Bắt đầu nhanh (API)
> Trả lời cuộc gọi điện thoại đầu tiên của bạn bằng tác nhân AI qua bốn lệnh gọi REST.
Hướng dẫn này sẽ chỉ cho bạn bốn lệnh gọi REST cần thiết để trả lời
cuộc gọi điện đầu tiên bằng tác nhân AI.
Bạn sẽ cần một [tài khoản ThunderPhone](https://app.thunderphone.com).
Đăng ký miễn phí và mất chưa đến một phút. Bạn thích nhấp chuột hơn dùng curl?
[Hướng dẫn nhanh trên bảng điều khiển](/vi/quickstart-dashboard) giúp bạn thực hiện
cùng cuộc gọi đầu tiên mà không cần viết mã.
## Bước 1: Lấy khóa API
Mở [app.thunderphone.com](https://app.thunderphone.com).
Vào **Tổ chức → Khóa** trong bảng điều khiển.
Nhấp vào **Tạo khóa**, đặt tên cho khóa rồi sao chép giá trị
`sk_live_...`. Khóa thô chỉ hiển thị **một lần duy nhất** — hãy lưu
ngay vào trình quản lý bí mật của bạn.
Gặp khó khăn? [Tạo khóa API máy chủ](/vi/guides/api-keys) hướng dẫn
quy trình này chi tiết từng bước, và trợ lý đồng hành trong ứng dụng có thể
làm nổi bật trực tiếp từng thành phần điều khiển cho bạn.
Trong toàn bộ hướng dẫn này, hãy thay `sk_live_YOUR_API_KEY` bằng giá trị
bạn vừa sao chép. Khóa tự động xác định tổ chức của bạn, vì vậy
bạn không bao giờ cần thêm id tổ chức vào URL.
## Bước 2: Tạo tác nhân
Một tác nhân xác định cách AI xử lý hội thoại — prompt, giọng nói,
gói sản phẩm, công cụ và điều kiện đủ để dùng widget.
```bash cURL theme={null}
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark"
}'
```
```python Python theme={null}
import os, requests
agent = requests.post(
"https://api.thunderphone.com/v1/agents",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={
"name": "Customer Support",
"prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
"voice": "john",
"product": "spark",
},
).json()
print("Agent id:", agent["id"])
```
```javascript Node.js theme={null}
const agent = await fetch("https://api.thunderphone.com/v1/agents", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Customer Support",
prompt: "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
voice: "john",
product: "spark",
}),
}).then((r) => r.json());
console.log("Agent id:", agent.id);
```
Gói sản phẩm: `spark` được tối ưu cho chi phí, `bolt` cho tốc độ, và
`storm-base` / `storm-extra` cho khả năng xử lý prompt phức tạp. Xem
[Tác nhân](/api-reference/agents#product-tiers-at-a-glance) để biết phần
so sánh đầy đủ.
## Bước 3: Cấp một số điện thoại
Lệnh gọi này yêu cầu một số từ nhóm số demo của ThunderPhone và gán
tác nhân AI mới của bạn làm trình xử lý cuộc gọi đến. (Để sử dụng số điện thoại của riêng bạn từ nhà cung cấp VoIP,
hãy xem [kết nối VoIP](/api-reference/voip-connections)
thay vào đó.)
```bash cURL theme={null}
# First provision
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"}'
# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/ \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
```python Python theme={null}
number = requests.post(
"https://api.thunderphone.com/v1/phone-numbers",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"area_code": "415"},
).json()
requests.patch(
f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])
```
Số mới của bạn bắt đầu ở trạng thái `status="provisioning"` và chuyển sang
`active` trong vài giây; đến khi bạn đóng trình duyệt,
số điện thoại đã sẵn sàng nhận cuộc gọi.
## Bước 4 (tùy chọn): Thiết lập webhook
Để nhận sự kiện theo thời gian thực (định tuyến cuộc gọi động, xử lý sau cuộc gọi), hãy thêm
một endpoint webhook. Chỉ đăng ký các sự kiện bạn cần.
```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Prod webhook",
"url": "https://your-server.com/thunderphone-webhook",
"events": ["telephony.incoming", "telephony.complete"]
}'
```
Phản hồi chứa một `secret` dùng một lần — hãy sao chép nó vào trình
quản lý secret của bạn. Dùng secret đó để xác minh header
`X-ThunderPhone-Signature` trên các yêu cầu đến (xem
[tổng quan về Webhook](/vi/webhooks/overview)).
## Bước 5: Kiểm thử tác nhân AI
Gọi đến số điện thoại bạn vừa cấp. Tác nhân AI sẽ bắt máy, giới thiệu
bản thân và làm theo prompt của bạn.
Kiểm tra cuộc gọi sau khi kết thúc:
```bash theme={null}
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Đi sâu vào một cuộc gọi cụ thể để lấy bản chép lời và URL bản ghi âm:
```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
***
## Bước tiếp theo
Cho phép tác nhân AI gọi API của bạn trong cuộc trò chuyện.
Kích hoạt cuộc gọi từ mã của riêng bạn.
Phản hồi các sự kiện cuộc gọi theo thời gian thực.
Mọi endpoint công khai, đều được tài liệu hóa.