---
title: "每通電話的變數與情境"
description: "為每通電話提供專屬詳細資訊，可作為提示詞的具名變數或自由格式簡述，無須變更智慧體。"
---

每通電話都可帶入兩種類型的單次通話輸入。你可以擇一使用，也可以同時使用：

- **`variables`**：填入提示詞中 `{{placeholders}}` 的具名值。適用於提示詞以名稱參照的欄位，例如來電者姓名、帳號或預約時段。
- **`context`**：新增在提示詞之後的自由格式文字。適用於不適合使用範本的簡述，例如本次通話的任務說明或先前蒐集的備註。

兩者皆可搭配已儲存的智慧體與內嵌設定，並適用於以下所述的所有發起通話方式。兩者都不會變更已儲存的智慧體、其版本紀錄或其他設定。

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## 變數

在已儲存的智慧體提示詞中加入預留位置，然後在開始通話時提供 `variables`
物件。ThunderPhone 會在將通話設定傳送至語音執行環境前，先轉譯文字。

不需要任何值時，請省略 `variables`，不要傳送 `null`（會以 `400` 拒絕）。

### 預留位置與預設值

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

名稱會區分大小寫，並遵循 `[A-Za-z_][A-Za-z0-9_]*`。名稱周圍允許空白；
`|` 後方的空白是預設值的一部分，且會保留。當 `name` 缺少或為
`null` 時，`{{name|Friend}}` 會使用 `Friend`；空字串則是明確提供的值。
沒有預設值的缺少值會變成空字串，且其名稱會顯示於 `unresolved_variables`。
雙大括號之間不是有效預留位置的文字會被移除。每個提供值中的雙大括號文字會
個別移除；某個值無法移除周圍的提示詞文字或另一個值。不成對的雙大括號分隔符
也會被移除。提示詞中的 JSON 範例不得使用 `{{`。
值一律是純文字，不會作為程式碼執行，也不會以範本遞迴展開。

變數也可以出現在確認提示詞、外撥語音信箱訊息，以及該欄位隨電話通話傳送時的
同意公告文字中。智慧體沒有獨立的 `first_message` 欄位：請將開場指示放入提示詞。
現有語音信箱的 `{agent_name}` 與 `{org_name}` 預留位置會繼續運作。

### 值與限制

值可以是字串、數字、布林值或 `null`；布林值會呈現為 `true`
和 `false`。除了換行（`\n`）、定位字元（`\t`）和歸位字元（`\r`）之外的 Unicode 控制（`Cc`）字元、除了零寬不連字元和連字元（U+200C、U+200D，這些字元用於拼寫印度語系及阿拉伯字母語言中的詞語）之外的格式（`Cf`）字元，以及代理（`Cs`）碼位都會被移除；`\r\n`
會正規化為 `\n`。每個值在呈現時
最多可包含 2,000 個字元。提供的字串也會在儲存前清理並截斷。原始物件必須符合 **32 KB 的 UTF-8 JSON**；較大的物件在通話／工作階段請求中會收到 `400`，而行銷活動匯入會逐一回報無效資料列。不接受陣列和巢狀物件作為值。不符規則的中繼資料鍵（例如含有空格的 CSV 標頭）會保留並回傳，但無法由預留位置參照。

## 情境

`context` 是最多 **20,000 個字元**的字串。ThunderPhone 會在提示詞的變數填入後，將其作為分隔區塊加在提示詞之後：

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

智慧體會連同其指示一併讀取，因此請以你在通話前向同事說明的方式撰寫。情境不是範本：
其中的 `{{name}}` 會維持原樣。如果文字需要某個值，請在傳送前自行填入該值。

- `null`、空字串或僅含空白字元表示沒有情境資訊。
- 非字串值，或超過 20,000 個字元的值，會在通話和工作階段請求中以 `400` 拒絕；若來自設定 Webhook，則會像無效的 `variables` 一樣使交換失敗（見下文）。
- 會修剪開頭與結尾的空白字元，並移除與變數值相同的控制字元和格式字元。
- 情境資訊是通話提示的一部分，因此會計入通話的[提示大小](/zh-Hant/guides/pricing)。

在 [steps](/zh-Hant/guides/agent-steps) 智慧體中，情境會接在通話中每個智慧體的提示詞後，而不是接在各步驟的指示後。

## 值的來源

### 外撥 API

在 `POST /v1/call` 上傳送 `variables` 和 `context`：

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

兩者也可搭配電話號碼的預設撥出語音智慧體或內嵌的
`config.prompt` 使用。使用內嵌設定時，`context` 也可放在 `config`
內，這與設定 webhook 回傳的欄位相同；如果兩者都傳送，文字必須完全相同。冪等性金鑰不可重複用於不同的變數或不同的內容。

### 行銷活動 CSV

非電話 CSV 欄位已儲存為聯絡人變數。每次撥號現在都會自動使用這些變數。請使用 `name`、`account_id` 和 `appointment_slot` 等標題來對應你的預留位置。現有的姓名對應可將名字與姓氏欄位合併為 `name` 變數。行銷活動聯絡人沒有每位聯絡人的情境資訊。

### 動態設定 webhook

在封鎖式設定 webhook 路徑上，傳回你組織中已儲存的智慧體，以及任何每通電話的值。對於 Full duplex 智慧體，即使通話以另一種支援的語言開始，通話仍會保留該智慧體的語音：
該通話不會套用各語言的語音對應或原生語音切換。

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

回應中的變數會覆寫請求層級的變數，其他請求鍵則會保留。回應值為 `null` 時，會選用預留位置的預設值。合併後的物件也必須小於 32 KB。已儲存智慧體的回應僅接受
`agent_id`、`variables`、`context`、`language`，以及每通電話的
[`timezone`](/zh-Hant/guides/dynamic-call-config)；當你需要
取代提示詞或其他設定時，請回傳內嵌設定。已儲存智慧體的網路掛鉤
回應會在電話和小工具通話中使用智慧體已部署的 A/B 分流；
變數會在選擇變體後轉譯。當回應為非全雙工智慧體設定 `language` 時，
如果智慧體已為該語言設定語音，通話也會使用該語言專屬的語音。包含 `prompt`
的回應一律使用內嵌設定：該回應中的任何 `agent_id` 都會被忽略，包括 null 或
非整數的中繼資料。內嵌提示詞仍須通過一般驗證。
內嵌網路掛鉤回應也可以包含 `variables` 和 `context`。非字串或過長的 `context`
會導致交換失敗：電話通話會被拒絕，而小工具工作階段請求會以 `400` 失敗。已儲存智慧體的網路掛鉤
回應會在電話和小工具通話中使用智慧體已部署的 A/B 分流；
變數會在選擇變體後轉譯。對於撥入電話通話，請使用未指派撥入
智慧體的號碼，並設定其電話號碼或組織網路掛鉤；小工具金鑰使用
`mode="webhook"`。端點系統的傳入通知不會提供阻塞式
設定回應。

### 智慧體通話設定 Webhook

若要讓號碼持續指派給其智慧體，並只填入該通話的值，請為智慧體提供[通話設定 Webhook](/zh-Hant/webhooks/call-incoming)。
在智慧體透過某個號碼接聽每通來電之前，Webhook 會取得通話以及智慧體的 ID、名稱和版本，並以與上述相同的
`variables`、`context`、`language` 和每通電話的 `timezone` 回應，不需要 `agent_id`。設定中使用沒有預設值的預留位置的智慧體，需要此 Webhook 才能接聽電話：Webhook 失敗時，通話不會開始。具有預設值的預留位置，例如 `{{name|there}}`，則可讓智慧體在沒有此 Webhook 的情況下接聽電話。

### SIP 標頭

透過 SIP（[SIP 位址](/zh-Hant/guides/sip-addresses)，或手動 SIP 連線上的號碼）接通至智慧體的通話，可在 `X-*` 與 `User-to-User` 標頭中攜帶情境資訊。每個標頭都會成為 `sip_` 變數，例如 `{{sip_x_amzn_connectcontactid}}` 或 `{{sip_uui}}`，且其優先順序最低：來自 API 或 webhook 的同名值會優先採用。請參閱[透過 SIP 標頭傳遞通話情境](/zh-Hant/guides/sip-addresses)。

標頭值由傳送端設定，因此應將其視為不受信任的內容，如同任何由瀏覽器提供的值。

### Widget 工作階段 API

`POST /v1/widget/session` 接受頂層的 `variables` 與 `language`。其可發布金鑰會選取已儲存的智慧體。Webhook 模式金鑰會將這些值轉送至設定 Webhook，並如上所述合併回應。
由瀏覽器提供的 Widget `variables` 由用戶端控制，在完成上述驗證與字串清理後，會原樣轉送至 `web.incoming`，並回傳至完成 Webhook 與通話紀錄。請勿將其視為可信任的身分識別或授權資料。

Widget 自身的瀏覽器 `context` 欄位不同：它承載訪客所在頁面的文字，智慧體會將其視為網站內容（請參閱[嵌入網頁 Widget](/zh-Hant/guides/embed-web-widget)）。Widget 通話的單次通話情境如上所述，來自 Webhook 模式金鑰的設定 Webhook。當通話同時具有兩者時，會先使用單次通話情境，再使用頁面內容。

### Realtime 工作階段 API

`POST /v1/realtime/sessions` 可接受頂層的 `variables`、`context` 和 `language`，以及 `agent_id` 或內嵌 `config`：

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` 僅能放在頂層；內嵌 `config` 會將其視為未知欄位而拒絕。

### 即時 WebSocket

使用已儲存的智慧體時，該智慧體已部署的提示詞會維持為其提示詞。
`session.instructions` 會成為通話的上下文，`session.prompt.variables`
（或 `session.config.variables`）會成為其變數，而 `session.language`
會成為每通通話的語言。在第一個 `session.update` 中透過
`session.prompt.id` 選擇智慧體；該更新送達後，即會啟動工作階段：

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

連線 URL 中的 `?agent_id=12` 會在 Socket 連線後立即啟動智慧體，早於任何
`session.update`，因此不會帶有每通通話的輸入。加入
`&wait_for_session_update=1` 即可等待第一個 `session.update`，並使用其中的
instructions 與 variables。

在內嵌工作階段中（沒有已儲存的智慧體），`session.instructions` 與先前相同，就是提示詞本身。瀏覽器測試通話和模擬會解析預設值與缺少的預留位置。若要使用特定值進行測試，請在智慧體上儲存一個[通話設定範例](/zh-Hant/webhooks/call-incoming)，並在開始測試時選取它；通話會如同你的通話設定 Webhook 已使用該範例回應般執行。

## 通話結束後

`GET /v1/calls`、`GET /v1/calls/{call_id}`、`telephony.complete` 和 `web.complete` 包含最終
合併的 `variables` 和 `unresolved_variables`。包含 `data.history` 的舊版完成酬載
也會包含這些欄位：

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

通話的 `prompt_snapshot`（`GET /v1/calls/{call_id}`）會顯示已填入變數並新增內容區塊的智慧體提示詞。

將你的 CRM 或任務識別碼儲存在變數物件中，以便將已完成的通話連回其來源紀錄。變數和內容會隨通話紀錄保留；僅傳送適合保留在通話紀錄和 Webhook 中的資訊。

在[驗證集](/api-reference/validation-sets)、[重播執行](/api-reference/replay-runs)和[調查](/api-reference/investigations)中重播通話時，會使用該通話的變數和內容，以及受測提示詞，因此重播可測試該通話中的智慧體原本會獲得哪些資訊。

## 與既有提示詞的相容性

渲染也適用於現有已儲存的智慧體與 A/B 變體提示詞、內嵌的外撥與即時設定，以及由設定 Webhook 傳回的提示詞。未知的 `{{name}}` 預留位置會變成空白文字，即使未提供 `variables` 也一樣。上線前請檢查現有提示詞，包括 ThunderPhone 無法盤點的外部提供內嵌／Webhook 提示詞。
瀏覽器測試通話與模擬會套用相同的預設／空白行為，除非你選擇已儲存的通話設定範例。
