處理來電（API）

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

1. 建立具備提示詞及語音的智能體。
2. 配置（或帶入）電話號碼，並將智能體指派為其 來電處理程式。
3. 致電該號碼。查看通話記錄、逐字稿及錄音。

API 呼叫總數：四次。所需時間：少於五分鐘。

1. 建立智能體

智能體整合用於處理通話的提示詞、語音及產品級別。 請參閱 智能體了解所有設定 欄位；最低要求如下：

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 需要使用它。

2. 取得電話號碼

如只需要一個可供撥打測試的號碼，可從 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"}'

回應包括採用 E.164 格式的 id 及 number。示範號碼 初始狀態為 status="provisioning"，並會在數秒內變為 active——如有需要，可輪詢 GET /v1/phone-numbers/{id} 以查看狀態轉換。

3. 指派智能體

將步驟 1 的智能體關聯至該號碼的來電方向：

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中顯示， 狀態為 status="in_progress"。通話結束後，記錄會更新 end_reason、duration_seconds、billable_minutes，以及（稍後） 錄音 URL 和 AI 評分。

5. 檢視結果

取得最近通話清單：

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

取得逐字稿：

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

以及錄音 URL（短時效、已簽署）：

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

如你已訂閱 telephony.complete webhook， 你將會以 POST 形式在伺服器接收相同資料——請參閱 call.complete。

下一步