---
title: "從 Slack 或聊天應用程式執行通話"
description: "使用公開 API 建置你自己的 Slack、Teams 或網頁聊天機器人，用來發起通話、即時追蹤通話、引導智慧體並回答其問題。"
---

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

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

## 整體運作方式

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

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

## 開始前

- **API 金鑰**，請儲存在你的伺服器上，切勿放在瀏覽器或聊天中。
  請在 **整合 → API 金鑰** 下建立金鑰（請參閱
  [建立伺服器 API 金鑰](/zh-Hant/guides/api-keys)）。
- **已啟用撥出功能的號碼與智慧體**，用於撥打通話。訊息會成為每通通話的
  `context`，因此一個通用智慧體即可處理所有工作。
- **可接收 Webhook 的伺服器**，例如 Railway、Fly.io、Render 或
  你自己的主機。
- **Webhook 端點**，指向該伺服器，並訂閱
  `telephony.turn` 與 `telephony.complete`。只有列出這些事件的端點才會收到回合事件。請參閱 [Webhook](/zh-Hant/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. 從訊息發起通話

當你的機器人收到訊息（私訊或 @提及）時，請立即確認 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 簽章](/zh-Hant/guides/verify-webhook-signatures)。
- **依封包的 `event_id` 去除重複項目，並依 `position` 排序。**Webhook 至少會傳送一次，且回合可能會以非預期順序送達。
- 如果忙碌的通話可能淹沒討論串，請**批次張貼內容**；每隔幾秒張貼一次，比每行一則訊息更易讀。

當 `telephony.complete` 送達時，張貼通話如何結束（其 `status` 和 `end_reason`）、`summary` 及任何擷取的資料，然後結束討論串。欄位資訊請參閱[通話完成](/zh-Hant/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 連線](/zh-Hant/guides/build-tool-integration)，並連結至智慧體。
每個工具請求都會在其 `X-ThunderPhone-Call-ID` 標頭中帶有通話資訊。

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

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

```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` 前沒有人回覆，智慧體會得知尚未收到答案，並向對方提供後續選項。當通話有待處理問題時，其討論串中的下一則回覆就是答案：將其作為工具結果傳送，不要同時將其作為耳語傳送（耳語只有在工具傳回後才會送達智慧體）。請參閱
[長時間等待](/zh-Hant/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 在 Slack 請求上的簽署密鑰。兩種 ThunderPhone 簽章使用不同的密鑰：Webhook 傳送作業使用 Webhook 端點本身的密鑰，而工具請求使用你組織在 [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) 中的 Webhook 密鑰。
- 決定哪些人可以發起通話：撥打前先檢查 Slack 使用者 ID。
- 撥出通話遵循與其他通話相同的規則。請參閱[撥出通話法規](/zh-Hant/guides/outbound-calling-laws)。

## 使用程式開發智慧體建置

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