> ## 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.

# 處理來電（API）

> 端到端流程：設定智慧體、將其指派給電話號碼、接聽來電，並檢視逐字稿。

<Note>
  第一次手動建立智慧體？控制台會透過引導式精靈帶你走完完全相同的
  流程——建立智慧體、新增號碼、模擬、檢視。從
  [控制台快速入門](/zh-Hant/quickstart-dashboard)開始。
</Note>

透過終端機完成標準的「使用 AI 接聽電話」流程。
你將會：

1. 建立具備提示詞與語音的智慧體。
2. 佈建（或自備）電話號碼，並將智慧體指派為其入站處理者。
3. 撥打該號碼，查看通話紀錄、逐字稿與錄音。

API 呼叫總數：四次。總時間：不到五分鐘。

## 1. 建立智慧體

智慧體會整合用於處理通話的提示詞、語音與產品方案。請參閱
[智慧體](/api-reference/agents)以了解所有設定欄位；最低需求如下：

```bash 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":    "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 用到它。

<Tip>
  簡單問答且希望成本最低時，選擇 `spark`；速度最重要時，選擇 `bolt`。
  當提示詞需要更深入的推理，且可容忍模型思考時約半秒的填充語時，請升級至
  `storm-base-with-ack`。請參閱
  [產品方案](/api-reference/agents#product-tiers-at-a-glance)。
</Tip>

## 2. 取得電話號碼

若你只需要一個可供撥打的號碼，請從 ThunderPhone 的號碼池佈建示範號碼：

```bash theme={null}
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"}'
```

回應會包含 E.164 格式的 `id` 與 `number`。示範號碼起始狀態為
`status="provisioning"`，並會在幾秒內變為 `active`——如有需要，可輪詢
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
查看狀態轉換。

<Note>
  用於正式環境時，請略過示範號碼，並
  [透過 VoIP 自備號碼](/zh-Hant/guides/bring-your-own-numbers)。
  示範號碼僅支援入站通話，且有用量上限。
</Note>

## 3. 指派智慧體

將步驟 1 的智慧體與號碼的入站方向建立關聯：

```bash theme={null}
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`，
讓該號碼也能用於撥出電話。

## 4. 接聽來電

使用你的電話撥打該號碼。智慧體會接聽、依照你的提示詞自我介紹，
然後開始對話。

通話進行期間，會在
[`GET /v1/calls`](/api-reference/calls#list-calls)中顯示，狀態為
`status="in_progress"`。通話結束後，紀錄會更新 `end_reason`、
`duration_seconds`、`billable_minutes`，以及（最終）錄音 URL 與 AI 評分。

## 5. 檢查結果

擷取最近通話清單：

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

取得逐字稿：

```bash theme={null}
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

以及錄音 URL（短期有效，已簽署）：

```bash theme={null}
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)。

***

## 後續步驟

<CardGroup cols={2}>
  <Card title="每通電話的動態設定" icon="bolt" href="/zh-Hant/guides/dynamic-call-config">
    根據電話號碼或 webhook 中的自訂邏輯，為每位來電者選擇不同的智慧體。
  </Card>

  <Card title="新增工具整合" icon="screwdriver-wrench" href="/zh-Hant/guides/build-tool-integration">
    讓智慧體在對話過程中呼叫你的 API。
  </Card>

  <Card title="接收 call.complete webhook" icon="bolt" href="/zh-Hant/webhooks/call-complete">
    將每通完成的通話串流至你的 CRM／分析流程。
  </Card>

  <Card title="AI 評分與問題報告" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    自動為每通電話評分，並將標記的通話送交審查。
  </Card>
</CardGroup>