---
title: "轉駁通話"
description: "透過冷轉接為來電者轉駁，或先篩選目標接聽方，再進行暖轉接。"
---

每個電話智能體均內置 `transfer_call` 動作。在智能體的提示詞中說明何時轉接、使用哪個號碼，以及應採用冷接還是暖接。

| 模式 | 運作方式 | 適用情況 |
| --- | --- | --- |
| **冷接** | 來電者會直接轉接至目的地。智能體不會介紹來電者，亦不會確認是否有人接聽。 | 快速路由比預先確認轉接更重要，或通話使用 ThunderPhone 提供的號碼。 |
| **暖接** | 智能體私下致電並確認目的地是否可接聽時，來電者會處於等候狀態。只有目標接聽方接受後，雙方才會接通。 | 目標接聽方需要在接受前了解背景，或無人可接聽時來電者應返回智能體。 |

如果智能體未指定模式，轉接會採用冷接。

## 設定轉接

在控制台中：

1. 開啟 **語音智能體**，選取智能體，然後開啟 **設定**。
2. 在提示詞中加入每個目的地、其路由條件，以及應使用 `cold` 還是 `warm` 模式。無需啟用獨立的轉接切換選項，亦無需建立自訂工具。
3. 如有需要，將 **進階 → 響鈴時間** 設為 5 至 120 秒。
4. 選取 **部署**。

使用 API 時，以 `PATCH /v1/agents/{agent_id}` 暫存提示詞及可選的
`ring_duration_seconds`，然後使用 `POST /v1/agents/{agent_id}/deploy`。請參閱
[智能體 API](/api-reference/agents#update-an-agent-writes-the-draft)。

## 暖接期間的運作方式

1. 智能體會通知來電者正在開始轉接。
2. 來電者會聽到等候音樂。來電者無法聽到目標接聽方的響鈴聲或私下對話。
3. ThunderPhone 會透過處理該通電話的 VoIP 號碼致電目標接聽方。智能體會傳達其 `screen_message`，當中應識別智能體、說明來電者姓名、解釋來電原因，並詢問目標接聽方是否可以接聽。
4. 目標接聽方可在決定前提問。來電者維持等候期間，智能體會根據原有對話及其提示詞作答。
5. 如目標接聽方接受，來電者會結束等候，雙方均會聽到簡短的 `introduction`。智能體其後會自動離線，兩人將維持通話連線。

如目標接聽方拒絕、未有接聽或轉駁至語音信箱，ThunderPhone
會結束該私下通話，並讓來電者結束等候。智能體會收到結果並繼續原有對話。它可以記錄留言、建議其他路由方式，或在來電者仍希望轉接時進行冷接。暖接不會留下語音留言。如目標接聽方要求智能體轉達訊息，工具結果會將該訊息列為 `relay_message_for_caller`。

<Note>
  如已啟用智能體的同意通知，轉接目標接聽方會在私下篩選對話開始前聽到該通知。
  等候中的來電者不會再次聽到。
</Note>

## 在提示中讓智能體妥善轉駁來電

將路由規則加入智能體提示。使用 E.164 格式：`+`、國家／地區代碼，
以及完整本地號碼，例如 `+14155550123`。為每個路由指定轉駁模式，並為暖轉接失敗時提供備用方案。

```text
Transfer policy

Confirm the caller's name and reason for calling before any transfer.

| Caller needs | Destination | Transfer mode |
| --- | --- | --- |
| A new purchase or plan change | +14155550123 | warm |
| Help with an existing order | +14155550124 | warm |
| The main office | +14155550125 | cold |

For a warm transfer:
- In the private screen message, identify yourself, give the caller's name and
  a one-sentence reason for the call, then ask whether the target can take it.
- Answer reasonable questions from the target using the conversation context.
- If the target accepts, introduce both people in one short sentence. Do not
  plan to speak after the introduction because you will be dropped.
- If the target declines, does not answer, or reaches voicemail, tell the
  caller what happened. Relay any message from the target, then offer to take
  a message or try another route. Do not cold-transfer unless the caller asks.
```

語音智能體在呼叫內建動作時會提供以下欄位：

| 欄位 | 使用時機 | 用途 |
| --- | --- | --- |
| `phone_number` | 一律 | 採用 E.164 格式的轉駁目的地。 |
| `mode` | 可選 | `cold` 或 `warm`；預設為 `cold`。 |
| `screen_message` | 暖轉接必填 | 接聽方私下聽到的開場訊息。 |
| `introduction` | 暖轉接必填 | 接聽方接受後，雙方都會聽到的一句簡短介紹。 |

無須定義或附加名為 `transfer_call` 的自訂工具。

## 私語轉駁

「私語轉駁」是業界對暖轉接的常用名稱：接聽方會在來電者接通前，
先聽到私下的背景資訊。在 ThunderPhone 中，暖轉接的 `screen_message`
會提供這段私下簡介。接聽方其後可在接受或拒絕前，向語音智能體提出後續問題。

這與
[`POST /v1/calls/{id}/whisper`](/yue/guides/monitor-live-calls)
不同。該端點讓員工或擁有人在進行中的通話期間，向 AI
語音智能體發送私密文字指示，並不會致電或向轉駁目的地提供簡介。

## 要求、限制及測試

| 問題 | 答案 |
| --- | --- |
| 哪些號碼支援暖轉接？ | 已透過可撥出電話的 VoIP 連線匯入並完成驗證的號碼。ThunderPhone 提供的號碼僅支援冷轉接。如暖轉接模式不可用，操作會改為冷轉接。[連接 VoIP 供應商](/yue/guides/voip-providers)。 |
| 哪些通話類型支援此功能？ | 一般電話通話可使用冷轉接。Browser Talk、Widget、模擬及測試通話均無法測試暖轉接。已儲存智能體的 Realtime 不包括 `transfer_call`；使用 `call_events` 的內嵌 Realtime 可要求冷轉接。 |
| 如何測試？ | 可先在 Browser Talk 或模擬中檢查路由語句，然後使用符合資格的已匯入 VoIP 號碼，在實際電話通話中測試完整轉接流程。 |
| 目標號碼會響鈴多久？ | `ring_duration_seconds` 可接受 5 至 120 秒。`null` 在暖轉接時使用 45 秒，冷轉接時則使用電訊商的預設值。一般撥出電話預設為 60 秒。此設定不會更改來電響鈴時間。 |
| 人員橋接可維持多久？ | 智能體連接雙方後，最長可維持 60 分鐘。 |
| 失敗時會如何？ | 如目標方拒絕、未有接聽、轉至語音信箱，或撥出線路失敗，來電者會連同結果返回智能體。提示詞應定義下一步。 |
| 費用是多少？ | 不收取轉接工具費用。一般通話費用涵蓋暖轉接流程直至介紹結束；AI 離開後，ThunderPhone 即停止計費。當雙方仍保持連線時，你的電訊商可能會繼續就撥出轉接線路收費。 |

## Webhook 及結束原因

完成資料載荷會在 `transfer_number` 記錄目標號碼，並使用以下其中一個
結束原因：

| `end_reason` | 含義 |
| --- | --- |
| `ai_transfer` | 智能體已啟動冷轉接。 |
| `ai_warm_transfer` | 目標方接受暖轉接，雙方已連接，而智能體在介紹後離開。 |

被拒絕、未接聽、失敗或轉至語音信箱的暖轉接嘗試，不屬於已完成的
轉接。來電者會返回智能體，因此最終結束原因會反映原來通話的結束方式。

如暖轉接成功，完成事件及 AI 通話的結束原因會在介紹完成、AI 離開時
記錄。如已啟用錄音，音訊會持續錄製人員橋接直至結束；轉接後的語音會被
錄音，但不會轉錄。啟用智能體的同意公告後，轉接目標會在篩選開始前聽到公告。

<Accordion title="舊版完成 Webhook">
  舊版單一 URL Webhook 可透過傳回 `{"transfer_ready": false}`，並在其後更新通話的
  轉接就緒狀態，將冷轉接延遲最多五分鐘。Webhook 端點傳送及暖轉接不會
  使用此協調機制。
</Accordion>

請參閱[完成 Webhook](/yue/webhooks/call-complete)，了解完整資料載荷及
舊版行為。

## 疑難排解

### 智能體執行直接轉接而非預先接通轉接

確認通話使用已驗證、已匯入且具備有效外撥路由的 VoIP 號碼。ThunderPhone
號碼及非電話工作階段的工具選項中不設預先接通模式。同時在提示詞的
路由表中明確指定模式。

### 目標對象一直未接聽

確認你的 VoIP 中繼線路可以向目的地撥打外線電話，並確保其驗證及路由規則
均為最新。檢查目的地的 E.164 格式。如 45 秒對預先接通轉接而言太短，請增加
`ring_duration_seconds`。

### 目標對象轉駁至留言信箱

預先接通轉接不會留下語音留言。來電者會解除保留狀態，而智能體會收到
`voicemail` 結果。在智能體的提示詞中說明應記錄留言、嘗試其他目的地，
還是提供直接轉接。

### 來電者未收到目標對象的訊息

指示智能體在提供後續選項前先轉達 `relay_message_for_caller`。該欄位僅會在
目標對象拒絕接聽並要求智能體轉達內容時出現。

### 直接轉接在接通前等待

如你使用舊版單一 URL webhook，請檢查它是否回傳
`{"transfer_ready": false}`。ThunderPhone 等候期間，來電者會聽到等候音樂。
目的地準備就緒後，更新通話的可轉接狀態。

### 員工耳語不會啟動轉接

即時通話耳語功能只會向 AI 提供指導。請在智能體提示詞中加入轉接指示，
並讓它呼叫 `transfer_call`。請參閱
[監察即時通話](/yue/guides/monitor-live-calls)。