---
title: "透過 Slack 或聊天應用程式執行通話"
description: "使用公開 API 建立專屬 Slack、Teams 或網頁聊天機械人，以啟動通話、即時跟進通話、引導智能體並回答其問題。"
---

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

ThunderPhone 不會代你託管此機械人。你（或你的編碼智能體）需要建立一個
小型伺服器，將你的聊天應用程式連接至公開 API。本頁展示
所需元件。這些元件適用於 Slack、Microsoft Teams、Discord 或私人
網頁聊天頁面；以下範例使用 Slack。

## 運作方式

| 你在聊天中執行的操作 | 你的機械人呼叫 | 結果 |
|---|---|---|
| 傳送「致電 Comcast 並取得服務中斷的預計恢復時間」 | 使用訊息作為 `context` 呼叫 [`POST /v1/call`](/api-reference/outbound-calls) | 智能體撥號。你的機械人會為通話開啟討論串 |
| 觀看討論串 | 接收 [`telephony.turn`](/yue/webhooks/events) webhook | 智能體或另一方說出的每一句話都會顯示於討論串中 |
| 在通話期間於討論串中回覆 | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | 智能體會私下接收你的訊息並據此行動。另一方永遠不會聽到 |
| 回答智能體的問題 | 你的[工具端點](/yue/guides/build-tool-integration)會傳回答案，或稍後透過 [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) 傳送答案 | 智能體會根據答案繼續通話；在等候模式中，另一方同時會聽到等候音樂 |
| 閱讀結果 | 接收 [`telephony.complete`](/yue/webhooks/events) | 你的機械人會發佈摘要及結果 |

你的機械人只需保留一個對應關係：哪個聊天討論串屬於哪個 `call_id`。

## 開始之前

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

<Tip>
  請使用你為自己工作區建立的 Slack 應用程式，並透過 Slack 的 Events API
  接收訊息，而非讀取頻道記錄。Slack 對於在 Marketplace 以外發佈至其他
  工作區的應用程式設有嚴格讀取限制；你為自己工作區建立的應用程式不受
  此限制，而且事件會在發生時即時傳送給你，無需進行任何讀取。常見的
  機械人權限範圍包括：`chat:write`、`app_mentions:read`、`im:history`（直接
  訊息）、`channels:history` 及 `groups:history`（機械人所在公開及私人頻道中的
  討論串回覆）。訂閱機械人事件
  `app_mention`、`message.im`、`message.channels` 及 `message.groups`，並
  在 App Home 下啟用 Messages 分頁，讓使用者可以向機械人傳送直接訊息。
</Tip>

## 1. 從訊息開始通話

當你的機械人收到訊息（直接訊息或 @mention）時，
立即確認 Slack 的請求（Slack 會重試任何未在 3 秒內
確認的請求），並在背景處理其餘工作。確認寄件者是否獲授權撥打電話，
然後以該訊息作為 `context` 開始通話：

```bash
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 簽署](/yue/guides/verify-webhook-signatures)。
- **按封包的 `event_id` 去重，並按 `position` 排序。**
  系統至少會傳送一次，而回合亦可能亂序到達。
- **將多行內容分批發布**，如繁忙的通話會令討論串出現大量訊息；
  每隔數秒發布一次，會比每行一則訊息更易閱讀。

當收到 `telephony.complete` 時，發布通話結束方式（其 `status`
及 `end_reason`）、`summary` 和任何擷取的資料，然後結束
討論串。欄位詳情請參閱[通話完成](/yue/webhooks/call-complete)。

## 3. 從討論串引導通話

當有人在進行中的通話討論串中回覆時，將回覆以耳語方式傳送，
除非智能體正等待問題的答案（步驟 4），在此情況下該回覆
就是答案：

```bash
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 連線](/yue/guides/build-tool-integration)，並連結至智能體。
每個工具請求均會在其 `X-ThunderPhone-Call-ID` 標頭附帶通話 ID。

有三種方式可取得回覆。

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

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

對方會先聽到智能體說一句話，然後播放等候音樂。在電話選單或語音信箱中，智能體會改用語音更新；全雙工智能體則不會保留通話：它會將待處理回覆視為結果。當討論串收到回覆後，透過
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result)
傳送：

```bash
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` 前無人回覆，智能體會得知尚未收到答案，並向對方提供下一步選項。當通話仍有待處理問題時，討論串中的下一則回覆便是答案：將其作為工具結果傳送，不要同時作為耳語傳送（耳語只會在工具完成後才傳達給智能體）。參閱
[長時間等候](/yue/tools/overview)。

**在請求中等待（最長 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 分鐘的回覆。通話不會被保留：你的提示應告知智能體期間應如何處理，例如陪伴對方交談或提出稍後回電。

無論使用哪種方式，都應在智能體的提示中說明何時使用工具，以及等候期間應向對方說甚麼：

```text
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`](/api-reference/organizations#legacy-single-url-webhook) 中設定的 webhook 密鑰。
- 決定哪些人可發起通話：在撥號前檢查 Slack 使用者 ID。
- 外撥通話須遵守與其他通話相同的規則。請參閱[外撥通話法規](/yue/guides/outbound-calling-laws)。

## 使用編碼智能體建立

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