service-de-channel-consent-configure

配置渠道同意

此技能的作用

确保增强型 MessagingChannel 在激活前已配置有效的同意。同意包含两部分，服务器端激活就绪检查门控（MessagingChannelReadinessChecker.isConsentConfiguredForChannel）会同时检查两者：

1. MessagingChannel 上的渠道级字段：

   • ConsentType — 静态枚举：ImplicitOptIn、ExplicitOptIn 或 DoubleOptIn。
   • OptInPrompt — 当最终用户的回复与加入关键词不匹配时发送的消息（ExplicitOptIn/DoubleOptIn 必填；Unified SMS / WhatsApp / RCS 除外，在这些渠道上为可选）。
   • DoubleOptInPrompt — 当回复与双重加入关键词不匹配时发送的消息（DoubleOptIn 必填）。
   • IsRequireDoubleOptIn — 布尔标志；与 ConsentType=DoubleOptIn 一同设为 true。

2. 按语言划分的关键词记录 — 一个或多个 MsgChannelLanguageKeyword 子记录（与 MessagingChannel 为主从关系，键前缀为 3Or）。每条记录包含最终用户发送的关键词（加入、双重加入、退出、帮助、自定义）以及确认回复，每种语言一条记录。关键词字段是逗号分隔的字符串（例如，"STOP,UNSUBSCRIBE,CANCEL"）。

同意设置绝不会对激活检查不起作用。 即使是 ImplicitOptIn，也至少需要一条包含退出关键词和退出确认的 MsgChannelLanguageKeyword 记录。（唯一例外是仅出站渠道，它会自动通过就绪检查。）

同意设置仅适用于受支持消息类型的增强型渠道（PlatformType=Enhanced）。标准渠道不会使用这些字段；此技能只会操作增强型渠道。

适用位置

此技能在增强型渠道设置流程中，介于路由与激活之间。service-de-channel-routing-configure 会设置渠道的 SessionHandler；此技能配置同意；随后 service-de-channel-activate 将渠道设为启用状态。激活就绪检查要求路由和同意两者都已配置，因此请在激活前运行此技能。service-de-headless-channel-configure 编排器会自动按顺序运行这三项；只有在希望单独配置同意时，才直接调用此技能。

参考文件索引

参考文件	加载时机
references/language-keywords.md	创建或更新按语言划分的 MsgChannelLanguageKeyword 记录时——完整字段列表、CSV 关键词语义、创建与更新逻辑，以及 Unified-SMS 帮助/自定义关键词规则。
references/gotchas.md	排查意外结果，或修改此技能前。
references/worked-examples.md	需要参考 ImplicitOptIn、ExplicitOptIn 或 DoubleOptIn 流程示例时。

不要使用此技能的情况

• 渠道不是增强型。 同意字段仅适用于增强型渠道。此技能会确认 PlatformType=Enhanced，否则停止。
• 渠道仅用于出站。 仅出站渠道会自动通过同意就绪检查；无需配置任何内容。
• 渠道尚不存在。 请先运行插入技能；此技能需要真实的 MessagingChannel.Id。

输入（来自调用方）

• {CHANNEL_ID} — 15 或 18 个字符的 MessagingChannel.Id（前缀为 0Mj）。必须已存在且为增强型。
• {CONSENT_TYPE} — 可选；取值之一：ImplicitOptIn | ExplicitOptIn | DoubleOptIn。若省略，此技能会提示输入。
• {LANGUAGE} — 可选；关键词记录的 MasterLanguage（例如 en_US）。若未提供，默认为 en_US。
• {ORG_ALIAS} — 可选；sf CLI 目标组织别名。默认值为 sf config get target-org 返回的内容。

各项关键词、确认消息和提示词的值会在阶段 3–4 交互式收集（如果调用方已预先提供，也可直接使用）。

输出（给调用方）

成功 — 无需更改：

{"ok": true, "noop": true, "consentType": "ImplicitOptIn|ExplicitOptIn|DoubleOptIn", "languageKeywordIds": ["3Or..."], "message": "Consent already configured and activation-ready"}

成功 — 已配置同意：

{"ok": true, "consentType": "ExplicitOptIn", "channelFieldsSet": ["ConsentType","OptInPrompt"],
 "languageKeywordId": "3Or...", "language": "en_US", "created": true|false, "activationReady": true}

前置条件/验证未通过：

{"ok": false, "kind": "not-enhanced", "hint": "consent fields apply to Enhanced channels only; this channel is PlatformType=<x>"}
{"ok": false, "kind": "missing-consent-input", "hint": "<which required keyword/prompt for the chosen ConsentType is missing>"}

失败：

{"ok": false, "kind": "channel-patch-failed", "message": "..."}
{"ok": false, "kind": "keyword-record-failed", "message": "..."}
{"ok": false, "kind": "verify-failed", "hint": "writes returned success but a re-read shows the channel is still not consent-ready"}

---

阶段 1：读取当前同意状态

读取渠道的同意字段和所有现有语言关键词记录。

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/cc-channel.json

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/cc-keywords.json

如果缺少渠道记录——停止，并显示 Error: Channel {CHANNEL_ID} not found — check the id, or run the insertion skill first.

如果 PlatformType != 'Enhanced'——输出 {ok:false, kind:"not-enhanced", ...} 并停止。

**无操作检查：**如果 ConsentType 非空，且现有语言关键词记录已满足该 ConsentType 的就绪矩阵（参见阶段 5），则输出 noop:true 信封并返回。对于已满足激活就绪条件的渠道，不要再次提示或覆盖。

---

阶段 2：选择 ConsentType

如果未提供 {CONSENT_TYPE}，则提示用户（不要自动选择）：

Channel '{developerName}' ({CHANNEL_ID}) — choose a consent model:

  1) ImplicitOptIn  — end users are opted in by default; you only handle opt-OUT (STOP) keywords.
  2) ExplicitOptIn  — end users must send an opt-in keyword before you can message them.
  3) DoubleOptIn    — explicit opt-in plus a second confirming keyword.

Pick [1-3]:

记录 {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 渠道，OptInPrompt 是可选的（就绪条件不要求）；可通过 Enhanced 渠道上的 MessageType IN ('Text','WhatsApp','Rcs') 识别（这是服务端 isUnifiedSMSOrWhatsappOrRCS 的可查询代理字段）。不过，为了提供良好的终端用户体验，仍建议设置此字段。

---

阶段 3：收集渠道级提示词值

仅提示用户填写所选 ConsentType 所要求的字段（参见上方矩阵）。对于 ImplicitOptIn，完全跳过此阶段——它不需要渠道级提示词字段。

对于 ExplicitOptIn / DoubleOptIn：

Opt-in prompt (sent when a reply doesn't match an opt-in keyword):

对于 DoubleOptIn，还需填写：

Double-opt-in prompt (sent when a reply doesn't match a double-opt-in keyword):

去除首尾空格。如果必需的提示词去除空格后为空，则重新提示一次；第二次仍为空时，输出 {ok:false, kind:"missing-consent-input", hint:"..."}。

---

阶段 4：配置按语言区分的关键词记录

收集 {LANGUAGE}（默认值为 en_US）对应的关键词列表和确认回复，然后创建或更新 MsgChannelLanguageKeyword 记录。

加载 references/language-keywords.md 并遵循其中说明——该文件包含完整字段列表、逗号分隔关键词的语义、创建还是更新的判断规则（对相同语言区应复用现有记录，而不是重复创建），以及 Unified-SMS 帮助信息/自定义关键词规则。

每种 ConsentType 的最低要求（同样来自就绪条件契约）：

• ImplicitOptIn：OptOutKeywords（例如 STOP,UNSUBSCRIBE）+ OptOutConfirmation。
• **ExplicitOptIn：**上述字段 + OptInKeywords（例如 START,YES）。
• **DoubleOptIn：**上述字段 + DoubleOptInKeywords（例如 CONFIRM）。

对于基础就绪检查，OptInConfirmation、HelpKeywords/HelpResponse 和 CustomKeywords/CustomResponse 均为可选项（帮助/自定义字段仅在 Unified SMS 上为必填——参见参考文档），但如果用户需要，也应收集这些字段。

---

阶段 5：写入渠道字段和关键词记录

通过一次 PATCH 写入渠道级字段（仅写入所选 ConsentType 要求的字段）。

引号规则（至关重要）：sf data update record --values 会按空格拆分，因此任何包含空格的值都必须在双引号括起的 --values 字符串中用单引号包裹——例如 OptInPrompt='Reply YES to receive messages'。不加引号的 OptInPrompt=Reply YES ... 会导致 Malformed key=value pair 错误（已在 sdb6c 上实时验证）。提示词几乎总是包含空格，因此务必加引号。

# ImplicitOptIn — ConsentType only
sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
  --record-id '{CHANNEL_ID}' --values "ConsentType=ImplicitOptIn" --json > /tmp/cc-patch.json

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

# DoubleOptIn
sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
  --record-id '{CHANNEL_ID}' \
  --values "ConsentType=DoubleOptIn OptInPrompt='{OPT_IN_PROMPT}' DoubleOptInPrompt='{DBL_PROMPT}' IsRequireDoubleOptIn=true" --json > /tmp/cc-patch.json

如果 status !== 0：输出 {ok:false, kind:"channel-patch-failed", message: ...} 并返回。

然后按照 references/language-keywords.md 创建或更新 MsgChannelLanguageKeyword 记录。如果失败：输出 {ok:false, kind:"keyword-record-failed", message: ...}。

---

Stage 6：验证激活就绪状态

重新读取渠道和关键词记录（与 Stage 1 中相同的两个查询）。根据 Stage 2 矩阵中所选 ConsentType 对应的行，确认渠道上以及配置语言的至少一条关键词记录上，每个必填字段现在都不为 null。

如果任何必填字段仍为 null：输出 {ok:false, kind:"verify-failed", hint:"<which requirement is unmet>"}。

否则，输出包含 activationReady: true 的成功封套。

---

Stage 7：向调用方报告

报告 JSON 封套。如果此技能是叶节点（用户直接调用了它），则呈现：

• Success — Consent configured — channel {CHANNEL_ID} is now {CONSENT_TYPE} with a {LANGUAGE} keyword record. Activation-ready.
• Info: Consent already configured — {CONSENT_TYPE}, {N} language record(s). No changes.（无操作路径）
• Warning: This channel is PlatformType={x}, not Enhanced — consent fields don't apply here.（非 Enhanced）
• Warning: Missing required consent input for {CONSENT_TYPE}: {what}. Re-run and provide it.（缺少必需的 Consent 输入）
• Error: {kind}: {message}（其他失败）

---

示例

有关 ImplicitOptIn（仅退订）、ExplicitOptIn 和 DoubleOptIn 路径的运行示例，请参阅 references/worked-examples.md。

---

注意事项

已知注意事项——准确的逐 ConsentType 激活就绪契约（及其来源）、逗号分隔的关键词存储、“ImplicitOptIn 仍需要关键词记录”的陷阱、每种语言仅允许一条记录的唯一性、Unified-SMS 帮助/French-custom 规则，以及 OptInPrompt 对 Unified-SMS/WhatsApp/RCS 的豁免。

排查意外结果时，或修改此技能之前，请加载 references/gotchas.md 并遵循其中的说明。