---
title: "Bắt đầu nhanh (API)"
description: "Trả lời cuộc gọi điện thoại đầu tiên bằng tác nhân AI: lấy khóa API, tạo tác nhân, cấp số điện thoại và thực hiện cuộc gọi kiểm thử trực tiếp — tất cả thông qua REST API."
---
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 cần có [tài khoản ThunderPhone](https://app.thunderphone.com).
Đăng ký miễn phí và mất chưa đến một phút. Thích nhấp chuột hơn dùng curl?
[Hướng dẫn nhanh trên dashboard](/vi/quickstart-dashboard) giúp bạn thực hiện
cuộc gọi đầu tiên tương tự 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 dashboard.
Nhấp vào **Tạo khóa**, đặt tên cho khóa và sao chép giá trị
`sk_live_...`. Khóa thô chỉ hiển thị **một lần** — 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
chi tiết từng bước của quy trình này, 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 suốt 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 tác nhân AI xử lý cuộc hội thoại — prompt, giọng nói,
gói sản phẩm, công cụ và điều kiện đủ điều kiện cho widget.
```bash cURL
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
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
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 năng lực xử lý prompt phức tạp. Xem
[Tác nhân](/api-reference/agents#product-tiers-at-a-glance) để biết
bảng 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 ThunderPhone cấp một số 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. (Để dùng số riêng của bạn từ nhà cung cấp VoIP, hãy xem [kết nối VoIP](/api-reference/voip-connections).)
```bash cURL
# 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
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 ở `status="provisioning"` và chuyển sang `active` trong vài giây; khi bạn đóng trình duyệt, số đã 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 endpoint webhook. Chỉ đăng ký các sự kiện bạn cần.
```bash
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ý bí mật của bạn. Dùng secret đó để xác minh header `X-ThunderPhone-Signature-V2` trên các yêu cầu gửi đế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ố bạn vừa cấp. Tác nhân AI sẽ bắt máy, tự giới thiệu và làm theo prompt của bạn.
Kiểm tra cuộc gọi sau khi kết thúc:
```bash
curl https://api.thunderphone.com/v1/calls \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Xem chi tiết một cuộc gọi cụ thể để lấy bản chép lời và URL bản ghi âm:
```bash
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 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.