service-de-channel-consent-configure

チャネルの同意を設定する

このスキルの機能

Enhanced MessagingChannel を有効化する前に、有効な同意が設定されていることを確認します。同意には 2 つの要素があり、どちらもサーバー側の有効化準備チェック（MessagingChannelReadinessChecker.isConsentConfiguredForChannel）で確認されます。

1. MessagingChannel のチャネルレベルの項目：

   • ConsentType — 静的な列挙値：ImplicitOptIn、ExplicitOptIn、または DoubleOptIn。
   • OptInPrompt — エンドユーザーの返信がオプトインキーワードと一致しない場合に送信されるメッセージ（Unified SMS／WhatsApp／RCS では任意ですが、それ以外は ExplicitOptIn／DoubleOptIn で必須です）。
   • DoubleOptInPrompt — 返信がダブルオプトインキーワードと一致しない場合に送信されるメッセージ（DoubleOptIn で必須です）。
   • IsRequireDoubleOptIn — ブール値フラグ。ConsentType=DoubleOptIn と併せて true に設定します。

2. 言語ごとのキーワードレコード — 1 つ以上の MsgChannelLanguageKeyword 子レコード（MessagingChannel との主従関係、キーのプレフィックスは 3Or）。各レコードには、エンドユーザーが送信するキーワード（オプトイン、ダブルオプトイン、オプトアウト、ヘルプ、カスタム）と確認応答が1 つの言語分保存されます。キーワード項目はカンマ区切りの文字列です（例："STOP,UNSUBSCRIBE,CANCEL"）。

同意設定が有効化に不要になることはありません。 ImplicitOptIn でも、オプトアウトキーワードとオプトアウト確認応答を含む MsgChannelLanguageKeyword が少なくとも 1 つ必要です。（唯一の例外はアウトバウンド専用チャネルで、この場合は準備チェックに自動的に合格します。）

同意設定は、サポートされているメッセージタイプのEnhancedチャネル（PlatformType=Enhanced）にのみ適用されます。Standard チャネルではこれらの項目は使用されません。このスキルが対象とするのは Enhanced チャネルのみです。

このスキルの位置付け

このスキルは、Enhanced チャネルのセットアップパイプラインでルーティングと有効化の間に実行します。service-de-channel-routing-configure がチャネルの SessionHandler を設定し、このスキルが同意を設定した後、service-de-channel-activate がチャネルを有効化します。有効化の準備チェックでは、ルーティングと同意の両方が必要となるため、有効化する前にこのスキルを実行してください。service-de-headless-channel-configure オーケストレーターは 3 つすべてを自動的に順番に実行します。同意だけを個別に設定したい場合に限り、このスキルを直接呼び出してください。

参照ファイル一覧

参照ファイル	読み込むタイミング
references/language-keywords.md	言語ごとの MsgChannelLanguageKeyword レコードを作成または更新する場合。全項目の一覧、CSV キーワードの仕様、作成と更新の判定ロジック、Unified SMS のヘルプ／カスタムキーワードのルールが記載されています。
references/gotchas.md	想定外の結果をトラブルシューティングする場合、またはこのスキルを変更する前。
references/worked-examples.md	ImplicitOptIn、ExplicitOptIn、または DoubleOptIn の手順例を参照したい場合。

このスキルを使用しない場合

• チャネルが Enhanced ではありません。 同意項目は Enhanced チャネルにのみ適用されます。このスキルは PlatformType=Enhanced を確認し、該当しない場合は停止します。
• チャネルがアウトバウンド専用です。 アウトバウンド専用チャネルは同意の準備チェックに自動的に合格するため、設定は不要です。
• チャネルがまだ存在しません。 先に挿入スキルを実行してください。このスキルには実在する MessagingChannel.Id が必要です。

入力（呼び出し元から）

• {CHANNEL_ID} — 15 文字または 18 文字の MessagingChannel.Id（プレフィックスは 0Mj）。既に存在し、Enhanced である必要があります。
• {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 が null ではなく、既存の言語キーワードレコードがその 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):

空白を削除します。必須のプロンプトが空白削除後に空の場合は、もう一度プロンプトを表示します。2 回目も空の場合は、{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：チャネルフィールドとキーワードレコードを書き込む

チャネルレベルのフィールドを 1 回の 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: ...} を出力します。

---

ステージ 6：有効化の準備状況を確認する

チャンネルとキーワードのレコードを両方再読み込みします（ステージ 1 と同じ 2 つのクエリ）。ステージ 2 のマトリックスで選択した ConsentType の行に従い、設定した言語のチャンネルと少なくとも 1 つのキーワードレコードの両方で、必須フィールドがすべて null ではないことを確認します。

必須フィールドにまだ null がある場合は、{ok:false, kind:"verify-failed", hint:"<which requirement is unmet>"} を出力します。

それ以外の場合は、activationReady: true を含む成功エンベロープを出力します。

---

ステージ 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.（必須の同意入力が不足している場合）
• Error: {kind}: {message}（その他のエラー）

---

実行例

ImplicitOptIn（オプトアウトのみ）、ExplicitOptIn、DoubleOptIn の各パスの実行例については、references/worked-examples.md を参照してください。

---

注意点

既知の注意点として、ConsentType ごとの正確な有効化準備状況の要件（およびその出典）、カンマ区切りのキーワード保存、「ImplicitOptIn でもキーワードレコードが必要」という落とし穴、言語ごとに 1 レコードのみという一意性、Unified-SMS のヘルプ／フランス語カスタムルール、OptInPrompt における Unified-SMS／WhatsApp／RCS の適用除外があります。

予期しない結果のトラブルシューティングを行う場合や、このスキルを変更する前には、references/gotchas.md を読み込み、その指示に従ってください。