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

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.

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 để biết mọi trường cấu hình; cấu hình 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 lấy một số ThunderPhone 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 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} để theo dõi quá trình chuyển đổi nếu bạn cần.

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ố:

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 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 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:

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ý, thời hạn 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 cùng dữ liệu dưới dạng POST đến máy chủ của mình — xem 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#