service-de-channel-settings-configure

配置渠道设置

此技能的作用

为已存在的 Enhanced MessagingChannel（由 {CHANNEL_ID} 标识）配置任意消息类型的设置。此技能分为五个方面；只需执行调用方要求的部分。

#	方面	写入方式	适用范围
1	同意 — 渠道上的 ConsentType + OptInPrompt/DoubleOptInPrompt，以及每种语言对应的 MsgChannelLanguageKeyword 记录	Data/SObjects API（sf data update/create record）	所有 Enhanced 类型
2	自动回复 — <automatedResponses>（初始、Agent 参与/结束、选择加入提示/确认、帮助、选择退出、不活跃/空闲）	Metadata API 部署	所有 Enhanced 类型
3	消息关键字 — <messagingKeywords>（每种语言的 OptIn/OptOut/Help 关键字组）	Metadata API 部署	所有 Enhanced 类型
4	会话不活跃设置 — endUserIdleTimeOut、endUserIdleAction、endInactiveSessionTimeOut、isAgentMessageResetInactivityEnabled	Metadata API 部署	仅限 MIAW（重置标志也适用于 Apple/Facebook）
5	聊天前参数 — <customParameters> / <standardParameters>	Metadata API 部署	仅限 MIAW 聊天前设置（较少见）

此技能使用多种写入方式。 同意（方面 1）通过 Data API 写入实时记录。方面 2–5 仅存在于渠道的元数据中，需检索渠道的 .messagingChannel-meta.xml、进行编辑，然后重新部署。已在 sdb6 上进行实时验证（2026-09）：通过 Data/Connect/Tooling 读取方面 2–5 的字段都会失败，并返回 INVALID_TYPE/"No such column"；这些字段只能通过 Metadata API 读取。

各类型的适用范围已经过验证，并非假定（基于对每种类型的真实渠道进行实时检索）。方面 2 和 3 确实与类型无关。方面 4 的四个超时字段仅出现在 MIAW 上；只有 isAgentMessageResetInactivityEnabled 也适用于 Apple/Facebook，SMS/WhatsApp/LINE 均不包含不活跃字段。方面 5 仅出现在使用聊天前设置的 MIAW 渠道上。请按类型限定范围——不要部署某种类型不支持的方面。

适用场景（触发条件）

当用户想要配置或更改已存在渠道的设置时，触发此技能，例如：

• “设置我的 WhatsApp 渠道的选择退出关键字/同意类型”
• “为此消息渠道添加双重选择加入确认”
• “配置我的 Apple 渠道的初始/Agent 参与/帮助自动回复”
• “为我的 Text 渠道添加 OptIn/OptOut/Help 关键字”
• “设置我的 MIAW 渠道的会话不活跃超时/空闲操作”
• “更改渠道 0MjXXXXXXXXXXXX 上的自动回复”

不要触发——请转交给其他技能：

• 从元数据 XML 文件创建或部署新渠道（MIAW / EmbeddedMessaging） → service-digital-engagement-channel-configure。该技能会从 XML 创建 Embedded Messaging 渠道；此技能仅配置已存在的渠道（需要实时 {CHANNEL_ID}，前缀为 0Mj）。
• 插入任何类型的新渠道 → service-de-channel-create。
• 设置路由/队列/SessionHandler → service-de-channel-routing-configure。
• 将渠道切换为上线状态 → service-de-channel-activate。

在流程中的位置

此技能属于 Enhanced 渠道无头流程：service-de-channel-create → service-de-channel-routing-configure → 此技能 → service-de-channel-activate。激活就绪检查要求路由和同意设置均已完成，因此至少要在激活前执行方面 1。service-de-headless-channel-configure 编排器会自动按顺序执行整个流程；若要单独配置设置，请直接调用此技能。有关 MIAW 专用的“从 XML 创建渠道”流程，请参阅同级技能 service-digital-engagement-channel-configure。

参考文件索引

参考文件	何时加载
references/language-keywords.md	Facet 1：创建/更新 MsgChannelLanguageKeyword 记录——字段列表、CSV 关键词语义、创建与更新的区别、Unified-SMS 帮助/自定义规则。
references/channel-settings-facets.md	Facet 2–5：Metadata-API 的检索→编辑→部署流程、完整的 <automatedResponses> 类型/结构目录（12 种类型、2 种内容结构）、<messagingKeywords>、不活跃字段，以及各类型的适用性。
references/gotchas.md	排查意外结果，或修改此技能之前。
references/worked-examples.md	ImplicitOptIn/ExplicitOptIn/DoubleOptIn 同意流程的参考运行示例。

何时不要使用此技能

• 渠道不是 Enhanced 渠道。 这些设置仅适用于 PlatformType=Enhanced 的渠道。Stage 1 会确认这一点，否则将停止。
• 渠道尚不存在。 请先运行 service-de-channel-create；此技能需要真实的 MessagingChannel.Id（前缀为 0Mj）。
• 你正在为仅出站渠道配置同意设置。 仅出站渠道会自动通过同意就绪检查——Facet 1 无需配置。

输入（来自调用方）

• {CHANNEL_ID} — 一个 15/18 位的 MessagingChannel.Id（前缀为 0Mj）。必须已存在且为 Enhanced 渠道。
• {FACETS} — 可选；要配置的 Facet（consent、auto-responses、keywords、inactivity、parameters）。如果省略，则根据请求推断或询问。
• {CONSENT_TYPE} — 可选（Facet 1）；ImplicitOptIn | ExplicitOptIn | DoubleOptIn。
• {LANGUAGE} — 可选；关键词/响应记录所用的区域设置（例如 en_US）。默认为 en_US。
• {ORG_ALIAS} — 可选；sf 目标组织别名。默认值：sf config get target-org。

各 Facet 所需的值（提示词、关键词列表、响应文本、超时分钟数）会按 Facet 逐项交互式收集，也可以接受预先提供的值。

输出（发送给调用方）

成功：

{"ok": true, "channelId": "0Mj...", "messageType": "WhatsApp",
 "facetsConfigured": ["consent","auto-responses"],
 "consent": {"consentType": "ExplicitOptIn", "languageKeywordId": "3Or...", "activationReady": true},
 "metadataDeploy": {"status": "Succeeded", "facets": ["auto-responses","keywords"]}}

无需更改 / 前置条件不满足 / 失败：

{"ok": true, "noop": true, "message": "Requested settings already configured"}
{"ok": false, "kind": "not-enhanced", "hint": "settings apply to Enhanced channels only; this channel is PlatformType=<x>"}
{"ok": false, "kind": "facet-not-applicable", "hint": "<facet> is not supported on <messageType> channels"}
{"ok": false, "kind": "channel-patch-failed" | "keyword-record-failed" | "metadata-deploy-failed" | "verify-failed", "message": "..."}

---

Stage 1：读取渠道并确定 Facet

读取渠道；确认其存在且为 Enhanced 渠道；记录 MessageType（用于判断各类型的适用性）。

sf data query --target-org '{ORG_ALIAS}' \
  --query "SELECT Id, DeveloperName, PlatformType, MessageType, MessagingPlatformKey, ConsentType, OptInPrompt, DoubleOptInPrompt, IsRequireDoubleOptIn FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
  --json > /tmp/cs-channel.json

• 找不到渠道 → 停止：Error: Channel {CHANNEL_ID} not found — check the id, or run service-de-channel-create first.
• PlatformType != 'Enhanced' → 输出 {ok:false, kind:"not-enhanced", ...} 并停止。

根据 {FACETS} 或请求确定要运行的 Facet。对每个请求的 Facet，检查其是否适用于相应类型（见上表 / references/channel-settings-facets.md）；如果某个 Facet 不适用于此 MessageType，则针对该 Facet 输出 {ok:false, kind:"facet-not-applicable", ...}（或跳过并注明），而不是部署不受支持的字段。

sf CLI 运行较慢，但并未故障。 对此组织的调用通常需要 2–4 分钟（CLI 启动开销大，加上往返耗时较长）。运行每条 sf 命令时请设置充足的超时时间；返回较慢是正常现象，不代表命令卡住。

---

阶段 2：方面 1 — 同意（Data API）

当请求 consent 时运行（并且始终在激活之前运行）。读取现有关键字记录：

sf data query --target-org '{ORG_ALIAS}' \
  --query "SELECT Id, MasterLanguage, OptInKeywords, DoubleOptInKeywords, OptInConfirmation, OptOutKeywords, OptOutConfirmation, HelpKeywords, HelpResponse, CustomKeywords, CustomResponse FROM MsgChannelLanguageKeyword WHERE MessagingChannelId = '{CHANNEL_ID}'" \
  --json > /tmp/cs-keywords.json

空操作检查： 如果 ConsentType 非空，且现有关键字记录已满足该 ConsentType 的就绪矩阵，则不要覆盖——此方面已可用于激活。

选择 ConsentType（若缺少 {CONSENT_TYPE}，则提示用户——不要自动选择），然后满足以下契约（服务器端激活就绪的确切规则——来源见 references/gotchas.md）：

ConsentType	MessagingChannel 字段	MsgChannelLanguageKeyword（≥1 条记录）
ImplicitOptIn	（无必填项）	OptOutKeywords + OptOutConfirmation
ExplicitOptIn	OptInPrompt¹	以上内容 + OptInKeywords
DoubleOptIn	OptInPrompt¹ + DoubleOptInPrompt + IsRequireDoubleOptIn=true	以上内容 + DoubleOptInKeywords

¹ 对 Unified SMS / WhatsApp / RCS（Enhanced 上的 MessageType IN ('Text','WhatsApp','Rcs')），就绪检查不要求 OptInPrompt；但仍建议设置。ImplicitOptIn 绝不会是空操作——仍需要一条退订关键字记录。

在一次 PATCH 中写入渠道字段，然后按照 references/language-keywords.md 创建或更新语言关键字记录。

引号规则（至关重要）： sf data ... --values 会按空格拆分，因此每个多词值都必须在双引号字符串内部用单引号括起来：OptInPrompt='Reply YES to receive messages'。不加引号会导致 Malformed key=value pair。

# ExplicitOptIn example
sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
  --record-id '{CHANNEL_ID}' --values "ConsentType=ExplicitOptIn OptInPrompt='{OPT_IN_PROMPT}'" --json > /tmp/cs-patch.json

状态码非零时：输出 {ok:false, kind:"channel-patch-failed"|"keyword-record-failed", message: ...}。然后重新读取以验证（阶段 5）。

WhatsApp 富内容在服务器端不接受 ExplicitOptIn——显示该消息，不要重试（见 references/gotchas.md）。

---

阶段 3：方面 2 和 3 — 自动响应 + Messaging 关键字（Metadata API）

当请求 auto-responses 和/或 keywords 时运行。这些设置与类型无关（适用于所有 Enhanced 类型）。加载 references/channel-settings-facets.md 并遵循其中的说明——其中包含 retrieve→edit→deploy 流程、12 个 <automatedResponses> 类型值、两种内容结构（TextResponse 与 MessageDefinition）、EndUserIdleResponse 的 <responseTimeoutInMins> 规则、XML 转义，以及 <messagingKeywords> 中的 OptIn/OptOut/Help 分组。

概要：

1. 将渠道元数据检索到临时 sfdx 项目中（sf project retrieve start -m MessagingChannel:{DeveloperName}）。
2. 在检索到的 .messagingChannel-meta.xml 中编辑 <automatedResponses> / <messagingKeywords> 区块（按 <type> / <keywordType>+<language> 添加或替换；对响应文本进行 XML 转义）。
3. 将其部署回去（sf project deploy start -m MessagingChannel:{DeveloperName}）。
4. 部署失败时：{ok:false, kind:"metadata-deploy-failed", message: <componentFailures>}。

绝不输出 <actionParameterMappings>（扫描 191 个渠道时出现 0 次——这是仅限 Tooling 的映射，在部署后通过 UI 完成）。

---

阶段 4：Facet 4 和 5 — 不活跃设置 + 聊天前参数（Metadata API，限定范围）

仅在收到请求且适用于此 MessageType 时运行：

• Facet 4（不活跃设置）：四个超时字段（endUserIdleTimeOut 5–30、endUserIdleAction = Inactivate|End|InactivateAndEnd、endInactiveSessionTimeOut、isAgentMessageResetInactivityEnabled）是 <embeddedConfig> 的同级顶层字段，不在其中。完整的四个字段 → 仅限 MIAW；isAgentMessageResetInactivityEnabled 也适用于 Apple/Facebook；不适用于 SMS/WhatsApp/LINE → 输出 facet-not-applicable。（在 262 行的 Pod 上，只有 endUserIdleTimeOut 会部署 — 参见 references/gotchas.md。）
• Facet 5（参数）：<customParameters>（name、masterLabel、externalParameterName、parameterDataType=String、可选的 maxLength）和 <standardParameters> — 仅限 MIAW 聊天前设置，很少使用。除非调用方明确配置聊天前设置，否则跳过。

两者均使用与阶段 3 相同的检索→编辑→部署流程（references/channel-settings-facets.md）。

---

阶段 5：验证并报告

对于 facet 1，重新读取渠道和关键字记录，并确认所选 ConsentType 的每个必需字段均非 null（渠道和 ≥1 条语言记录）；否则输出 {ok:false, kind:"verify-failed", hint:"..."}。对于元数据 facet，确认部署 status 为 Succeeded，然后重新检索渠道元数据，确认已编辑的 <automatedResponses> / <messagingKeywords> / 不活跃设置 / 参数块均存在；如果部署报告 Succeeded，但重新检索的块缺失，则输出 {ok:false, kind:"verify-failed", hint:"..."}。

输出 JSON 信封。如果直接调用（叶节点），则呈现简短摘要：

• Success — configured {facets} on channel {CHANNEL_ID} ({MessageType}).（通过同意验证时，添加 Activation-ready.）
• Info: requested settings already configured — no changes.（无操作）
• Warning: {facet} is not supported on {MessageType} channels — skipped.（facet-not-applicable）
• Warning: this channel is PlatformType={x}, not Enhanced — these settings don't apply.（not-enhanced）
• Error: {kind}: {message}（失败）