---
title: "處理來電（API）"
description: "端到端流程：設定智慧體、將其指派給電話號碼、接聽來電，並檢視逐字稿。"
---
要親手建立你的第一個智慧體嗎？控制台會透過引導精靈帶你完成完全相同的
流程——建立智慧體、加入號碼、模擬、檢視。從
[控制台快速入門](/zh-Hant/quickstart-dashboard)開始。
從終端機完成標準的「由人工智慧接聽電話」流程。
你將：
1. 使用提示詞和語音建立智慧體。
2. 佈建（或帶入）電話號碼，並將智慧體指派為其
入站處理者。
3. 撥打該號碼。查看通話紀錄、逐字稿和錄音。
API 呼叫總數：四次。總時間：五分鐘內。
## 1. 建立智慧體
智慧體會整合用來驅動通話的提示詞、語音和產品方案等級。你也可以在智慧體上設定通話限制，例如 `max_call_duration_seconds`
和 `ring_duration_seconds`。智慧體也支援 `intro_clip`
和 `intro_ring_count`，可在智慧體開始說話前播放預錄開場內容及最多兩次鈴響。新的智慧體也需要設定時區。如果你的智慧體支援多種語言，可以設定 `language_switching`，控制它是在切換語言前詢問，還是依照來電者使用的語言回應。
請參閱 [智慧體](/api-reference/agents) 了解所有設定欄位；最基本的設定如下：
```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"
}'
```
儲存回傳的 `id`——你會在步驟 2 需要它。
簡單問答且希望最低成本時，選擇 `spark`；速度最重要時，選擇 `bolt`。
當提示詞需要更深入的推理，且能接受模型思考時有半秒鐘的填充語音，
請升級至 `storm-base-with-ack`。請參閱
[產品方案](/api-reference/agents#product-tiers-at-a-glance)。
## 2. 取得電話號碼
如果你只需要一個可撥打測試的號碼，請從 ThunderPhone 的號碼池
取得 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"}'
```
回應包含 `id` 和 E.164 格式的 `number`。ThunderPhone
號碼初始狀態為 `status="provisioning"`，並會在數秒內變為 `active`——如果你
想查看狀態轉換，請輪詢
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)。
ThunderPhone 號碼一開始僅支援入站通話。組織管理員可從「電話號碼」頁面申請
出站通話功能。ThunderPhone 會人工審核每項申請；核准後，號碼即可撥打電話並執行
行銷活動。客戶的 VoIP 號碼不受影響。
## 3. 指派智慧體
將步驟 1 的智慧體與號碼的入站方向建立關聯：
```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}'
```
完成——該號碼已啟用。你的組織獲准使用出站通話後，也可以在相同的 PATCH 中
設定 `outbound_agent_id`。在此之前，API 會以 `400` 拒絕該指派。
如果你透過設定 Webhook 路由來電，而非使用固定的
`inbound_agent_id`，該 Webhook 現在可隨 `agent_id` 和 `variables` 一併針對每通電話回傳 `timezone`。
## 4. 接聽通話
使用你的電話撥打該號碼。智慧體會接聽、依照你的提示詞自我介紹，
然後開始對話。
通話進行期間，會顯示在
[`GET /v1/calls`](/api-reference/calls#list-calls)中，狀態為
`status="in_progress"`。通話結束後，紀錄會更新
`end_reason`、`duration_seconds`、`billable_minutes`，以及（最終）
錄音 URL 和人工智慧評分。
來電會計入你組織的
[同時通話數上限](/api-reference/introduction#call-limits)（預設為 20
通進行中的通話，與撥出、網路及測試
通話共用）。達到上限時撥入的通話會在智慧體接聽前遭拒絕並掛斷，不會計費，且會記錄為失敗通話，結束原因為 `concurrent_call_limit_reached`。如果你
需要提高上限，請寄信至 support@thunderphone.com。
## 5. 檢查結果
取得近期通話清單：
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
取得逐字稿：
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
以及錄音網址（短效期、已簽章）：
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
如果你訂閱了
[`telephony.complete` webhook](/zh-Hant/webhooks/events)，
系統會以 POST 將相同資料傳送至你的伺服器——請參閱
[call.complete](/zh-Hant/webhooks/call-complete)。
如果你的智慧體已設定擷取欄位，已完成通話的酬載也可能包含結構化的擷取資料。
---
## 後續步驟
根據電話號碼或 webhook 中的自訂邏輯，為每位來電者選擇不同的智慧體。
讓智慧體在對話期間呼叫你的 API。
直接轉接來電者，或在接通前先篩選目的地。
將每通已完成的通話串流至你的 CRM／分析流程。
自動為每通通話評分，並將標記的通話送交審查。