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

Developer cookbook

從 Slack 或聊天應用程式執行通話

使用公開 API 建置你自己的 Slack、Teams 或網頁聊天機器人,用來發起通話、即時追蹤通話、引導智慧體並回答其問題。

你可以透過團隊已在使用的聊天應用程式操控智慧體。一則訊息即可發起通話。通話會在討論串中即時進行。你在討論串中的回覆會引導智慧體。當智慧體需要決策時,會在該處詢問你並等待你的回答。

ThunderPhone 不會為你代管此機器人。你(或你的程式設計智慧體)需建立一個小型伺服器,將聊天應用程式連接至公開 API。本頁說明所需元件。Slack、Microsoft Teams、Discord 或私有網頁聊天頁面皆使用相同方式;範例以 Slack 為例。

整體運作方式

你在聊天中執行的操作你的機器人呼叫發生的事
傳送「致電 Comcast 並取得服務中斷的預計恢復時間」使用訊息作為 context 呼叫 POST /v1/call智慧體撥出電話。你的機器人會為該通話建立討論串
監看討論串接收 telephony.turn Webhook智慧體或對方說的每一句話都會顯示在討論串中
在通話期間於討論串中回覆POST /v1/calls/{call_id}/whisper智慧體會私下收到你的備註並據此行動。對方永遠不會聽到
回答智慧體的問題你的工具端點傳回答案,或稍後透過 POST /v1/calls/{call_id}/tool-results 提供答案智慧體會帶著答案繼續通話;在保留模式中,對方同時會聽到保留音樂
閱讀結果接收 telephony.complete你的機器人會發布摘要與結果

你的機器人只需維護一項對應關係:哪個聊天討論串屬於哪個 call_id。

開始前

  • API 金鑰,請儲存在你的伺服器上,切勿放在瀏覽器或聊天中。 請在 整合 → API 金鑰 下建立金鑰(請參閱 建立伺服器 API 金鑰)。
  • 已啟用撥出功能的號碼與智慧體,用於撥打通話。訊息會成為每通通話的 context,因此一個通用智慧體即可處理所有工作。
  • 可接收 Webhook 的伺服器,例如 Railway、Fly.io、Render 或 你自己的主機。
  • Webhook 端點,指向該伺服器,並訂閱 telephony.turn 與 telephony.complete。只有列出這些事件的端點才會收到回合事件。請參閱 Webhook。 回合事件需要啟用智慧體的通話錄音,而通話結束時的 summary 需要智慧體的 產生通話摘要設定;否則這些欄位會保持空白。
  • 你自己的聊天應用程式。若使用 Slack,請在你的工作區中透過 api.slack.com/apps 建立應用程式。

1. 從訊息發起通話

當你的機器人收到訊息(私訊或 @提及)時,請立即確認 Slack 的請求(Slack 會重試任何未在 3 秒內確認的請求),並在背景處理其餘工作。確認寄件者是否有權撥打電話,然後以該訊息作為 context 發起通話:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

將傳回的 call_id 儲存到 Slack 討論串(channel 加上訊息的 ts),並在討論串中回覆(「正在撥號……」)。使用頻道和訊息的 ts 建立 idempotency_key(ts 僅在其頻道內唯一),以確保重試的 Slack 事件不會再次撥打電話。如果請求指定的是人名而非號碼,你的機器人會先查詢該人的號碼。ThunderPhone 只會撥打你傳送的 to_number。

2. 在討論串中追蹤通話

每個 telephony.turn webhook 都會帶有 call_id、發話者(role:智慧體為 assistant,另一方為 user)、text 以及該回合的 position。依 call_id 查詢討論串並張貼該行內容。

  • 在處理前,驗證每個 webhook。請參閱驗證 webhook 簽章。
  • **依封包的 event_id 去除重複項目,並依 position 排序。**Webhook 至少會傳送一次,且回合可能會以非預期順序送達。
  • 如果忙碌的通話可能淹沒討論串,請批次張貼內容;每隔幾秒張貼一次,比每行一則訊息更易讀。

當 telephony.complete 送達時,張貼通話如何結束(其 status 和 end_reason)、summary 及任何擷取的資料,然後結束討論串。欄位資訊請參閱通話完成。

3. 從討論串引導通話

當有人回覆進行中通話的討論串時,除非智慧體正在等待問題的答案(步驟 4),否則請將回覆作為耳語傳送;在該情況下,回覆就是答案:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

智慧體會私下聽到耳語,並將其融入下一個回合;另一方絕不會聽到耳語本身。耳語長度為 1 至 1000 個字元。409 表示通話已不再進行中:請告知討論串通話已結束。

4. 讓智慧體詢問你

為智慧體提供一個工具,例如具有一個 question 參數、會呼叫你伺服器的 ask_owner。將其建立為 API 連線,並連結至智慧體。 每個工具請求都會在其 X-ThunderPhone-Call-ID 標頭中帶有通話資訊。

有三種方式可以取得回覆。

保留通話,最長 10 分鐘。 將工具設為保留模式:spec.wait_mode "hold",並將 spec.timeout 設為最長 600 秒(未設定逾時時間時,保留 狀態會持續 20 秒)。可透過 API 設定,或請 Zeus 為你設定(應用程式的編輯器目前尚未提供這兩個欄位)。你的端點會將問題發布到通話的討論串,並立即以待處理結果回應:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

對方會先聽到智慧體說一句話,接著播放保留音樂。在電話選單或語音信箱中,智慧體會改用口語更新;全雙工智慧體則不會保留通話:它會將待處理回覆視為結果。當討論串收到回覆時,透過 POST /v1/calls/{call_id}/tool-results 傳送:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

音樂會淡出,智慧體會接著使用你的回覆繼續對話。如果在 timeout 前沒有人回覆,智慧體會得知尚未收到答案,並向對方提供後續選項。當通話有待處理問題時,其討論串中的下一則回覆就是答案:將其作為工具結果傳送,不要同時將其作為耳語傳送(耳語只有在工具傳回後才會送達智慧體)。請參閱 長時間等待。

在請求中等待(最長 3 分鐘)。 你的端點會發布問題、等待回覆後再傳回,例如 {"answer": "Yes, book Tuesday at 10."}。 透過 API 設定工具的 spec.timeout,最長可達 180 秒(預設值為 20)。為你的端點設定比此短幾秒的期限 (例如 170 秒),如此一來,即使沒有人回覆,它仍會傳回智慧體可採取行動的內容,例如 {"answer": null, "note": "No reply yet. Offer to take a message."}。達到其 timeout 的工具會以錯誤形式送達智慧體,而你的主機必須讓請求維持開啟那麼久。等待期間,智慧體會告訴對方它正在確認,約 12 秒後表示仍在處理,之後每約 15 秒提供一次簡短更新。此處也可使用保留模式:將 spec.wait_mode 設為 "hold",對方就會聽到音樂而非更新訊息。

透過耳語回覆。 你的端點會發布問題並立即傳回,例如 {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}。 收到回覆後,將其作為耳語傳送(步驟 3),智慧體會立即對此回應。若答案可能需要超過 10 分鐘,請使用此方式。通話不會被保留:你的提示應告訴智慧體在此期間該怎麼做,例如陪對方聊聊或提出稍後回電。

無論使用哪種方式,都請在智慧體的提示中說明何時使用工具,以及等待期間要對對方說什麼:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

需要預先規劃的限制

  • 你的端點必須在工具的 timeout 內回覆,最長為 180 秒。處於保留模式的工具可在結果待處理期間讓通話保留最長 600 秒。
  • 工具等待時,智慧體不會回應另一方。保留模式下,對方會聽到音樂;否則會聽到簡短的語音更新。
  • 耳語訊息最多為 1000 個字元。
  • telephony.turn 至少會傳送一次,且可能不依序送達。

安全性檢查清單

  • 將 API 金鑰保留在你的伺服器上。
  • 驗證 ThunderPhone 在 Webhook 和工具請求上的簽章,以及 Slack 在 Slack 請求上的簽署密鑰。兩種 ThunderPhone 簽章使用不同的密鑰:Webhook 傳送作業使用 Webhook 端點本身的密鑰,而工具請求使用你組織在 GET /v1/webhook 中的 Webhook 密鑰。
  • 決定哪些人可以發起通話:撥打前先檢查 Slack 使用者 ID。
  • 撥出通話遵循與其他通話相同的規則。請參閱撥出通話法規。

使用程式開發智慧體建置

讓你的程式開發智慧體參考 文件 MCP 伺服器與本頁面,並要求它建立「一個遵循本指南、供我的 ThunderPhone 智慧體使用的 Slack 機器人」。ThunderPhone app 中的智慧體 Zeus 可以設定智慧體端(Webhook 端點、工具和提示詞行),並在聊天中為機器人撰寫入門程式碼。