Open in
透過 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 端點、工具及提示詞行),並在聊天中為機械人編寫入門程式碼。