---
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/guides/pricing)。

对于[步骤](/zh/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`](/zh/guides/dynamic-call-config)；当您需要替换提示词或其他设置时，请返回内联配置。已保存智能体 webhook
响应会在电话和小组件通话中使用该智能体已部署的 A/B 分流；
变量会在变体选择后渲染。当响应为非全双工智能体设置 `language` 时，如果该智能体已为该语言设置语音，通话也会使用该语言自己的语音。包含 `prompt` 的响应始终使用内联配置：该响应中的任何 `agent_id` 都会被忽略，包括 null 或非整数元数据。内联提示词仍必须通过常规验证。
内联 webhook 响应也可以包含 `variables` 和 `context`。非字符串或过长的 `context`
会导致交换失败：电话通话会被拒绝，小组件会话请求会以 `400` 失败。已保存智能体 webhook
响应会在电话和小组件通话中使用该智能体已部署的 A/B 分流；
变量会在变体选择后渲染。对于呼入电话，请使用未分配呼入智能体的号码，并配置其电话号码或组织 webhook；小组件密钥使用
`mode="webhook"`。端点系统的传入通知不提供阻塞式配置响应。

### 智能体通话设置 Webhook

要让号码保持分配给其智能体，并且仅填充本次通话的值，请为该智能体配置[通话设置 Webhook](/zh/webhooks/call-incoming)。
在智能体接听号码上的每次呼入通话之前，Webhook 会获取通话以及智能体的 ID、名称和版本，并使用与上述相同的 `variables`、`context`、`language` 和每次通话的 `timezone` 进行响应，无需提供 `agent_id`。如果智能体的设置使用了没有默认值的占位符，则需要此 Webhook 才能接听电话：Webhook 失败时，通话不会开始。带有默认值的占位符（如 `{{name|there}}`）允许智能体在没有此 Webhook 的情况下接听。

### SIP 标头

通过 SIP（[SIP 地址](/zh/guides/sip-addresses)或手动 SIP 连接上的号码）接入智能体的通话可以在 `X-*` 和 `User-to-User` 标头中携带上下文。每个标头都会成为一个 `sip_` 变量，例如 `{{sip_x_amzn_connectcontactid}}` 或 `{{sip_uui}}`，其优先级最低：来自 API 或 webhook 的同名值会优先生效。请参阅[通过 SIP 标头传递通话上下文](/zh/guides/sip-addresses)。

标头值由发送方设置，因此应将其视为不受信任的数据，就像任何由浏览器提供的值一样。

### Widget 会话 API

`POST /v1/widget/session` 接受顶层 `variables` 和 `language`。其可发布
密钥会选择已保存的智能体。Webhook 模式的密钥会将这些值转发到
配置 Webhook，并按上述说明合并响应。
浏览器提供的小组件 `variables` 由客户端控制，在完成上述验证和字符串清理后，
会原样转发至 `web.incoming`，并回显到完成 Webhook 和通话记录中。请勿将其
视为可信的身份或授权数据。

Widget 自身的浏览器 `context` 字段有所不同：它承载访问者当前所在页面中的文本，智能体会将其视为网站内容（请参阅[嵌入网页 Widget](/zh/guides/embed-web-widget)）。Widget 通话的单次通话上下文如上所述，来自 Webhook 模式密钥的配置 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` 会在套接字连接后立即启动智能体，无需等待任何
`session.update`，因此不会携带单次通话输入。添加
`&wait_for_session_update=1`，以等待首次 `session.update` 并使用其中的
指令和变量。

在内联会话中（没有已保存的智能体），`session.instructions` 与之前一样，就是提示词本身。浏览器测试通话和模拟会解析默认值及缺失的占位符。要使用具体值进行测试，请在智能体上保存一个[通话设置示例](/zh/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 提示词。浏览器测试通话和模拟也会采用相同的默认值/空白行为，除非您选择已保存的通话设置示例。
