service-digital-engagement-channel-configure

配置增强型聊天渠道

为 Salesforce 应用内和 Web 消息（MIAW）创建 MessagingChannel 元数据 XML。此技能可生成完整配置的增强型聊天渠道，其中包含路由、用户验证、聊天前表单和自动回复设置，可直接用于 Metadata API 部署。

范围

• 范围内：创建包含 Omni-Channel Flow 路由、Omni-Channel Queue 路由或 Agentforce Service Agent（ASA）路由的 MessagingChannel 元数据；启用用户验证；配置所有渠道设置（聊天前表单、自动回复、同意关键词、文件附件、自定义参数）
• 范围外：创建引用的 Omni-Channel Flow/Queue 定义（使用 automation-flow-generate）、创建 Embedded Service Deployment（单独的元数据类型 — 使用 service-digital-engagement-deployment-configure）、创建消息传递权限集（使用 platform-permission-set-generate）、配置 Embedded Service Code Snippet

---

入口点和传输方式

• 委派模式（context.calledFrom == "service-onboarding"）：使用已批准的 values，不提问；如果缺少任何必需键，则返回 failed 并指出缺少的键。独立模式（无 context）：执行澄清问题。
• 传输方式 A（主要）：通过 /headless/metadata 使用 headless-360 MCP dispatch / dispatch_readonly。传输方式 B：仅当探测结果显示传输方式 A 不可用时，使用下方的 sf 命令。

详情：references/onboarding_contract.md（§1 入口点、§2 传输方式、§3 预扫描、§5 结果）。

---

澄清问题

生成前，如果信息尚不明确，请询问用户（仅独立模式）：

• 渠道名称/标签是什么？（用于 masterLabel 和文件名）
• 路由类型是什么？（Omni-Channel Flow、Omni-Channel Queue、User 或 Agentforce Service Agent）
• 路由目标是什么？（Flow API 名称、Queue 开发者名称、User ID 或 ASA 机器人名称）
• 对于 Flow、User 或 ASA 路由：回退队列名称是什么？
• 是否应启用用户验证？（根据此技能，默认值为 true）
• 是否需要聊天前表单字段？如果需要，字段及其类型是什么？

---

必需输入

继续前，请收集或推断以下信息：

• 渠道名称：用于 masterLabel 和文件名（<Name>.messagingChannel-meta.xml）
• 路由类型：Queue、Flow、User 或 AgentforceServiceAgent 之一
• 路由目标：队列、流程、用户或 ASA 机器人的开发者名称
• 回退队列（Flow、User 和 ASA）：用于升级处理的回退队列开发者名称
• 用户验证：是否要求基于 JWT 的身份验证（默认值：true）

除非另有说明，否则使用以下默认值：

• messagingChannelType：EmbeddedMessaging
• authMode：Auth
• chatAbandonmentTimeout：5（分钟）
• endUserIdleTimeOut：5（分钟）
• isAttachmentUploadEnabled：true
• maxFileSize：5（MB）
• allowedFileTypes：bmp,csv,doc,docx,gif,jpg,pdf,png,tiff,txt,xls,xml
• anonymousUserJwtExpirationTime：360（分钟，UnAuth 必需，范围为 60-4320）
• verifiedUserJwtExpirationTime：60（分钟，Auth 必需，范围为 60-240）
• isAbandonedChatsEnabled：false
• isSaveTranscriptEnabled：false
• isFallbackMessageEnabled：false
• isEstimatedWaitTimeEnabled：false
• isFileAttachmentExtUnrestricted：false
• isQueuePositionEnabled：false
• isSynchronousChatEnabled：false
• isVoiceModeEnabled：false

---

工作流

所有步骤均须按顺序执行。不得跳过或调整顺序。

阶段 1 — 收集上下文

1. 验证组织 API 版本 — 运行 scripts/check-api-version.sh 67.0 <org-alias>，并报告其返回的任何错误。如果脚本失败，请在元数据输出文件夹中生成 sfdx-project.json，并设置 "sourceApiVersion": "67.0"。

2. 收集输入 — 独立执行：根据澄清问题收集。委派执行：从 values 收集。然后通过对 MessagingChannel 执行只读 GET 来探测传输方式（契约 §2）。

3. 确定文件名 — 运行 scripts/normalize-channel-name.sh "<LABEL>"，并指出其返回的任何错误。

3a. 预扫描 — 按第 3 步生成的名称对 MessagingChannel 执行 GET（契约 §3）：未找到 → 创建；找到且处于活动状态 → 不写入，返回 already-configured，跳至阶段 4；找到但未激活 → 仅激活（第 15 步）；存在差异 → 逐项说明每处变更，然后写入完整文档（独立执行：先询问）。

4. 验证路由目标是否存在 — 如果第 3a 步的结果是 already-configured 或仅激活，则跳过此步骤，这样重新运行时就不会创建队列。查询组织以确认所引用的路由目标存在：

   • 对于 Queue：sf data query --query "SELECT Id, DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='<QUEUE_NAME>'" --target-org <org-alias>
   • 对于 Flow：sf data query --query "SELECT Id, ApiName FROM FlowDefinitionView WHERE ApiName='<FLOW_NAME>' AND IsActive=true" --target-org <org-alias>
   • 对于 User：sf data query --query "SELECT Id, Username FROM User WHERE Id='<USER_ID>' AND IsActive=true" --target-org <org-alias>
   • 对于 ASA：sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName='<BOT_NAME>'" --target-org <org-alias>
   • 还要验证备用队列是否存在（Flow、User 和 ASA 路由必需）

   如果找不到任何目标：独立执行 — 告知用户并询问是否创建。委派执行 — 返回 failed 并指出缺失的目标；绝不要创建。如果独立执行时用户确认创建：

   • 对于 Queue：生成包含 MessagingSession 作为 queueSobject 类型的 .queue-meta.xml，并在通道部署前部署它。**新建队列需要 QueueRoutingConfig，否则即使通道部署并激活，会话也会失败，并显示“座席不可用。请稍后重试”。**队列部署完成后，立即按照 service-agentforce-channel-configure 中的 references/queue-resolution.md 第 4 步解析或创建一个；不要延后。
   • 对于 Flow/User/ASA：告知用户必须单独创建流程、用户或机器人（不在此技能范围内）

5. 阅读通道设置参考 — 加载 references/channel_settings.md，了解所有可用的配置选项及其有效值。

第 2 阶段 — 生成元数据

6. 读取元数据模板 — 将 assets/messaging_channel_template.xml 作为起始结构加载。

7. 应用路由配置 — 设置 sessionHandlerType 和对应的处理器字段：

   路由类型	sessionHandlerType	必填字段
   Omni-Channel 队列	Queue	sessionHandlerQueue
   Omni-Channel Flow	Flow	sessionHandlerFlow + sessionHandlerQueue（回退）
   用户	User	sessionHandlerUser + sessionHandlerQueue（回退）
   Agentforce Service Agent	AgentforceServiceAgent	sessionHandlerQueue（回退）+ sessionHandlerAsa（bot 开发名称 — 必填，见下方 v67 说明）

   v67 说明 — <sessionHandlerAsa> 为必填项（省略会因“Missing required Agentforce Service Agent”失败）；部署时会绑定 SessionHandlerId，无需 PATCH。Bot 必须先处于 Active 状态：运行 sf agent activate -o <org> --api-name <BotDevName>，并确认 BotVersion.Status = Active。

8. 应用用户验证 — 如果启用，则将 embeddedConfig.authMode 设为 Auth，并包含 <messagingAuthorizations>。如果未启用，则将 embeddedConfig.authMode 设为 UnAuth，并省略 <messagingAuthorizations>。

9. 配置嵌入式设置 — 在 <embeddedConfig> 中填入：

   • allowedFileTypes — 以逗号分隔的文件扩展名（不含空格）
   • anonymousUserJwtExpirationTime — JWT 过期时间（分钟；UnAuth 必填）
   • verifiedUserJwtExpirationTime — JWT 过期时间（分钟；Auth 必填）
   • chatAbandonmentTimeout — 对话被放弃后清理前的等待时间（分钟）
   • isAbandonedChatsEnabled — 启用已放弃聊天检测
   • isAttachmentUploadEnabled — 支持文件上传
   • isEstimatedWaitTimeEnabled — 显示预计等待时间
   • isFallbackMessageEnabled — Agent 不可用时启用回退消息
   • isFileAttachmentExtUnrestricted — 允许任意文件扩展名
   • isSaveTranscriptEnabled — 保存对话记录
   • maxFileSize — 附件最大大小（MB）

10. 配置消息关键字 — 生成 <messagingKeywords> 元素：

    • OptOut 类型，包含单独的 <keyword> 元素：cancel、end、quit、stop、stopall、unsubscribe
    • Help 类型，包含 <keyword>：help

11. 应用标准参数 — 如果用户需要标准的预聊天字段，则生成带有 parameterType 的 <standardParameters> 元素。如果通道使用基于 Flow 的路由，且用户指定了 Flow 变量映射，则包含 <actionParameterMappings>，并使用 actionParameterName 将每个参数映射到一个 Flow 输入变量。

12. 应用自定义参数 — 如果用户需要收集预聊天数据，则生成包含 name、masterLabel、parameterDataType、externalParameterName 和 maxLength 的 <customParameters> 元素。始终将 parameterDataType 设为 String — 通道不接受其他值（字段的实际类型，包括 Checkbox/Number/下拉列表，应通过部署级别的 formFieldType 设置，而非在此处设置）。如果通道使用基于 Flow 的路由，且用户指定了 Flow 变量映射，则包含 <actionParameterMappings>，并使用 actionParameterName 将每个参数映射到一个 Flow 输入变量。

13. 生成文件 — 按照模板结构生成 .messagingChannel-meta.xml 文件。将文件放在用户指定的路径；如果用户未指定，则默认放在项目元数据源路径下的 messagingChannels/ 中。

阶段 3 — 部署并启用

14. 写入渠道 — 传输方式 A：使用 POST 创建，使用 PUT 更新完整文档（最简化的 PUT 会丢失 embeddedConfig）；检查 results[].success，然后重新执行 GET。传输方式 B：

    sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias>
    

15a. 仅限 ASA 路由 — 验证绑定已生效（Queue、Flow、User 可跳过）：

```bash
sf data query -o <org> --json \
  -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<CHANNEL_DEV_NAME>'"
```

两者都必须非空；如果不是，请检查 XML 中是否包含两个处理程序元素，以及部署前 bot 是否处于 Active 状态。

15. 启用渠道 — 写入成功后，启用消息渠道（IsActive 不属于元数据）。传输方式 A：通过 dispatch 执行 sObject 更新 {"IsActive": true}。传输方式 B： bash sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>

阶段 4 — 验证

16. 根据清单验证 — 确认以下验证清单中的所有项目均通过，然后再呈现输出。

17. 报告 — 委派执行：返回合同 §5 结果并停止。独立执行：继续。

18. 呈现输出（独立执行）— 向用户展示生成的文件，并总结已配置的设置，确认启用状态。提供后续步骤：

    • 自动响应 — 询问用户是否要配置 <automatedResponses>（OptOutConfirmation、HelpResponse）。如果是，则生成包含 autoResponseContentType: TextResponse、language 和经过 XML 转义的 response 文本的元素，然后重新部署。

---

规则 / 约束

约束	原因
文件名作为渠道 API 名称	XML 正文中没有 channelPlatformKey 字段
sessionHandlerType 必须与存在的处理程序字段相匹配	设置为 Queue 却填入 sessionHandlerFlow 会导致部署错误
Flow 路由必须同时包含 sessionHandlerFlow 和 sessionHandlerQueue	Queue 是人工升级处理的必需回退选项
User 路由必须同时包含 sessionHandlerUser 和 sessionHandlerQueue	当用户不可用时，Queue 是必需的回退选项
ASA 路由：在 XML 中同时包含 sessionHandlerQueue 和 sessionHandlerAsa	sessionHandlerAsa 在 v67 中为必需字段——若省略，部署会因“Missing required Agentforce Service Agent”而失败；部署本身会绑定 SessionHandlerId，无需 PATCH
在绑定 SessionHandlerId 的元数据部署前，bot 必须处于 Active 状态	如果 bot 未激活，API 会以“Only active Agentforce Service Agents are supported”拒绝请求
masterLabel 最多 40 个字符	平台对渠道标签的限制
文件名必须匹配 ^[a-zA-Z][a-zA-Z0-9_]*$	Metadata API 强制要求的 API 名称格式
allowedFileTypes 是以逗号分隔且不带空格的字符串	不是嵌套列表或数组
keyword 元素各自独立——每个触发词对应一个元素	不是逗号分隔的列表
customParameters 需要 name、masterLabel、parameterDataType 和 externalParameterName	参数不完整时会静默失败
文件扩展名为 .messagingChannel-meta.xml	Metadata API 使用此特定扩展名
不要硬编码文件路径——遵循 sfdx-project.json 中的包目录设置	客户组织会自定义源代码路径
部署后必须启用渠道	渠道默认处于停用状态——启用前消息不会路由
isSynchronousChatEnabled 默认为 false；只有在用户请求时，UnAuth 渠道才能设为 true	对于 Auth 渠道，平台会拒绝请求并提示“You can't enable Session-Based Chat for verified users”

注意事项

问题	解决方法
通道名称与现有通道冲突	检查组织中是否已有同名通道；文件名必须唯一
部署时找不到队列	确保引用的队列存在，且其 queueSobject 类型为 MessagingSession
通道成功部署并激活，但会话开始时小组件显示“Agents are not available. Try again later.”	队列没有 QueueRoutingConfig——部署时不会显示任何提示。检查 SELECT QueueRoutingConfigId FROM Group WHERE Id='<QUEUE_ID>'；如果结果为 null，请按照 queue-resolution.md 第 4 步解决或创建
部署时找不到 Omni-Channel Flow	确保引用的流程存在且已激活，然后再部署通道
ASA bot 引用无效	Bot 必须已发布且处于活动状态；使用 BotDefinition 元数据中的准确开发人员名称
ASA 通道部署失败，并显示“Missing required Agentforce Service Agent”	XML 中缺少 <sessionHandlerAsa>{BotDevName}</sessionHandlerAsa>——在 v67 中这是必需项，并非可选项
ASA 通道已部署，但部署后 SessionHandlerId 为 null	部署时 Bot 未处于活动状态——运行 sf agent activate，确认 BotVersion.Status = Active，然后重新部署
部署时显示“Only active Agentforce Service Agents are supported”	Bot 未激活——部署前运行 sf agent activate
Flow 或 ASA 路由没有备用队列时失败	当 sessionHandlerType 为 Flow 或 AgentforceServiceAgent 时，sessionHandlerQueue 是必需项
JWT 验证不起作用	必须为组织配置已连接应用和证书
未收集自定义参数	每个通道中的 name 必须唯一
部署 <customParameters> 失败：“bad value for restricted picklist field”	parameterDataType 设置成了 String 以外的值。通道自定义参数始终为 String；应在部署级别设置字段的实际类型（Number、Checkbox、下拉列表），而不是在此处设置
移除自定义参数时显示：“can't be deleted as it is referenced elsewhere”	请在部署前检查，而不是部署后检查。 所有在此通道上使用该参数的部署，其预聊天表单都必须先移除该字段并发布（需用户批准）；先在单独的部署中移除该参数的 actionParameterMappings。请参阅 references/channel_settings.md §移除自定义参数
未显示自动回复	使用准确的 type 值（OptOutConfirmation、HelpResponse）；对特殊字符进行 XML 转义
通道已部署，但消息未路由	通道部署后必须激活——默认处于非活动状态
“You can't enable Session-Based Chat for verified users”	对 Auth 通道，将 isSynchronousChatEnabled 设为 false——基于会话的聊天仅对 UnAuth 有效

---

验证清单

通用检查

• 文件名是否符合 ^[a-zA-Z][a-zA-Z0-9_]*$？
• masterLabel 是否不超过 40 个字符？
• messagingChannelType 是否设为 EmbeddedMessaging？

路由检查

• 是否只设置了一个 sessionHandlerType 值（Queue、Flow、User 或 AgentforceServiceAgent）？
• 对于 Queue 路由：XML 中是否包含 sessionHandlerQueue？
• 对于 Flow 路由：XML 中是否包含 sessionHandlerFlow，以及作为备用项的 sessionHandlerQueue？
• 对于 User 路由：XML 中是否包含 sessionHandlerUser，以及作为备用项的 sessionHandlerQueue？
• 对于 ASA 路由：XML 中是否同时包含 sessionHandlerQueue 和 sessionHandlerAsa？
• 对于 ASA 路由：是否已执行步骤 15a？部署后 SessionHandlerId 和 FallbackQueueId 是否均非 null？
• 路由目标是否引用了组织中现有的实体？

用户验证检查

• 如果启用了验证，embeddedConfig.authMode 是否设为 Auth？
• 如果禁用了验证，embeddedConfig.authMode 是否设为 UnAuth？

嵌入式配置检查

• chatAbandonmentTimeout 是否为正整数（分钟）？
• allowedFileTypes 是否为不含空格的逗号分隔字符串？
• maxFileSize 是否为 1-5 MB 之间的值？
• 如果是 UnAuth，是否已设置 anonymousUserJwtExpirationTime（默认值为 360，范围为 60-4320）？
• 如果是 Auth，是否已设置 verifiedUserJwtExpirationTime（默认值为 60，范围为 60-240）？

自动回复检查（仅当用户要求时）

• 所有 type 值是否都使用有效 ID（OptOutConfirmation、HelpResponse）？
• response 文本中的特殊字符是否已进行 XML 转义？

关键词检查

• 是否至少定义了一种 OptOut 关键词类型？
• 关键词是否分别使用 <keyword> 元素，而非逗号分隔？
• 是否为每个关键词块都设置了 language？

激活检查

• 通道是否已成功部署？
• 通道是否在部署后激活（IsActive=true）？

---

输出要求

交付物：

• Messaging Channel 元数据：<source-path>/messagingChannels/<ChannelName>.messagingChannel-meta.xml

文件结构遵循 assets/messaging_channel_template.xml 中的模板。

---

跨技能集成

需求	委派给
创建用于路由的 Omni-Channel Flow	automation-flow-generate 技能
为消息 Agent 创建权限集	platform-permission-set-generate 技能
创建 Embedded Service Deployment	service-digital-engagement-deployment-configure 技能

---

参考文件索引

文件	读取时机
references/onboarding_contract.md	委派模式（context.calledFrom == "service-onboarding"）、组织写入（transport）、模块注册
assets/messaging_channel_template.xml	生成前——将其用作起始结构
references/channel_settings.md	配置默认值以外的通道选项时
scripts/check-api-version.sh	阶段 1——验证组织 API 版本是否达到传入的最低要求（67.0）
scripts/normalize-channel-name.sh	阶段 1——根据通道标签生成文件 API 名称
examples/omni_flow_channel.xml	验证 Omni-Channel Flow 路由的输出
examples/omni_queue_channel.xml	验证 Omni-Channel Queue 路由的输出
examples/asa_agent_channel.xml	验证 Agentforce Service Agent 路由的输出