ThunderPhone v3 已正式上线。全程自助,低至2美分/分钟。查看发布公告

Developer cookbook

每通电话的变量和上下文

为每通电话提供专属详细信息,可将其作为提示词的命名变量或自由格式简介,而无需更改智能体。

每通电话都可以携带两种按通话传入的输入。您可以单独使用其中一种,也可以同时使用两种:

  • 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 提示词。浏览器测试通话和模拟也会采用相同的默认值/空白行为,除非您选择已保存的通话设置示例。