内置变量

快速阅读

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

本文的核心结论是：

• 内置变量是平台在通话运行时和话单沉淀过程中提供的标准变量集合。
• 内置变量不是客户自定义字段，也不是某个页面参数；它是平台标准通话事实和运行上下文的可引用表达。
• 内置变量通常来自通话本身，例如客户号码、座席、热线、队列、通话标识、通话时间、通话状态、录音、任务、满意度等。
• 内置变量可以被 IVR、TTS、弹屏、推送、记录、导出、报表和质检等能力消费。
• 不是所有内置变量都适合长期查询和对账；只有被沉淀到话单、记录、推送日志或导出结果中的字段，才适合用于稳定追溯。

阅读地图

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

一、文档说明

1.1 文档目的

呼叫中心在处理一通电话时，会产生大量标准信息，例如客户号码、热线号码、队列、座席、通话标识、开始时间、接听时间、挂断方、录音文件、任务 ID、机器人会话等。

这些信息不仅用于通话记录，也会被以下能力使用：

1. IVR 根据变量判断客户进入哪个流程。
2. TTS 根据变量播报动态文本。
3. 工作台弹屏根据变量打开客户资料页。
4. 推送事件根据变量把通话结果同步给客户系统。
5. 话单和导出根据变量沉淀业务追溯字段。
6. 录音、质检和报表根据变量关联通话事实。

本文用于建立“内置变量”的统一产品说明，帮助客户和实施团队理解哪些变量是平台标准提供的、哪些是客户自定义传入的、哪些适合用于运行时、哪些适合用于记录沉淀和对账。

1.2 适用对象

• 客户业务负责人：用于理解平台标准字段如何支撑弹屏、推送、记录和报表。
• 运营管理人员：用于确认哪些变量可用于筛选、导出、质检和复盘。
• 实施顾问：用于配置 IVR、TTS、弹屏、推送和记录字段。
• 产品经理：用于统一变量、通道、话单、推送和报表之间的口径。
• 技术负责人：用于理解变量来源、生命周期、字段边界和对接验收。

1.3 文档范围

本文覆盖呼叫中心内置变量的产品说明，包括变量分类、来源、生命周期、引用方式、消费位置、与通道变量、自定义变量、话单字段、推送字段、弹屏参数和 TTS 变量的关系。

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

二、产品总览

2.1 什么是内置变量

内置变量是平台在通话运行时、事件推送、话单沉淀和页面联动中提供的标准变量集合。它来自平台已经识别或生成的通话事实。

人话总结：

内置变量就是平台已经知道的标准通话信息，可以被 IVR、弹屏、推送、记录和报表按需引用。

2.2 内置变量解决什么问题

如果没有内置变量，很多能力就需要重复配置或手工传值：

• IVR 无法根据客户号码、热线或队列上下文判断流程。
• TTS 无法播报动态订单号、排队位置或座席工号。
• 弹屏无法自动带入客户号码、通话标识或业务上下文。
• 推送无法稳定回传通话结果和关键标识。
• 记录和导出无法统一展示标准字段。
• 外部系统难以把事件、录音和话单对齐。

内置变量的作用，是让平台标准通话事实在不同能力之间可引用、可展示、可沉淀、可对账。

2.3 与通道变量的关系

通道变量是通话过程中的上下文承载机制，内置变量是平台标准提供的一类变量。

可以这样理解：

内置变量和自定义变量都可以作为通道变量的一部分在通话过程中使用；但它们是否进入话单、推送、导出或页面展示，取决于对应配置。

2.4 核心价值

三、核心概念

3.1 内置变量

内置变量是平台标准提供的运行时变量，通常不需要客户主动传入。它来自系统识别、通话状态、话单事实、任务上下文或平台配置。

典型内置变量包括：

• 通话标识。
• 客户号码。
• 座席信息。
• 热线号码。
• 队列信息。
• 通话类型。
• 开始、接听、结束时间。
• 接听状态和挂断方。
• 录音信息。
• 任务或机器人上下文。

3.2 自定义变量

自定义变量是客户系统、IVR 流程、SIP Header、机器人或外呼任务传入的业务扩展变量，例如客户 ID、订单号、工单号、线索 ID、活动批次等。

自定义变量通常用于客户侧业务联动，内置变量通常用于平台标准通话事实。

3.3 通道变量

通道变量是一次通话过程中的上下文载体。内置变量和自定义变量都可以在通道上下文中流转，被 IVR、TTS、弹屏、推送、记录等能力读取。

3.4 变量表达式

变量表达式是引用变量的一种方式。实施人员在配置 TTS、弹屏参数、推送参数或任务变量时，可通过约定表达方式引用某个变量值。

使用变量表达式时应注意：

• 变量名必须正确。
• 变量在当前通话上下文中必须存在。
• 变量为空时应有默认值或兜底路径。
• 不同消费方支持的变量范围可能不同。

3.5 TTS 变量

TTS 变量是 IVR 或提示音能力读取变量值并合成为语音的使用形态。

例如系统读取订单状态变量后，向客户播报“您的订单已发货”。如果变量为空，客户可能听到空播报或异常提示，因此必须配置兜底。

3.6 弹屏变量

弹屏变量是工作台、自定义弹屏页或自定义 Tab 页使用的变量。它通常会被转换成页面参数，用于打开 CRM、工单、订单或客户资料页。

弹屏变量的关键不是“变量存在”，而是页面参数名、变量名和客户系统接收字段要一致。

3.7 推送变量

推送变量是在事件推送中发送给客户系统的变量。不同事件可用变量范围不同，例如来电、响铃、接通、挂机、录音完成、满意度结束、IVR 结束、预测外呼状态等。

客户系统若依赖推送对账，应提前确认关键事件中是否都包含必要变量。

3.8 话单字段

话单字段是通话结束后沉淀到主话单、从话单或记录明细中的字段。内置变量不一定都会成为话单字段，只有被话单链路或记录配置沉淀后，才适合用于长期查询、导出和对账。

3.9 表头与导出字段

表头和导出字段是变量或话单字段的展示结果。它们不是变量来源，而是变量被沉淀和配置后在页面、导出文件或报表中呈现的方式。

四、对象关系与数据流

4.1 总体关系

通话接入或发起
↓
平台生成标准运行时上下文
├─ 内置变量：号码、座席、热线、队列、通话标识、时间、状态等
└─ 自定义变量：客户 ID、订单号、工单号、机器人会话 ID 等
↓
通道变量上下文
↓
IVR / TTS / 弹屏 / 推送 / 记录 / 报表 消费变量
↓
主话单 / 从话单 / 推送日志 / 导出结果 按配置沉淀

4.2 生命周期

内置变量通常经历以下生命周期：

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

关键边界：

• 运行时可用，不代表通话结束后可查。
• 推送中可用，不代表记录导出中一定有。
• 页面可展示，不代表话单中已沉淀。
• 记录可查询，才适合用于长期追溯和对账。

4.3 与主从话单的关系

内置变量既可能来自主通道，也可能来自子通道。

4.4 与外部系统的关系

外部系统通常通过内置变量和自定义变量完成业务联动：

• 用通话标识关联话单和推送。
• 用客户号码或客户 ID 打开客户资料。
• 用订单号或工单号回写业务结果。
• 用机器人会话 ID 查找机器人侧对话。
• 用任务 ID 和批次号核对外呼任务结果。

五、能力地图

六、产品功能说明

6.1 标准通话变量

标准通话变量用于描述一通电话的基础事实。

常见类别包括：

• 通话标识。
• 通话类型。
• 客户号码。
• 主叫号码、被叫号码、外显号码。
• 热线号码。
• 开始时间、接听时间、结束时间。
• 接听状态、呼叫结果、挂断方。

这些变量通常用于记录查询、推送、导出和排障。

6.2 座席与队列变量

座席与队列变量用于描述人工承接过程。

常见类别包括：

• 座席工号、座席姓名、座席号码。
• 队列号、队列名称。
• 座席响铃时间。
• 座席接听时间。
• 座席未接或拒接原因。
• 排队时长和等待信息。

这些变量通常用于座席接听记录、队列报表、弹屏和质检分析。

6.3 IVR 与流程变量

IVR 与流程变量用于描述客户在语音导航中的流转。

常见类别包括：

• IVR 名称。
• 节点名称。
• 按键结果。
• 收号结果。
• 时间条件。
• 流程分支。
• 转人工原因。

这些变量通常用于 IVR 判断、TTS 播报、IVR 报表、通话记录详情和推送。

6.4 机器人与智能体变量

机器人与智能体变量用于描述智能服务过程。

常见类别包括：

• 机器人名称。
• 会话 ID。
• 客户意图。
• 对话轮次。
• 是否解决。
• 是否转人工。
• 转人工原因。
• 会话摘要。

这些变量通常用于机器人记录、AI 转人工、质检、推送和工作台上下文展示。

6.5 任务变量

任务变量用于任务型外呼场景。

常见类别包括：

• 任务 ID。
• 任务名称。
• 批次号。
• 名单字段。
• 重呼轮次。
• 是否最终呼叫。
• 活动标签。

这些变量通常用于预测外呼记录、自动外呼记录、任务监控、任务报表和客户系统对账。

6.6 TTS 变量

TTS 变量用于把运行时变量转换成语音播报内容。

典型场景：

• 播报订单状态。
• 播报排队位置。
• 播报座席工号。
• 播报客户输入的号码。
• 播报机器人或业务系统返回的提示文本。

使用建议：

• 变量为空时必须有兜底提示。
• 播报文本不宜过长。
• 敏感信息不建议完整播报。
• 数字、金额、日期等内容应确认播报方式。

6.7 弹屏和自定义页面变量

弹屏和自定义页面变量用于把通话上下文带给座席工作台或客户业务系统。

配置时需要确认：

• 页面参数名。
• 变量来源。
• 参数是否必填。
• 页面鉴权方式。
• 变量为空时页面如何处理。
• 是否需要号码脱敏或加密串。

6.8 推送变量

推送变量用于在事件发生时把变量同步给外部系统。

不同事件的变量范围可能不同：

• 来电事件关注客户号码、热线、通话标识。
• 响铃事件关注座席和队列。
• 接通事件关注接听时间和接听方。
• 挂机事件关注结束时间、通话时长、挂断方。
• 话单事件关注完整通话结果。
• 录音事件关注录音文件和录音状态。

客户系统对账时，应确认需要的变量在哪些事件中返回。

6.9 话单和导出变量

话单和导出变量用于通话结束后的长期追溯。

建议原则：

• 需要长期查询的变量，应沉淀到记录字段。
• 只用于通话过程判断的变量，不一定需要导出。
• 主话单字段和从话单字段应区分。
• 机器人会话字段不应简单混入主话单。
• 导出字段应受权限和脱敏控制。

6.10 变量表达式使用

变量表达式用于在配置中引用变量。

使用建议：

• 只引用当前场景可用的变量。
• 变量名保持稳定。
• 变量为空时配置兜底。
• 上线前用真实通话验证。
• 不把示例变量名当作平台固定字段。

七、典型业务场景

7.1 呼入弹屏

客户拨打热线后，系统识别客户号码、热线、队列和通话标识，并在座席响铃时通过内置变量打开客户资料页。

关注点：

• 客户号码是否正确。
• 热线和队列是否能展示。
• 通话标识是否可用于后续回写。
• 页面参数是否和客户系统一致。

7.2 IVR 自助播报

客户在 IVR 中输入订单号，系统查询订单状态并通过 TTS 变量播报结果。

关注点：

• 收号结果是否正确。
• 查询结果是否进入变量。
• 变量为空时是否转人工或播放兜底提示。
• 播报内容是否适合语音表达。

7.3 CRM 点击外呼

座席从 CRM 发起外呼，平台内置变量提供通话标识、座席、时间和通话状态，自定义变量携带客户 ID 和线索 ID。通话结束后，推送事件把这些字段回传给 CRM。

关注点：

• 请求标识是否唯一。
• 推送事件是否带回客户系统需要的字段。
• 话单中是否沉淀用于对账的字段。

7.4 机器人转人工

机器人识别客户诉求后转人工，内置变量提供通话标识和通话状态，自定义或智能服务变量提供机器人会话 ID、意图、摘要和转人工原因。

关注点：

• 座席是否能看到机器人上下文。
• 机器人会话是否能和主话单关联。
• 转人工失败时是否有兜底。

7.5 预测外呼任务回溯

预测外呼任务产生通话后，内置变量提供通话标识、座席、接听状态、时间等，任务变量提供任务 ID、批次和名单字段。

关注点：

• 任务 ID 是否能关联任务监控和预测外呼记录。
• 重呼后是否能判断最终结果。
• 导出字段是否满足客户对账。

7.6 事件推送对账

客户系统收到来电、接通、挂机和话单生成事件后，通过内置变量中的通话标识和自定义业务标识关联同一通电话。

关注点：

• 各事件中的标识是否一致。
• 事件粒度是整通电话还是某一段通话腿。
• 话单生成事件是否作为最终对账依据。

八、上线准备与运营建议

8.1 上线前确认事项

上线使用内置变量前，建议确认：

1. 本项目要使用哪些变量。
2. 变量是平台内置还是客户自定义。
3. 变量使用场景是 IVR、TTS、弹屏、推送、话单还是导出。
4. 变量是否在当前通话类型下可用。
5. 变量是否需要沉淀到主话单、从话单或机器人会话。
6. 变量是否涉及敏感信息和脱敏要求。
7. 变量为空时如何处理。
8. 客户系统是否依赖变量做对账。
9. 变量变更是否影响外部系统。

8.2 实施建议

• 先确认变量清单，再配置页面、推送和记录。
• 优先使用平台标准内置变量，不重复创建同义自定义变量。
• 自定义变量命名应和内置变量区分，避免混淆。
• 关键变量要做真实通话验证。
• 涉及话单对账的变量必须验证沉淀结果。
• 涉及推送的变量必须验证事件返回。
• 涉及 TTS 的变量必须验证空值和异常播报。

8.3 风险提示

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 内置变量和通道变量有什么区别？

内置变量是平台标准变量集合，通道变量是通话过程中的上下文承载机制。内置变量可以通过通道变量在一次通话中流转。

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

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

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

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

10.4 为什么推送里没有某个变量？

可能该事件不支持该变量，或推送变量未配置，或变量在事件发生时尚未产生。需要按事件类型确认变量可用范围。

10.5 TTS 变量为空怎么办？

应配置默认播报、失败提示或转人工兜底，避免客户听到空内容或异常停顿。

10.6 内置变量能否用于长期对账？

只有沉淀到话单、推送日志、导出或记录字段中的变量，才适合长期对账。纯运行时变量不建议作为长期对账依据。

10.7 可以修改内置变量名称吗？

通常不建议也不应修改平台内置变量名称。客户如需业务化命名，可在弹屏参数、推送字段或导出表头中使用业务展示名。

10.8 自定义变量能不能覆盖内置变量？

不建议。自定义变量应避免与内置变量同名或同义混用，防止弹屏、推送和话单字段口径混乱。

10.9 如何判断某个变量在哪些场景可用？

应结合通话类型、事件类型、配置入口和实际测试通话确认。不要假设所有变量在所有场景都可用。

10.10 内置变量是否都能导出？

不一定。导出取决于记录字段、表头配置、权限和产品版本。运行时可用的变量不一定出现在导出中。

十一、总结

内置变量是呼叫中心标准通话事实和运行上下文的统一表达。它连接通话通道、IVR、TTS、弹屏、推送、话单、导出、报表和质检能力，是客户业务系统与呼叫中心协同的重要基础。

使用内置变量时，应先确认变量来源和生命周期，再确认消费位置和沉淀范围。对于需要长期查询和对账的字段，必须验证其是否进入主话单、从话单、推送日志或导出结果；对于只在运行时使用的变量，应配置空值和异常兜底。

附录 A：入口与权限

权限建议：

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

附录 B：关键字段口径

附录 C：实施检查清单

附录 D：常见问题速查

附录 E：术语表