---
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`、空字串或只有空白字元，表示沒有 context。
- 不是字串的值，或長度超過 20,000 個字元的值，會在通話及工作階段請求中以 `400` 拒絕；如來自設定 webhook，則會如無效的 `variables` 一樣令交換失敗（見下文）。
- 系統會移除開頭及結尾的空白字元，並移除與變數值相同的控制字元及格式字元。
- Context 是通話提示的一部分，因此會計入通話的[提示大小](/yue/guides/pricing)。

在 [步驟](/yue/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 路徑中，傳回你組織內已儲存的智能體，以及任何每通通話的值。對於全雙工智能體，即使通話以另一種支援語言開始，通話仍會保留該智能體的語音：每種語言的語音對應和原生語音切換均不適用於該通話。

```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`](/yue/guides/dynamic-call-config)；如需取代提示詞或其他設定，請傳回內嵌設定。已儲存智能體的 webhook
回應會在電話及小工具通話中使用智能體已部署的 A/B 分流；
變數會在選擇變體後代入。當回應為非 Full duplex 智能體設定 `language` 時，如智能體已為該語言設定語音，通話亦會使用該語言本身的語音。包含 `prompt` 的回應一律使用內嵌
設定：該回應中的任何 `agent_id` 都會被忽略，包括 null 或非整數的中繼資料。內嵌提示詞仍必須通過一般驗證。
內嵌 webhook 回應亦可包含 `variables` 及 `context`。如 `context`
不是字串或過長，該次交互便會失敗：電話通話會被拒絕，而小工具工作階段請求會以 `400` 失敗。已儲存智能體的 webhook
回應會在電話及小工具通話中使用智能體已部署的 A/B 分流；
變數會在選擇變體後代入。對於入站電話通話，請使用未指派入站
智能體的號碼，並設定其電話號碼或組織 webhook；小工具金鑰使用
`mode="webhook"`。端點系統的入站通知不會提供阻塞式設定回應。

### 智能體通話設定 Webhook

如要將號碼保留指派予其智能體，並只填入該通話的值，
請為智能體設定 [通話設定 webhook](/yue/webhooks/call-incoming)。
在智能體接聽號碼上的每個來電之前，webhook 會取得通話，以及智能體的 ID、名稱和版本，並以與上述相同的
`variables`、`context`、`language` 及每通通話的 `timezone` 回應，無需提供 `agent_id`。如果智能體的
設定使用了沒有預設值的佔位符，便需要此 webhook 才能接聽電話：webhook 失敗時，通話不會開始。具有預設值的佔位符，例如 `{{name|there}}`，則可讓智能體無需此 webhook 亦可接聽。

### SIP 標頭

透過 SIP（[SIP 位址](/yue/guides/sip-addresses)，或手動 SIP 連線上的號碼）接通至智能體的通話，可在 `X-*` 及
`User-to-User` 標頭中攜帶內容。每個標頭均會成為一個 `sip_` 變數，例如
`{{sip_x_amzn_connectcontactid}}` 或 `{{sip_uui}}`，其優先順序最低：來自 API 或
webhook 的同名值會優先採用。請參閱
[在 SIP 標頭中傳遞通話內容](/yue/guides/sip-addresses)。
標頭值由傳送者設定，因此應視為不受信任，與任何由瀏覽器提供的值相同。

### Widget 工作階段 API

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

Widget 自身的瀏覽器 `context` 欄位則不同：它會帶入訪客所在頁面的文字，
智能體會將其視為網站內容（見
[嵌入網頁 Widget](/yue/guides/embed-web-widget)）。Widget 通話的每次通話
內容如上所述，來自 Webhook 模式金鑰的設定回調。當通話同時擁有兩者時，
會先使用每次通話內容，然後才使用頁面內容。

### 即時工作階段 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`，並使用其中的
指示和變數。

在內嵌工作階段（沒有已儲存智能體）中，`session.instructions` 會如以往一樣作為提示詞本身。Builder 咪高峰和模擬測試通話會解析預設值及缺失的預留位置，但不支援每次通話的變數或內容輸入。

## 通話結束後

`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 傳回的提示詞。即使未有提供 `variables`，未知的 `{{name}}` 佔位符亦會顯示為空白文字。推出前請檢查現有提示詞，包括 ThunderPhone 無法清點、由外部提供的內嵌／webhook 提示詞。Builder 咪高峰及模擬通話同樣採用預設值／空白的行為。
