Open in
每通电话的变量和上下文
为每通电话提供专属详细信息,可将其作为提示词的命名变量或自由格式简介,而无需更改智能体。
每通电话都可以携带两种按通话传入的输入。您可以单独使用其中一种,也可以同时使用两种:
variables:用于填充提示词中{{placeholders}}的命名值。将其用于提示词按名称引用的字段,例如来电者姓名、账号或预约时段。context:添加在提示词后的自由格式文本。将其用于不适合模板的简要说明,例如本次通话的任务描述或之前收集的备注。
两者均可与已保存的智能体和内联配置配合使用,适用于下文所述的每种发起通话方式。两者都不会更改已保存的智能体、其版本历史记录或其他设置。
{
"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 拒绝)。
占位符和默认值
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 会在提示词之后、提示词变量填充完成后,将其作为带分隔符的区块添加:
<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一样导致交换失败(见下文)。 - 会移除首尾空白字符,以及与变量值中相同的控制字符和格式字符。
- 上下文是通话提示的一部分,因此会计入通话的提示大小。
对于步骤智能体,上下文会跟在通话中每个智能体的提示词之后,而不是跟在每个步骤的指令之后。
值的来源
出站 API
在 POST /v1/call 中发送 variables 和 context:
{
"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 路径上,返回您组织中已保存的智能体以及任意按通话设置的值。对于全双工智能体,即使通话以另一种受支持的语言开始,通话仍会保留该智能体的语音:该通话不适用按语言设置的语音映射和原生语音切换。
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"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;当您需要替换提示词或其他设置时,请返回内联配置。已保存智能体 webhook
响应会在电话和小组件通话中使用该智能体已部署的 A/B 分流;
变量会在变体选择后渲染。当响应为非全双工智能体设置 language 时,如果该智能体已为该语言设置语音,通话也会使用该语言自己的语音。包含 prompt 的响应始终使用内联配置:该响应中的任何 agent_id 都会被忽略,包括 null 或非整数元数据。内联提示词仍必须通过常规验证。
内联 webhook 响应也可以包含 variables 和 context。非字符串或过长的 context
会导致交换失败:电话通话会被拒绝,小组件会话请求会以 400 失败。已保存智能体 webhook
响应会在电话和小组件通话中使用该智能体已部署的 A/B 分流;
变量会在变体选择后渲染。对于呼入电话,请使用未分配呼入智能体的号码,并配置其电话号码或组织 webhook;小组件密钥使用
mode="webhook"。端点系统的传入通知不提供阻塞式配置响应。
智能体通话设置 Webhook
要让号码保持分配给其智能体,并且仅填充本次通话的值,请为该智能体配置通话设置 Webhook。
在智能体接听号码上的每次呼入通话之前,Webhook 会获取通话以及智能体的 ID、名称和版本,并使用与上述相同的 variables、context、language 和每次通话的 timezone 进行响应,无需提供 agent_id。如果智能体的设置使用了没有默认值的占位符,则需要此 Webhook 才能接听电话:Webhook 失败时,通话不会开始。带有默认值的占位符(如 {{name|there}})允许智能体在没有此 Webhook 的情况下接听。
SIP 标头
通过 SIP(SIP 地址或手动 SIP 连接上的号码)接入智能体的通话可以在 X-* 和 User-to-User 标头中携带上下文。每个标头都会成为一个 sip_ 变量,例如 {{sip_x_amzn_connectcontactid}} 或 {{sip_uui}},其优先级最低:来自 API 或 webhook 的同名值会优先生效。请参阅通过 SIP 标头传递通话上下文。
标头值由发送方设置,因此应将其视为不受信任的数据,就像任何由浏览器提供的值一样。
Widget 会话 API
POST /v1/widget/session 接受顶层 variables 和 language。其可发布
密钥会选择已保存的智能体。Webhook 模式的密钥会将这些值转发到
配置 Webhook,并按上述说明合并响应。
浏览器提供的小组件 variables 由客户端控制,在完成上述验证和字符串清理后,
会原样转发至 web.incoming,并回显到完成 Webhook 和通话记录中。请勿将其
视为可信的身份或授权数据。
Widget 自身的浏览器 context 字段有所不同:它承载访问者当前所在页面中的文本,智能体会将其视为网站内容(请参阅嵌入网页 Widget)。Widget 通话的单次通话上下文如上所述,来自 Webhook 模式密钥的配置 webhook。当一次通话同时具有两者时,单次通话上下文在前,随后是页面内容。
实时会话 API
POST /v1/realtime/sessions 接受顶层的 variables、context 和 language,可与 agent_id 或内联 config 一同使用:
{
"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 选择智能体;该更新到达后会启动会话:
{
"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 与之前一样,就是提示词本身。浏览器测试通话和模拟会解析默认值及缺失的占位符。要使用具体值进行测试,请在智能体上保存一个通话设置示例,并在启动测试时选择它;通话会像您的通话设置 Webhook 已使用该示例响应一样运行。
通话结束后
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"]
}通话的 prompt_snapshot(GET /v1/calls/{call_id})会显示已填入变量并添加了上下文块的智能体提示词。
请将您的 CRM 或任务标识符存储在变量对象中,以便将已完成的通话关联回其源记录。变量和上下文会随通话记录一并保留;请仅发送适合保留在通话记录和 Webhook 中的信息。
在验证集、回放运行和调查中对通话进行回放时,会将该通话的变量和上下文与正在测试的提示词一起使用,因此回放会测试该通话中的智能体原本会获得的信息。
与现有提示词的兼容性
渲染同样适用于现有已保存智能体和 A/B 变体提示词、内联外呼和实时配置,以及由配置 Webhook 返回的提示词。未知的 {{name}} 占位符会变为空白文本,即使未提供 variables 也是如此。发布前请检查现有提示词,包括 ThunderPhone 无法清点的外部提供的内联/Webhook 提示词。浏览器测试通话和模拟也会采用相同的默认值/空白行为,除非您选择已保存的通话设置示例。