共享变量
快速阅读
共享变量是一通电话上可跨节点读写的变量集合。它用来把外呼名单字段、接口入参和平台默认字段，统一交给推送、智能体和后续流程引用。
- 配置入口在管理端推送配置的「共享变量」页。先打开「启用共享变量」，下面才是「常用变量」和「参数自动转换」。关闭总开关后，本企业不再使用共享变量。
- 登记名称只方便管理和配置；未登记的名称仍可写入和引用。
- 推送参数用
SVAR(变量名)引用；推送发出前，平台按当前通话展开成实际值。 - 参数自动转换开启后，指定呼叫类型下勾选的属性由平台转为共享变量；当前支持预测外呼和自动外呼。未开启或未指定的字段仍按原参数传递。
- 这和 Copilot 智能体里的常用变量不是同一处配置。也不是自定义变量页本身。
阅读地图
- 和另外几类变量怎么分：读「二」。
- 值从哪来、推送怎么引用：读「三」。
- 页面怎么配：读「四」。
- 一通外呼怎么验收：读「五」。
- 对不上时：读「六」。
一、文档说明
本文说明共享变量是什么、从哪写入、怎么在推送里引用，以及管理端怎么配置。平台标准字段见内置变量。项目约定、由外部或流程写入的业务字段见自定义变量。只在当前节点临时用的值见缓存变量。推送能力总览见推送产品。
二、产品总览
外呼名单 / 接口入参 / 参数自动转换 / 智能体开始时的默认写入
→ 写入本通共享变量集合
→ 推送参数用 SVAR(变量名) 展开
→ 下游系统、智能体或后续流程读取| 对象 | 是什么 | 不要当成 |
|---|---|---|
| 共享变量 | 一通电话上可跨节点共享的变量集合 | 只登记名称、没有值的目录 |
| 常用变量 | 企业在推送配置里登记的名称和描述 | 写入值本身；也不是 Copilot 常用变量 |
| 参数自动转换 | 按呼叫类型，把指定属性转为共享变量 | 改下游接口字段名 |
| 自定义变量 | 项目约定的业务字段名和写入方式 | 推送配置里的共享变量页 |
| 缓存变量 | 当前通话或会话里临时有效的值 | 推送配置登记目录 |
共享变量强调「这一通已经有值，后面还能用」。自定义变量强调「项目先约定名字和来源」。一个业务字段可以先按自定义变量约定命名，再进入本通共享变量集合，供推送用 SVAR(变量名) 引用。
三、对象关系与运行链路
1. 写入
| 来源 | 什么时候写入 | 说明 |
|---|---|---|
| 参数自动转换 | 对应呼叫类型的外呼发起时 | 开启转换后，按呼叫类型勾选的属性名由平台写入共享变量；当前支持预测外呼和自动外呼 |
| 外呼或 WebCall 入参 | 发起呼叫时 | 入参中的共享变量进入本通集合；接通后绑定提升到通话会话 |
| 智能体开始 | 智能体 Start | 平台写入一组默认共享变量，见下表 |
| 企业登记 | 配置阶段 | 只登记名称和描述，不产生通话值 |
智能体开始时，平台默认写入：
| 变量名 | 含义 | 说明 |
|---|---|---|
cdr_main_unique_id | 主通话标识 | 用于串联本通 |
cdr_customer_number | 客户号码 | 本通客户侧号码 |
cdr_task_id | 任务标识 | 有任务号时才写入 |
current_time | 当前时间 | 按企业时区；缺省按平台默认时区 |
current_date | 当前日期 | 同上 |
current_weekday | 当前星期 | 中文星期文案 |
系统默认传递的变量名称来自系统配置，在「常用变量」列表里只读展示，不能修改或删除。具体清单以当前环境系统配置为准。
2. 引用
在推送动作的参数映射里，把参数值配成 SVAR(变量名)。推送入队前，平台按当前通话的请求标识和主通话标识展开。
- 有值：发出实际内容。
- 无值：按空值规则发出，不把字面量
SVAR(...)原样留给下游。 - 未登记的变量名只要本通已写入，仍可引用。
推送只带该事件发生时已经存在、且推送配置选中的参数。共享变量有值，不等于自动进入主话单、从话单或导出列；要对账或长期查询，仍按沉淀配置处理。
3. 生效条件
| 层次 | 含义 |
|---|---|
| 启用共享变量 | 页上的总开关。关闭后，本企业呼叫不再使用共享变量，SVAR(...) 不会展开 |
| 页面已保存常用变量或参数自动转换 | 登记名称、转换开关和属性列表以最近一次保存为准 |
| 本通已写入对应变量 | 展开时读取的是当前通话集合，不是配置目录 |
推送动作已配置 SVAR(变量名) | 未引用的变量不会出现在推送参数里 |
四、页面配置
入口：管理端 → 推送配置 → 共享变量。
需要具备消息推送相关的查看权限才能打开；保存需要消息推送相关的管理权限。具体权限名以当前账号权限配置为准。
1. 启用共享变量
| 配置项 | 作用 | 注意事项 |
|---|---|---|
| 启用共享变量 | 本企业是否使用共享变量 | 开启后，呼叫通过共享变量读写。关闭后不再使用，推送里的 SVAR(...) 不会展开 |
这个开关和下面的「启用转换」不是同一个。转换开关只决定外呼字段要不要自动变成共享变量。
2. 常用变量
| 配置项 | 作用 | 注意事项 |
|---|---|---|
| 变量名称 | 企业常用共享变量名 | 字母、数字、下划线；可用 前缀.名称 形式。不能以 SVS_ 或 SYSTEM_ 开头。名称数量有上限 |
| 变量描述 | 说明用途 | 便于实施和管理查阅 |
| 系统默认变量 | 系统配置下发的只读项 | 不可改、不可删；保存时不会被企业登记覆盖 |
| 保存 | 全量替换本企业已登记的常用变量 | 保存前确认清单；系统默认项不受影响 |
未登记的名称仍可正常写入和引用。登记的作用是统一名称、便于配置和协作，不是写入门槛。
3. 参数自动转换
| 配置项 | 作用 | 注意事项 |
|---|---|---|
| 启用转换 | 是否按呼叫类型自动转换 | 关闭后，字段仍按原参数传递 |
| 呼叫类型 | 本条转换规则适用的呼叫类型 | 当前支持预测外呼和自动外呼 |
| 属性名 | 要转为共享变量的字段名 | 填外呼名单或接口入参里已有的属性名；同一呼叫类型下不要重复 |
| 添加呼叫类型 | 增加一条呼叫类型规则 | 同一呼叫类型只能配一条 |
| 保存 | 保存开关和映射 | 与「常用变量」分开保存 |
典型做法：名单或接口里已有 customerId、orderId 等字段时，打开转换，呼叫类型选预测 / 自动外呼，属性名填这些字段。推送参数再写 SVAR(customerId)、SVAR(orderId)，不必为共享变量单独改外呼入参结构。
五、典型场景与验收
场景：预测外呼或自动外呼推送业务字段
- 打开「启用共享变量」。
- 在共享变量页登记常用名称（可选）。
- 打开参数自动转换，呼叫类型选预测 / 自动外呼，属性名填名单字段。
- 在对应推送动作里，参数值写
SVAR(属性名)。 - 发起一通带该字段值的外呼，触发推送后核对下游收到的值。
| 验收项 | 预期 |
|---|---|
| 转换开启且属性已勾选 | 下游收到的是字段实际值 |
| 转换关闭或未勾选该属性 | 仍按原参数传递，不按共享变量展开该字段 |
推送参数未写 SVAR(...) | 推送不会自动带上该共享变量 |
| 本通没有该字段值 | 下游对应参数为空或按空值规则处理 |
六、FAQ
共享变量和自定义变量有什么区别？
自定义变量先约定项目业务字段的名字和来源。共享变量是本通上可共享读写的集合，并在推送里用 SVAR(变量名) 引用。名字可以一致，配置入口不同。
和 Copilot 常用变量是不是一回事？
不是。Copilot 智能体有自己的常用变量配置。推送配置里的共享变量是另一处。
只登记了名称，推送为什么还是空？
登记不产生通话值。先看「启用共享变量」是否打开，再确认本通是否已写入、推送参数是否写成 SVAR(变量名)。
参数自动转换要不要改现有外呼接口？
按设计不需要。开启后，指定呼叫类型下勾选的字段由平台转为共享变量；未开启或未指定的字段仍按原参数传递。
系统默认变量能删吗？
不能。系统默认项只读，保存企业常用变量时也不会覆盖它们。
共享变量会不会自动进话单？
不会仅因为写进共享变量就进入主话单或导出。要对账，按沉淀配置处理。
七、总结
共享变量服务「这一通已经写入的值，后面还能被推送和流程引用」。先确认写入来源，再在推送参数里用 SVAR(变量名) 引用；常用变量登记和参数自动转换分别解决命名管理和外呼字段转换。和自定义变量、缓存变量、Copilot 常用变量不要混用同一套配置入口。
Updated 16 days ago