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 金鑰,儲存在你的伺服器上,絕不可放在瀏覽器或聊天中。 可在 組織設定 → 金鑰 下建立(請參閱 金鑰)。
  • 用於通話的已啟用撥出功能的號碼及智能體。訊息會 成為每次通話的 context,因此一個通用智能體即可處理所有工作。
  • 伺服器,可接收 webhook,例如 Railway、Fly.io、Render 或 你自己的主機。
  • 指向該伺服器並已訂閱 telephony.turn 及 telephony.complete 的 webhook 端點。轉換事件只會傳送至 列出該事件的端點。請參閱 Webhooks。 轉換事件需要啟用智能體的通話錄音,而通話結束時的 summary 則需要啟用智能體的產生通話摘要設定;如未啟用, 這些欄位會維持空白。
  • 你自己的聊天應用程式。 如使用 Slack,請在你的工作區於 api.slack.com/apps 建立應用程式。

1. 從訊息開始通話

當你的機械人收到訊息(直接訊息或 @mention)時, 立即確認 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 排序。 系統至少會傳送一次,而回合亦可能亂序到達。
  • 將多行內容分批發布,如繁忙的通話會令討論串出現大量訊息; 每隔數秒發布一次,會比每行一則訊息更易閱讀。

當收到 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 標頭附帶通話 ID。

有三種方式可取得回覆。

保留通話(最長 10 分鐘)。 將工具設為保留模式:透過 API 設定 spec.wait_mode 為 "hold",並將 spec.timeout 設為最多 600 秒(如未設定逾時,保留 會持續 20 秒)(控制台編輯器暫時未提供這兩個欄位)。你的端點會將問題發佈至通話的討論串,並立即以下列待處理結果回覆:

{"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 請求的簽署密鑰。兩種 ThunderPhone 簽名使用不同的密鑰:webhook 傳送使用 webhook 端點本身的密鑰,而工具請求則使用你機構在 GET /v1/webhook 中設定的 webhook 密鑰。
  • 決定哪些人可發起通話:在撥號前檢查 Slack 使用者 ID。
  • 外撥通話須遵守與其他通話相同的規則。請參閱外撥通話法規。

使用編碼智能體建立

將你的編碼智能體指向 docs MCP 伺服器及本頁,並要求它建立「一個遵循本指南、供我的 ThunderPhone 智能體使用的 Slack 機械人」。ThunderPhone app 中的助理 Zeus 可設定智能體一側的內容(webhook 端點、工具及提示詞行),並在聊天中為機械人編寫入門程式碼。