自定义变量

快速阅读

本文用于统一说明呼叫中心自定义变量的产品定位、来源、生命周期、使用场景、与内置变量和通道变量的关系，以及在 IVR、TTS、弹屏、推送、话单、导出、报表和质检中的使用原则。

本文的核心结论是：

• 自定义变量是客户系统、IVR、机器人、SIP Header、外呼任务或座席操作写入的业务扩展上下文。
• 自定义变量不是平台内置变量，也不天然等于话单字段、推送字段、弹屏参数或导出列。
• 自定义变量进入通话上下文后，只有按配置被弹屏、推送、话单、导出或报表消费，才会在对应能力中生效。
• 弹屏有值不代表话单可查，推送有值不代表导出有列，运行时有值不代表通话结束后永久保存。
• 上线自定义变量前，必须统一变量清单、命名、来源、格式、长度、脱敏、沉淀范围、推送范围和验收路径。

阅读地图

• 如果只想理解自定义变量是什么，重点阅读“二、产品总览”和“三、核心概念”。
• 如果要理解自定义变量如何随通话流转，重点阅读“四、对象关系与数据流”。
• 如果要在 IVR、TTS、弹屏、推送、话单中使用变量，重点阅读“六、产品功能说明”。
• 如果要做实施验收和排障，重点阅读“八、上线准备与运营建议”和“附录 C：实施检查清单”。

一、文档说明

1.1 文档目的

呼叫中心在处理客户来电、座席外呼、WebCall、预测外呼、机器人转人工和 SIP 接入时，除了平台标准通话信息，还经常需要携带客户侧业务信息，例如：

1. 客户 ID、会员等级、客户标签。
2. 工单号、订单号、预约 ID、服务记录 ID。
3. 销售线索 ID、活动编号、营销批次。
4. 机器人会话 ID、客户意图、转人工原因、会话摘要。
5. 外部系统会话 ID、第三方通话标识、SIP Header 透传字段。

这些字段不是平台天然知道的标准通话事实，通常需要客户系统、流程节点或任务配置写入。自定义变量的作用，就是把这些客户侧业务字段带入一次通话，让后续弹屏、推送、话单、导出、报表和质检可以使用。

本文用于建立“自定义变量”的统一产品说明，帮助客户和实施团队理解变量从哪里来、如何进入通话上下文、能被哪些能力消费、什么时候可以长期查询和对账。

1.2 适用对象

• 客户业务负责人：用于理解通话如何关联 CRM、工单、订单、机器人和任务。
• 运营管理人员：用于确认哪些业务字段需要展示、推送、导出或统计。
• 实施顾问：用于规划变量清单、命名、映射、联调、验收和排障。
• 产品经理：用于统一自定义变量、内置变量、通道变量、话单字段和推送字段之间的口径。
• 技术负责人：用于理解变量来源、传递链路、字段限制、对接边界和数据安全要求。

1.3 文档范围

本文覆盖呼叫中心自定义变量的产品说明，包括变量来源、生命周期、引用方式、命名规范、长度和数量限制、与内置变量、通道变量、话单字段、推送字段、弹屏参数、TTS 变量和报表字段的关系。

本文不展开底层通信协议、代码实现和内部实现细节；涉及 SIP Header、变量表达式或字段示例时，仅作为产品口径说明，具体支持范围以实际系统版本和配置页面为准。

二、产品总览

2.1 什么是自定义变量

自定义变量是由客户系统、IVR 流程、SIP Header、机器人、外呼任务或人工操作写入的业务扩展变量。它通常用于补充平台内置变量无法直接表达的客户侧业务上下文。

人话总结：

自定义变量就是客户希望随一通电话一起带进来的业务字段，例如“这通电话属于哪个客户、哪个订单、哪个工单、哪个机器人会话”。

2.2 自定义变量解决什么问题

如果没有自定义变量，电话系统只能知道通话本身的信息，例如号码、座席、热线、队列、接听状态和通话时间；但客户业务系统还需要知道：

• 这通电话对应哪个客户。
• 这通电话对应哪个工单。
• 这次外呼来自哪个营销活动。
• 机器人前面和客户聊了什么。
• 通话结束后结果要回写到哪个业务对象。
• 录音质检要按哪个业务维度抽样。

自定义变量用于把“通话事实”和“客户业务对象”连接起来。

2.3 与内置变量的区别

2.4 与通道变量的关系

通道变量是一次通话过程中的上下文承载机制。自定义变量进入通话上下文后，可以作为通道变量的一部分被 IVR、TTS、弹屏、推送、记录等能力读取。

可以这样理解：

自定义变量 = 客户侧业务字段
通道变量 = 通话过程中的承载容器
话单字段 / 推送字段 / 弹屏参数 = 不同消费结果

2.5 核心价值

三、核心概念

3.1 自定义变量

自定义变量是客户或业务流程按项目约定写入的扩展字段。它的变量名和变量值通常由项目双方提前约定。

典型自定义变量包括：

• customer_id：客户编号。
• order_id：订单编号。
• ticket_id：工单编号。
• lead_id：销售线索编号。
• campaign_id：营销活动编号。
• robot_session_id：机器人会话编号。
• transfer_reason：转人工原因。

3.2 变量名

变量名是自定义变量的稳定识别名称。变量名会被弹屏、推送、记录、导出、IVR、TTS、机器人等配置引用。

变量名建议：

• 语义清晰。
• 前后一致。
• 不和内置变量混淆。
• 不使用过于泛化的名称。
• 上线后尽量不改名。
• 不把测试示例名当作正式变量名。

3.3 变量值

变量值是本次通话中对应变量实际携带的内容。例如某通电话的 ticket_id 可能是一个具体工单号。

变量值应注意：

• 控制长度。
• 统一字符格式。
• 避免前后空格。
• 不传敏感明文。
• 空值应有明确处理策略。

3.4 变量来源

自定义变量可来自多个来源：

3.5 变量表达式

变量表达式是在配置中引用变量值的方式。它常用于弹屏参数、TTS 播报、推送参数、外呼任务通道变量等场景。

使用变量表达式时，应确认：

• 变量名是否正确。
• 当前场景是否存在该变量。
• 变量为空时如何处理。
• 变量值是否适合被展示、播报或推送。

3.6 话单自定义字段

话单自定义字段是自定义变量沉淀到记录后的结果。只有进入话单或记录扩展字段的自定义变量，才适合用于长期查询、导出和对账。

需要注意：

• 自定义变量不一定自动进入话单。
• 主话单和从话单的沉淀口径可能不同。
• 只有配置为记录字段或导出列后，用户才可能在页面或文件中看到。

3.7 推送自定义字段

推送自定义字段是事件推送中带给客户系统的业务字段。不同事件可带出的字段范围和触发时机可能不同。

客户系统如果依赖变量对账，应确认来电、接通、挂机、话单生成等关键事件是否都能带出必要字段。

3.8 弹屏参数

弹屏参数是自定义变量在页面消费侧的表现形式。变量通常会被转换为 URL 参数、Tab 参数或页面字段。

弹屏参数名不一定等于变量名，但二者必须建立清晰映射关系。

3.9 任务自定义字段与任务通道变量

在任务型外呼中，自定义变量常分为两类：

• 任务自定义字段：更偏任务、名单、批次和记录沉淀。
• 任务通道变量：更偏运行时通话上下文，可能用于座席侧通道、弹屏、推送或后续链路。

两类字段使用目标不同，配置前应明确用途。

四、对象关系与数据流

4.1 总体关系

客户系统 / IVR / 机器人 / SIP 接入 / 外呼任务
↓ 写入业务字段
自定义变量
↓ 进入通话上下文
通道变量
├─ 运行时消费：IVR / TTS / 弹屏 / 座席操作
├─ 事件消费：推送 / 状态同步 / 转人工
└─ 结束沉淀：主话单 / 从话单 / 记录字段 / 导出 / 报表
↓
客户系统对账 / 质检复盘 / 运营分析

4.2 生命周期

自定义变量通常经历以下生命周期：

变量产生或传入
↓
进入实时通话上下文
↓
被 IVR、TTS、弹屏、推送、座席操作读取
↓
按配置进入主话单、从话单、推送日志、记录扩展字段、导出字段或报表统计
↓
用于查询、对账、复盘、质检、排障

关键边界：

• 运行时可用，不代表通话结束后可查。
• 弹屏有值，不代表话单可查。
• 推送有值，不代表导出有列。
• 变量进入主话单或从话单后，才适合长期追溯。
• 报表能否按变量统计，取决于变量是否进入统计链路。

4.3 与主从话单的关系

自定义变量可按业务需要沉淀到不同对象：

4.4 与外部系统的关系

外部系统通过自定义变量完成通话与业务对象的关联：

• CRM 用客户 ID 或线索 ID 回写通话结果。
• 工单系统用工单号关联录音和服务过程。
• 订单系统用订单号查询通话历史。
• 机器人平台用会话 ID 关联转人工前的对话。
• 数据平台用活动批次和通话标识做对账。

五、能力地图

六、产品功能说明

6.1 变量清单管理

上线前应先整理自定义变量清单。清单建议包含：

• 变量名。
• 变量含义。
• 变量来源。
• 是否必填。
• 字段格式。
• 最大长度。
• 是否敏感。
• 使用场景。
• 是否需要沉淀到话单。
• 是否需要推送或导出。

没有变量清单就直接配置弹屏、推送或记录，后续很容易出现字段对不上、命名冲突或对账失败。

6.2 变量写入

自定义变量可通过以下方式写入：

1. 客户系统发起外呼、WebCall 或回拨时传入。
2. SIP 接入时通过约定 Header 透传。
3. IVR 收号、查询或脚本流程生成。
4. 机器人或智能体在会话中生成。
5. 外呼任务名单、任务模板或任务配置携带。
6. 座席或业务页面在通话过程中补充。

写入后，变量先进入通话上下文，后续能力再按配置读取或沉淀。

6.3 变量读取

自定义变量可被以下能力读取：

• IVR 判断节点读取变量并分流。
• TTS 读取变量并动态播报。
• 弹屏读取变量并打开业务页面。
• 推送读取变量并发送给客户系统。
• 记录读取变量并沉淀为扩展字段。
• 报表或导出读取沉淀字段做分析。

变量读取失败时，应先确认变量是否已经进入通话上下文，再检查消费方配置。

6.4 IVR 与 TTS 使用

IVR 和 TTS 可使用自定义变量完成动态服务。

典型场景：

• 根据客户等级变量进入不同队列。
• 根据订单号查询结果并播报。
• 根据机器人意图决定是否转人工。
• 根据活动标签播放不同提示语。

使用建议：

• 变量为空时必须有兜底路径。
• 不适合语音播报的内容不要直接播报。
• 敏感字段不建议完整播报。
• 播报前应确认数字、金额、日期的表达方式。

6.5 弹屏和自定义页面使用

弹屏和自定义页面通常把自定义变量转换为页面参数。

配置时应确认：

• 页面参数名。
• 平台变量名。
• 客户系统接收字段。
• 页面鉴权方式。
• 变量为空时页面如何处理。
• 是否需要脱敏或加密串。

示例：

6.6 推送使用

推送使用自定义变量时，应先明确哪些事件需要带出变量。

常见事件包括：

• 来电进入。
• 座席响铃。
• 通话接通。
• 通话挂机。
• 话单生成。
• 录音完成。
• IVR 结束。
• 机器人转人工。
• 预测外呼状态变化。

不同事件发生时，变量可能尚未产生或已经发生变化，因此应按事件逐一验证。

6.7 话单和导出使用

如果自定义变量需要长期追溯，应配置进入话单或记录扩展字段。

建议原则：

• 用于对账的字段优先沉淀到主话单。
• 只和某段过程有关的字段可沉淀到从话单。
• 机器人会话字段应沉淀到机器人会话或对应记录。
• 导出字段应和页面展示口径一致。
• 不要把大量临时变量全部导出。

6.8 外呼任务使用

任务型外呼中，自定义变量常用于名单、任务、座席侧通道和记录对账。

常见用法：

• 名单字段携带客户标签和活动编号。
• 任务自定义字段用于任务维度对账。
• 通道变量用于座席侧通话上下文。
• 记录和导出用于回溯每通任务呼叫结果。

使用限制应以实际系统版本为准。实施中应特别关注变量数量、单字段长度、字段格式和重呼后的变量一致性。

6.9 SIP Header 透传

SIP Header 透传是自定义变量的一类来源。

推荐链路：

客户侧发送约定 Header
↓
平台读取 Header
↓
映射为项目约定变量名
↓
进入通话上下文
↓
弹屏、推送、话单、导出按配置消费

页面通常不会直接读取原始 Header。如果弹屏没有值，应先检查 Header 是否进入通话上下文，而不是只检查页面配置。

6.10 报表和质检使用

自定义变量可用于报表和质检，但前提是变量已经进入可统计或可查询的数据链路。

使用建议：

• 报表统计前确认变量是否沉淀。
• 高基数字段不适合直接作为聚合维度。
• 质检抽样可使用客户标签、业务线、工单类型等变量。
• 录音复盘可通过业务标识关联客户侧对象。

七、典型业务场景

7.1 CRM 点击外呼

座席在 CRM 中点击客户号码发起外呼。CRM 传入客户 ID、线索 ID 和请求唯一标识。通话结束后，推送事件带回这些变量，CRM 根据变量回写通话结果。

关注点：

• 客户 ID 和线索 ID 是否稳定。
• 请求唯一标识是否唯一。
• 推送事件是否带出变量。
• 话单或导出是否沉淀关键字段。

7.2 工单回访

售后系统发起回访，传入工单号、服务记录 ID 和客户标签。座席接听或外呼时，弹屏自动打开工单详情。

关注点：

• 弹屏参数是否和工单系统一致。
• 工单号是否沉淀到记录。
• 录音是否可按工单追溯。
• 回访结果是否能回写。

7.3 IVR 自助查询

客户在 IVR 中输入订单号，系统查询订单状态并把查询结果写入自定义变量。客户可听到 TTS 播报，也可转人工后让座席看到订单上下文。

关注点：

• 收号校验是否准确。
• 查询失败是否有兜底。
• TTS 变量为空时如何处理。
• 转人工后变量是否展示给座席。

7.4 机器人转人工

机器人识别客户意图后生成会话 ID、意图、摘要和转人工原因。转人工时，这些自定义变量随通话传递给座席。

关注点：

• 机器人会话 ID 是否稳定。
• 转人工原因是否清晰。
• 会话摘要是否适合展示。
• 记录和推送是否保留变量。

7.5 SIP 呼入对接

客户侧系统通过 SIP 呼入，并通过 Header 传入外部会话 ID 或机器人会话 ID。平台读取后映射为自定义变量，用于弹屏、推送和话单。

关注点：

• Header 命名是否按项目约定。
• 变量名是否统一。
• 页面、推送和记录是否引用同一变量。
• 联调时先验证变量链路，再验证页面。

7.6 预测外呼任务变量

预测外呼任务导入名单时携带客户标签、批次号、活动编号。客户接通并分配座席后，变量用于弹屏、记录、报表和对账。

关注点：

• 名单字段格式是否统一。
• 重呼后变量是否保持一致。
• 导出字段是否满足客户对账。
• 报表是否需要按变量维度分析。

八、上线准备与运营建议

8.1 上线前确认事项

上线自定义变量前，建议确认：

1. 变量清单是否完整。
2. 每个变量的业务含义是否明确。
3. 每个变量从哪里来。
4. 每个变量要被哪些能力消费。
5. 变量是否需要沉淀到主话单、从话单、机器人会话或导出。
6. 变量是否需要推送给客户系统。
7. 变量是否用于报表统计或质检抽样。
8. 变量是否包含敏感信息。
9. 变量为空、超长、格式错误时如何处理。
10. 变量变更后如何通知客户系统和运营人员。

8.2 命名建议

变量命名建议：

• 使用业务含义清晰的英文或拼音缩写。
• 同一项目内统一命名风格。
• 不与内置变量重名。
• 不使用 value、data、id 等含义过宽的名称。
• 不在变量名中包含临时测试含义。
• 上线后尽量不修改变量名。

8.3 安全与脱敏

自定义变量可能包含客户业务数据，应遵循：

• 不传密码、验证码、银行卡号、完整证件号等高敏感明文。
• 如需关联敏感对象，优先传业务 ID、加密串或脱敏值。
• 弹屏、推送、导出受权限控制。
• 导出前确认字段范围。
• 对外推送前确认客户系统接收权限和安全责任。

8.4 验收建议

验收不应只看弹屏是否显示变量，还应覆盖：

• 变量来源是否正确。
• 变量是否进入通话上下文。
• IVR / TTS 是否能读取变量。
• 弹屏和自定义页面是否能收到变量。
• 推送事件是否带出变量。
• 主话单、从话单或机器人会话是否按需沉淀变量。
• 导出和报表是否能使用沉淀字段。
• 变量为空、超长、格式错误时是否有兜底。

九、与周边能力的关系

9.1 与内置变量的关系

内置变量由平台提供，自定义变量由客户或业务流程写入。自定义变量应补充内置变量无法表达的业务上下文，而不是重复定义平台已有标准字段。

9.2 与通道变量的关系

自定义变量进入一次通话后，可作为通道变量的一部分随通话流转。通道变量是承载机制，自定义变量是业务内容。

9.3 与主从话单的关系

自定义变量是否进入主话单、从话单或机器人会话，取决于沉淀配置和业务需要。用于整通电话对账的变量适合主话单，用于某段过程分析的变量适合从话单。

9.4 与 IVR / TTS 的关系

IVR 可读取自定义变量进行分流、判断和 TTS 播报。变量为空时必须配置兜底，避免客户卡在流程中。

9.5 与弹屏和工作台的关系

弹屏可使用自定义变量打开客户资料、工单、订单或机器人会话页面。页面参数名和变量名必须映射清楚。

9.6 与推送的关系

推送可把自定义变量同步给外部系统。客户系统如果依赖变量对账，需要确认变量在哪些事件中返回，以及事件粒度是整通电话还是某一段通话腿。

9.7 与报表和导出的关系

报表和导出使用的是沉淀后的字段。运行时自定义变量如果没有进入记录或统计链路，不适合作为报表字段或长期对账字段。

十、FAQ

10.1 自定义变量和内置变量有什么区别？

内置变量由平台自动生成或识别，自定义变量由客户系统、IVR、机器人、SIP Header、外呼任务或人工操作写入。

10.2 自定义变量和通道变量有什么区别？

自定义变量是业务字段，通道变量是承载机制。自定义变量进入通话上下文后，可以作为通道变量流转。

10.3 弹屏有变量，为什么记录里没有？

弹屏是运行时消费，记录是通话结束后的沉淀结果。变量是否进入记录，需要看话单字段或记录扩展字段配置。

10.4 推送有变量，为什么导出没有？

推送字段和导出字段是不同消费链路。推送带出变量，不代表该变量已配置为导出列。

10.5 SIP Header 已经传了，为什么页面没有值？

需要先确认 Header 是否被平台读取并映射为自定义变量。页面通常不会直接读取原始 Header。

10.6 自定义变量能否用于报表统计？

可以按场景支持，但前提是变量进入统计链路，并且字段适合作为统计维度。高基数字段不适合直接聚合。

10.7 自定义变量能传敏感信息吗？

不建议传递敏感明文。应优先传业务 ID、加密串或脱敏值，并通过权限控制弹屏、推送和导出。

10.8 自定义变量可以修改名称吗？

不建议随意修改。变量名一旦被弹屏、推送、记录、导出或客户系统引用，改名会影响多个下游能力。

10.9 自定义变量为空怎么办？

应根据场景配置兜底：IVR 可转人工或播放提示，弹屏可打开默认页面，推送可返回空值或省略字段，但需和客户系统约定。

10.10 是否所有自定义变量都要沉淀到话单？

不需要。只沉淀有查询、导出、对账或复盘价值的字段。临时流程变量、敏感字段和无长期价值字段不建议全部沉淀。

十一、总结

自定义变量是呼叫中心连接客户业务系统的重要扩展能力。它把客户 ID、订单号、工单号、线索 ID、机器人会话 ID、任务批次等业务上下文带入通话链路，使 IVR、TTS、弹屏、推送、话单、导出、报表和质检能够围绕同一业务对象协同。

使用自定义变量时，应先明确变量清单、来源、命名和用途，再决定是否展示、推送、沉淀、导出或统计。只有让变量在“产生、流转、消费、沉淀、验收、变更”各环节都有清晰口径，才能稳定支撑客户业务闭环。

附录 A：入口与权限

权限建议：

• 变量配置权限应限制给实施或管理员。
• 推送和导出字段变更应有变更记录。
• 含敏感信息的变量应受脱敏、数据范围和导出权限控制。

附录 B：关键字段口径

附录 C：实施检查清单

附录 D：常见问题速查

附录 E：术语表