ThunderPhone v3 現已上線。自助開通,價格低至每分鐘 2¢。查看公告

Developer cookbook

處理來電(API)

端對端流程:設定智能體、將其指派至電話號碼、接聽來電,並檢視逐字稿。

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

  1. 建立包含提示詞和語音的智能體。
  2. 配置(或帶入)電話號碼,並將智能體指派為其 入站處理程式。
  3. 致電該號碼。查看通話記錄、逐字稿和錄音。

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

1. 建立智能體

智能體整合了驅動通話的提示詞、聲音及產品級別。你亦可在智能體上設定通話限制,例如 max_call_duration_seconds 及 ring_duration_seconds。對於外撥通話,你亦可設定 max_hold_seconds,限制智能體在結束通話前等待保留的時間。Bolt 智能體亦支援 audio_tier、endpointing 及 intelligence ,以控制其聆聽及回應方式:intelligence 可設為 core 或 pro, 而 audio_tier(Hearing)可設為 lite、standard、plus 或 max(Max 目前尚未全面推出)。較舊的值(適用於 intelligence 的 lite 及 standard;適用於 hearing 的 lean、hearing 及 deep_hearing)仍然受支援。全雙工智能體會在支援的語言之間維持相同聲音, 因此這類通話不適用按語言切換聲音。智能體亦支援 intro_clip 及 intro_ring_count,可在智能體說話前播放預錄開場內容及最多兩下鈴聲。新智能體亦需要設定時區。如你的智能體支援多種語言,你可設定 language_switching,控制它在切換語言前是否先詢問,或跟隨來電者使用的語言。 你亦可在智能體上設定 words,控制其讀出特定詞語的方式,以及需要識別的詞語。 請參閱 智能體 了解所有設定欄位;最基本設定如下:

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": "bolt"
  }'

儲存回傳的 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"}'

回應會包括 E.164 格式的 id 和 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。對於 Bolt 智能體,你亦可在 API 寫入時於智能體上設定 audio_tier、endpointing 及 intelligence。API 仍接受較舊的 eagerness 名稱作為 endpointing 的別名。如果你的智能體使用帶有 trigger="call_start" 的 API 連線, ThunderPhone 可在每通電話開始時、問候語之前,使用其已儲存的 call_start_arguments 執行這些工具一次。

撥出通話的回撥

當有人回撥一個在過去 30 日內曾致電給他們的號碼,接聽的智能體會取得該通話的簡短背景資料:通話時間、由哪個智能體撥出,以及結果如何(無人接聽、語音信箱或已通話)。如該號碼未設定接聽來電的智能體,系統會將相同詳情以 returning_call 傳送至你的設定 webhook。如該號碼沒有 webhook,或 webhook 逾時或無法連線,通話會轉接至先前撥出該通電話的智能體,而不會結束通話。來電顯示可以偽造,因此只有管理員在「組織」→「一般」→「回撥」中啟用 分享先前通話的詳情 後,系統才會分享先前通話的摘要及變數。詳見回撥。

4. 接聽通話

使用你的電話撥打該號碼。智能體會接聽、按照你的提示詞介紹自己, 然後開始對話。

通話進行期間,會在 GET /v1/calls中顯示,狀態為 status="in_progress"。通話結束後,記錄會更新為包括 end_reason、duration_seconds、billable_minutes,以及(稍後提供的) 錄音 URL 和 AI 評分。

來電會計入你機構的 同時通話上限(預設為 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"

以及錄音 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。

如果你的智能體已設定擷取欄位,已完成通話的承載資料亦可包含結構化擷取資料。除非智能體覆寫此設定,否則通話摘要會以你的機構在 ThunderPhone 使用的語言撰寫。


下一步