自定义变量

快速阅读

自定义变量是项目约定、由外部系统或流程写入的业务字段，用来补充内置变量没有的客户侧上下文，例如客户 ID、订单号、工单号、线索 ID、呼入或外呼机器人会话 ID。

• 变量名一旦被弹屏、推送、记录、导出、IVR 或 TTS 引用，就不要再改。
• 来源：外部请求、SIP Header、IVR、呼入或外呼机器人、外呼任务、座席操作。
• 弹屏参数名可以和变量名不同，但要有明确映射。
• 是否进入主话单、从话单或机器人会话，取决于沉淀配置，不是写入之后自动留下。
• 推送要按本通取值时，用共享变量，并在推送参数里写 SVAR(变量名)。配置入口在推送配置的「共享变量」页，和 Copilot 智能体里的常用变量不是同一处。用法见共享变量。

阅读地图

• 和内置变量的差别：读「二」。
• 对名字、来源和沉淀：读「三」。
• 对不上账：读「四」。

一、文档说明

本文说明自定义变量怎么命名、从哪写入、被谁消费。平台标准字段见内置变量。只在当前节点临时用、不打算长期保留的值，见缓存变量。

二、产品总览

客户系统 / IVR / SIP Header / 呼入或外呼机器人 / 外呼任务 / 座席操作
→ 写入变量名和变量值
→ IVR 判断、TTS、座席工作台弹屏、推送读取
→ 按配置沉淀到主话单、从话单、机器人会话或导出列

现稿里的示例名包括 ticket_id、robot_session_id、robotSessionId、conversationId。它们是项目示例，不是平台内置字段。正式名字由项目约定，不要把测试名留到上线。

三、字段

整通对账的变量适合主话单。只描述某一段的变量适合从话单。呼入或外呼机器人的会话字段适合机器人会话记录，不要默认写进主话单。

SIP 接入时，Header 里的外部会话 ID 要先映射成项目约定的变量名，再给弹屏和推送用。

四、FAQ

和缓存变量有什么区别？
自定义变量强调这是项目约定要带的业务字段。缓存变量强调它在当前通话或会话里临时可读。一个业务字段可以先作为缓存值使用，再按配置沉淀。

弹屏有值，客户系统对不上？
核对变量名有没有改过、标识是不是 mainUniqueId 或 requestId、推送事件发生时值是否已经写入。

转人工后座席工作台没有会话摘要？
呼入或外呼机器人写入的会话 ID、意图、摘要、转人工原因，要作为变量传到座席工作台，并在弹屏参数里映射。

敏感内容能不能当变量值？
客户编号优先传 ID。明文敏感信息按项目脱敏要求处理，不在变量名里做测试标记。

五、总结

自定义变量先定名字和来源，再逐个确认弹屏、IVR、推送和话单要不要用。改名会影响已经接上的消费方。