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 金鑰,請儲存在你的伺服器上,切勿放在瀏覽器或聊天中。 請在 整合 → 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 端點、工具和提示詞行),並在聊天中為機器人撰寫入門程式碼。