處理來電（API）

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

從終端機完成標準的「由人工智慧接聽電話」流程。 你將：

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

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

1. 建立智慧體#

智慧體會整合用來驅動通話的提示詞、語音和產品方案等級。你也可以在智慧體上設定通話限制，例如 max_call_duration_seconds 和 ring_duration_seconds。智慧體也支援 intro_clip 和 intro_ring_count，可在智慧體開始說話前播放預錄開場內容及最多兩次鈴響。新的智慧體也需要設定時區。如果你的智慧體支援多種語言，可以設定 language_switching，控制它是在切換語言前詢問，還是依照來電者使用的語言回應。 請參閱 智慧體 了解所有設定欄位；最基本的設定如下：

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 的號碼池 取得 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"}'

回應包含 id 和 E.164 格式的 number。ThunderPhone 號碼初始狀態為 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。在此之前，API 會以 400 拒絕該指派。

如果你透過設定 Webhook 路由來電，而非使用固定的 inbound_agent_id，該 Webhook 現在可隨 agent_id 和 variables 一併針對每通電話回傳 timezone。

4. 接聽通話#

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

通話進行期間，會顯示在 GET /v1/calls中，狀態為 status="in_progress"。通話結束後，紀錄會更新 end_reason、duration_seconds、billable_minutes，以及（最終） 錄音 URL 和人工智慧評分。

來電會計入你組織的 同時通話數上限（預設為 20 通進行中的通話，與撥出、網路及測試 通話共用）。達到上限時撥入的通話會在智慧體接聽前遭拒絕並掛斷，不會計費，且會記錄為失敗通話，結束原因為 concurrent_call_limit_reached。如果你 需要提高上限，請寄信至 support@thunderphone.com。

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"

以及錄音網址（短效期、已簽章）：

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

如果你訂閱了 telephony.complete webhook， 系統會以 POST 將相同資料傳送至你的伺服器——請參閱 call.complete。

如果你的智慧體已設定擷取欄位，已完成通話的酬載也可能包含結構化的擷取資料。

後續步驟#