Developer cookbook

Xử lý cuộc gọi đến (API)

Trọn quy trình: 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.

Luồng 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 AI 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à chỉ định tác nhân AI 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 AI#

Một tác nhân AI gói gọn prompt, giọng nói và gói sản phẩm sẽ vận hành cuộc gọi. Xem Tác nhân AI để biết mọi trường cấu hình; mức tối thiểu là:

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.

2. Lấy số điện thoại#

Nếu bạn chỉ cần một số để gọi thử, hãy cấp phát số demo từ nhóm số của ThunderPhone:

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 một id và một number theo định dạng E.164. Số demo bắt đầu ở status="provisioning" và trở thành active trong vài giây — thăm dò GET /v1/phone-numbers/{id} để theo dõi trạng thái chuyển đổi nếu cần.

3. Chỉ định tác nhân AI#

Liên kết tác nhân AI từ bước 1 với chiều cuộc gọi đến của số điện thoại:

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ố điện thoại đã hoạt động. Bạn cũng có thể đặt outbound_agent_id trong cùng PATCH để số điện thoại cũng sẵn sàng gọi đi.

4. Nhận cuộc gọi#

Gọi đến số đó từ điện thoại của bạn. Tác nhân AI bắt máy, tự giới thiệu theo prompt của bạn, rồi cuộc trò chuyện bắt đầu.

Trong khi cuộc gọi đang diễn ra, cuộc gọi sẽ xuất hiện trong GET /v1/calls với status="in_progress". Khi cuộc gọi kết thúc, bản ghi sẽ được cập nhật với end_reason, duration_seconds, billable_minutes và (sau đó) URL bản ghi âm cùng đánh giá AI.

5. Kiểm tra kết quả#

Lấy danh sách các cuộc gọi gần đây:

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:

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ý, tồn tại trong thời gian ngắn):

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 bạn sẽ nhận cùng dữ liệu dưới dạng POST đến máy chủ của bạn — xem call.complete.

Các bước tiếp theo#