service-digital-engagement-deployment-configure

配置嵌入式消息部署

配置 Salesforce Messaging for In-App and Web（MIAW）的 EmbeddedServiceConfig 元数据。支持两种不同的工作流：通过 Connect API 创建新部署，以及通过 Metadata API 更新现有部署。

范围

• 范围内：通过 Connect API 创建新的 Embedded Service Deployments（API、Mobile、Web 类型）；通过 Metadata API 使用表单、品牌、渠道设置和功能更新现有部署；为更新生成 EmbeddedServiceConfig XML
• 范围外：创建消息渠道本身（请使用 service-digital-engagement-channel-configure）、生成网站代码片段（仅作为后续步骤提供，参见 references/code_snippet.md）、创建 Experience Sites（Web 类型的 Connect API 前置条件）

---

入口点和传输方式

• 委托调用（context.calledFrom == "service-onboarding"）：使用已批准的 values，不提问；如果缺少任何必需键，则返回 failed 并指出缺少的键。独立调用（无 context）：执行澄清问题。
• 传输方式 A（首选）：在 /services/data/vXX.0/headless/metadata 上使用 headless-360 MCP dispatch / dispatch_readonly。传输方式 B：仅当探测显示传输方式 A 不可用时，才使用下方的 sf 命令。例外：创建 Web 始终使用 sf CLI（步骤 17a）。

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

---

澄清问题

生成之前，如果尚未明确，请询问用户（仅限独立调用）：

• 创建还是更新？ 您要创建新的部署，还是更新现有部署？
• 部署类型？ API（无头）、Mobile（原生应用）还是 Web（浏览器小组件）？
• 渠道名称？ 要关联的消息渠道的 channelPlatformKey 是什么？
• 对于创建：部署应使用什么名称？
• 对于更新：要配置哪些功能？（预聊天表单、营业时间、条款和条件、UI 切换项）
• 对于预聊天（如有要求）：references/prechat_forms.md §Inputs to Gather 中的问题
• 对于更新（Web）：Experience Site 的名称是什么？是否需要品牌覆盖设置？

---

必需输入

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

• 操作：create 或 update
• 部署类型：API、Mobile 或 Web
• 部署名称：用作 masterLabel。根据该名称派生 API 名称（fullName / DeveloperName、Connect name）：将每一段非字母数字字符替换为 _，然后去除首尾的 _（Acme Support Chat → Acme_Support_Chat）。结果必须匹配 ^[a-zA-Z][a-zA-Z0-9_]*$。所有查找和写入操作都使用 API 名称
• 渠道名称：关联的消息渠道的 channelPlatformKey

对于更新操作，还需提供：

• 站点名称（仅限 Web）：Experience Site 名称（格式为 ESW_<name>_<timestamp>）
• 品牌名称（可选）：对现有 BrandingSet 的引用
• 预聊天表单字段（可选）：参见 references/prechat_forms.md §Inputs to Gather
• 营业时间（可选）：现有 BusinessHours 记录的名称

除非另有指定，否则使用以下默认值：

• isEnabled：true
• deploymentFeature：EmbeddedMessaging

---

工作流

所有步骤都按顺序执行。不得跳过或重新排序。根据操作类型选择分支。

阶段 1 — 收集上下文

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

2. 确定操作 — 独立模式：询问用户要创建新的部署还是更新现有部署。委派模式：从 values.operation 获取，然后由预扫描（步骤 4a）确认。

3. 收集输入 — 独立模式：按照澄清问题收集。委派模式：从 values 获取（deploymentName、deploymentType、channelName 为必填项）。

3a. 探测传输方式 — 对 EmbeddedServiceConfig 执行只读 GET（参见契约 §2）。

4. 读取部署设置参考文档 — 加载 references/deployment_settings.md，了解所有可用的配置选项。

4a. 预扫描 — 按派生的 API 名称查找部署（契约 §3）：没有匹配项 → create（阶段 2A）；有匹配项 → 不执行写入，标记为 already-configured，跳至阶段 3；配置不同 → update（阶段 2B），说明每项变更（独立模式：先询问）；关联到其他通道 → 独立模式：询问后再更改关联，委派模式：failed。独立模式下，如果部署已存在，则只提供以下三种选择 — 不作更改 / 覆盖 / 添加到现有部署。

阶段 2A — 创建新部署

操作为 create 时使用此路径。

5. 根据类型确定 API 方法 — API/Mobile：通过 Metadata API 部署。Web：使用 Connect API（创建 Experience Site）。所有类型都要求通道已存在。

6. 对于 API/Mobile 类型 — 读取模板 assets/esd_api_mobile_template.xml，并生成 EmbeddedServiceConfig XML，其中包含：

   • 将 deploymentType 设为 API 或 Mobile
   • 将 deploymentFeature 设为 EmbeddedMessaging
   • 应用所有默认值

7. 对于 Web 类型 — 告知用户，由于 Network 和 CustomSite 之间存在循环依赖，首次创建 Web 部署需要使用 Connect API。读取 references/connect_api_creation.md，获取 Connect API 负载和说明。

8. 生成输出 — 生成 .EmbeddedServiceConfig-meta.xml 文件（适用于 API/Mobile）或 Connect API 操作说明（适用于 Web）。

9. 展示输出和后续步骤 — 按照步骤 17 执行。

阶段 2B — 更新现有部署（Metadata API）

当操作为 update 时，使用此路径。

10. 检索现有部署 — 进行更改前，先从组织中获取当前的 EmbeddedServiceConfig。传输方式 A：使用步骤 3a/4a 中 GET 返回的 xmlRep。传输方式 B：

    sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>
    

    将其作为起始结构 — 更新始终需要完整文档（请参阅规则）。如果无法检索，则将 assets/esd_web_update_template.xml 作为备用参考。

11. 应用消息传递渠道设置 — 在 <embeddedServiceMessagingChannel> 中设置 messagingChannel（该渠道的 channelPlatformKey）和 UI 开关（shouldShow*、shouldStartNewLineOnEnter、邀请标志）。包括所有布尔值，即使值为 false 也不例外；完整列表见 references/deployment_settings.md。保留检索到的每个 shouldShow* / shouldStartNewLineOnEnter 值（如果没有检索到，则默认为 false）；只有用户明确要求启用某项功能时才将其设为 true — 切勿根据示例推断。

12. 应用预聊天表单 — 预聊天默认关闭：除非用户要求在对话开始前收集数据，否则省略 <embeddedServiceForms>。如果用户有此要求，请先阅读 references/prechat_forms.md 并遵循其中的说明（字段属性、隐藏字段、ChoiceList、displayNameFormat、停用与移除）。

    • 生成前，针对检索到的渠道，运行其中 §Validating and Remediating Prerequisites 下的检查。渠道修复必须通过 service-digital-engagement-channel-configure 进行；切勿在此处手动编辑渠道。
    • 要合并到基础部署中的差异：examples/esd_web_prechat_fields.xml。

13. 应用品牌自定义（仅限 Web）— 通过 Connect API 创建部署时，会自动创建带有默认值的 BrandingSet。如果用户希望覆盖特定品牌属性（颜色、字体、尺寸），请阅读 references/branding_and_tooling.md，了解通过 Tooling API 更新各项属性的步骤。

14. 应用邀请（仅限 Web）— 将 isInvitationEnabled 设为 true，添加 <embdMsgChannelInvitationConditions>（字段和运算符见 references/deployment_settings.md），并在条件变更时确保 formula（例如 1 AND 2）与条件的 sequence 编号保持同步。

15. 应用其他设置：

    • isTermsAndConditionsEnabled / isTermsAndConditionsRequired — 预聊天中的条款与条件
    • site — Web：保留检索到的值，不作更改（请参阅规则）；API/Mobile：省略

16. 生成文件 — 在用户指定的路径下生成 .EmbeddedServiceConfig-meta.xml 文件；如果用户未指定，则默认生成到项目元数据源路径下的 EmbeddedServiceConfig/。

17. 展示输出和后续步骤 — 展示生成的文件，并总结已配置的内容。建议后续步骤：

    • 发布（Web）— 仅在用户批准后进行，遵循步骤 17c
    • 生成代码片段以供集成 — 请参阅 references/code_snippet.md

阶段 2C — 应用到组织

阶段 2A 和 2B 均会执行，除非预扫描返回 already-configured。独立执行：写入前确认。委托执行：计划审批即为确认；仍须在每次写入时告知用户。

17a. 写入部署 — - Web 创建：通过 sf api request rest 使用 Connect API（参见 references/connect_api_creation.md）——始终使用此方式，而非 dispatch（MCP dispatch 在创建站点期间会因 INTERNAL_ERROR 失败）。 - API/Mobile 创建：传输方式 A：POST EmbeddedServiceConfig（请求体包含 type、fullName、xmlRep）；传输方式 B：sf project deploy start。 - 更新：传输方式 A：对完整文档执行 PUT；传输方式 B：sf project deploy start。 检查 results[].success，不能只看 HTTP 状态。失败时停止并报告出错步骤——不得静默重试。

17b. 重新读取并比对 — 再次 GET 该组件，确认每个预期字段均已写入，且没有内联区块（embeddedServiceMessagingChannel、表单）被删除。

17c. 发布（仅限 Web）——绝不自动发布。 发布会让更改对客户生效；部署操作只会保存草稿。完成 17b 后停止：总结更改内容，提供纯文本 Setup 链接 <instanceUrl>/lightning/setup/EmbeddedServiceDeployments/<EmbeddedServiceConfigId>/view，供用户查看草稿，并询问是否现在发布。只有用户在本轮明确回答是时才发布（原始请求中的“发布”不算）。然后在完整限定的发布路径上执行 dispatch POST；如果返回路径/路由错误，或使用传输方式 B，则运行 references/connect_api_creation.md 中的 sf 发布命令。委托执行：不要发布；返回 published: false。注意：通过 Connect API 创建 Web 部署时会自动发布（isPublishSuccess: true）；创建前须在计划中说明。

阶段 3 — 验证

18. 根据清单验证 — 确认以下验证清单中的所有项目均通过。

19. 报告 — 委托执行：返回契约 §5 规定的结果。独立执行：以通俗语言报告相同结果。

---

规则 / 约束

约束	原因
deploymentType 必须为 API、Mobile 或 Web	平台会拒绝其他值
Web 更新必须包含 site，并将其设置为检索到的原值，不得更改	site（ESW_<name>_<timestamp>）在创建时自动生成；缺失或更改该值会被平台拒绝
embeddedServiceMessagingChannelName 必须引用现有渠道	渠道不存在时，部署会失败
文件扩展名为 .EmbeddedServiceConfig-meta.xml	Metadata API 使用此特定扩展名
不要硬编码文件路径——应遵循 sfdx-project.json 中的包目录	客户组织会自定义源路径
不要在生成的文件或制品中嵌入部署/推送命令	制品应保持可移植；会话期间的写入须在阶段 2C 通过选定的传输方式进行
更新时使用检索到的完整文档，绝不要执行最小化 PUT	更新可能会静默清除省略的内联区块

---

注意事项

问题	解决方法
品牌覆盖设置未应用	创建部署后，使用 Tooling API 更新各项 BrandingSet 属性
预聊天表单、字段、ChoiceList 或 displayNameFormat 问题	参见 references/prechat_forms.md 中的注意事项表
更改未显示在小组件中	发布前，部署只是草稿（步骤 17c）
sf api request rest 失败（“No 'mode' found”、“Nonexistent flag: --url”）	参见 references/connect_api_creation.md §更新后的发布
部署因“required field missing”或“upsert failed null”失败	所有属性均为必填项：embeddedServiceMessagingChannel 中的布尔字段（即使默认值为 false 也要全部包含），以及所有预聊天表单字段属性

---

验证清单

通用检查

• deploymentType 是否为 API、Mobile 或 Web 之一？
• masterLabel 是否已填写且唯一？
• messagingChannel 是否引用了现有渠道？
• deploymentFeature 是否设置为 EmbeddedMessaging？
• isEnabled 是否设置为 true？

Web 类型检查

• site 是否已填写 Experience Site 名称？
• 如果已配置品牌，embeddedServiceBrandingName 是否引用了现有的 BrandingSet？
• 预聊天（如已配置）：references/prechat_forms.md 中的验证清单是否每项都通过？
• 如果 isInvitationEnabled 为 true，formula 是否已填写，且与 <embdMsgChannelInvitationConditions> 中的所有 sequence 编号一致？

API/Mobile 类型检查

• siteUrl 是否为空（无需站点）？
• deploymentType 是否正确设置为 API 或 Mobile？

部署后检查

• Web：是否在发布前停止、提供审核链接，并且仅在用户明确同意后发布？是否提醒用户激活任何已部署的消息组件（Tooling API）？

---

输出要求

交付内容：

• API/Mobile 创建及任何更新：<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml
• Web 创建：Connect API 载荷和说明（无 XML 文件）

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

---

跨技能集成

需求	委派给
创建消息渠道	service-digital-engagement-channel-configure 技能
渠道自定义参数、流程变量映射或 Queue → Omni-Flow 路由	service-digital-engagement-channel-configure 技能（传递检索到的渠道；参见步骤 12）
创建 Omni-Channel 路由流程	automation-flow-generate 技能
为 Agent 创建权限集	platform-permission-set-generate 技能

---

参考文件索引

文件	阅读时机
references/onboarding_contract.md	预扫描（§3，两种模式）；委派模式（context.calledFrom == "service-onboarding"）、组织写入（传输）、模块注册
assets/esd_api_mobile_template.xml、assets/esd_web_update_template.xml	分别在生成 API/Mobile 部署和 Web 更新前
references/deployment_settings.md	配置超出默认值的部署选项时；较少见的注意事项（嵌入式流程、reCAPTCHA、营业时间）
references/prechat_forms.md	每当用户要求预聊天时——输入、字段规则、ChoiceList、displayNameFormat、停用与移除、预聊天注意事项和清单
references/connect_api_creation.md	创建 Web 类型部署时（需要 Connect API）；发布命令和 ID 查询
references/branding_and_tooling.md	用户询问品牌配置时
references/code_snippet.md	用户需要用于其网站的 JavaScript 嵌入代码片段时
scripts/check-api-version.sh	阶段 1——验证组织 API 版本是否达到传入的最低版本（67.0）
examples/esd_api.xml、esd_mobile.xml、esd_web_full.xml、esd_web_prechat_fields.xml	按类型验证输出；预聊天文件是一个表单增量，需合并到 esd_web_full.xml 中