每通电话变量

为每通电话个性化已保存的智能体，而无需更改其已部署的提示词、工具或设置。

在您已保存的智能体提示词中加入占位符，然后在发起通话时提供 variables 对象。已保存的配置和版本历史保持不变。ThunderPhone 会在将通话配置发送到语音运行时之前渲染文本。

当不需要任何值时，请省略 variables，不要发送 null（会以 400 拒绝）。

占位符和默认值

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）字符、所有格式（Cf）字符以及代理项（Cs）代码点都会被移除；\r\n 会规范化为 \n。每个值在渲染时最多限制为 2,000 个字符。提供的字符串也会在存储前清理并截断。原始对象必须符合 32 KB UTF-8 JSON 限制；较大的对象在通话/会话请求中会收到 400，而营销活动导入会分别报告无效行。数组和嵌套对象不能作为值接受。不匹配的元数据键（例如包含空格的 CSV 标头）会被保留并回显，但无法通过占位符引用。

值的来源

出站 API

在 POST /v1/call 中将 variables 与 agent_id 一并发送：

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

这同样适用于电话号码的默认出站智能体，或内联 config.prompt。幂等键不能与不同的变量重复使用。

营销活动 CSV

非电话号码的 CSV 列已作为联系人变量存储。现在每次拨号都会自动使用这些变量。使用 name、account_id 和 appointment_slot 等表头来匹配您的占位符。现有的姓名映射可以将名字和姓氏列组合为变量 name。

动态配置 webhook

在阻塞式配置 webhook 路径中，返回您组织中的已保存智能体以及任意每通话值：

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

响应中的键会覆盖请求级变量，其他请求键则会保留。响应值为 null 时会选择占位符的默认值。合并后的对象也必须小于 32 KB。已保存智能体响应仅接受 agent_id 和 variables；当您需要替换提示词或设置时，请返回内联配置。包含 prompt 的响应始终使用内联配置：该响应中的任何 agent_id 都会被忽略，包括 null 或非整数元数据。内联提示词仍必须通过常规验证。内联 webhook 响应也可以包含 variables。已保存智能体 webhook 响应会在电话和小组件通话中使用智能体已部署的 A/B 分流；变量会在选择变体后渲染。对于入站电话，请使用未分配入站智能体的号码，并配置其电话号码或组织 webhook；小组件密钥使用 mode="webhook"。端点系统的入站通知不提供阻塞式配置响应。

小组件和 Realtime 会话 API

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

POST /v1/realtime/sessions 接受与 agent_id（或内联 config）一并提供的 variables。这些是会话创建 API 字段。Realtime WebSocket 桥接不会转发 variables 选项；请直接将其提供给会话创建 API。小组件客户端必须在提交的会话负载中包含 variables； SDK 转发不属于此次 API 变更的一部分。构建器麦克风和模拟测试通话会解析默认值和缺失的占位符，但不提供每通话变量输入。

通话后返回的值

GET /v1/calls、GET /v1/calls/{call_id}、telephony.complete 和 web.complete 包含最终合并的 variables 和 unresolved_variables。包含 data.history 的旧版完成负载也会包含这些字段：

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

将您的 CRM 或任务标识符存储在 variables 对象中，以便将已完成的通话关联回其来源记录。这些字段会随通话记录保留；请仅发送适合保留在通话记录和 webhook 中的信息。

与现有提示词的兼容性

渲染同样适用于现有已保存智能体和 A/B 变体提示词、内联外呼和实时配置，以及由配置 webhook 返回的提示词。未知的 {{name}} 占位符会变为空白文本，即使未提供 variables 也是如此。请在发布前检查现有提示词，包括 ThunderPhone 无法盘点的外部提供的内联/webhook 提示词。构建器麦克风和模拟通话同样采用默认值/空白行为。