service-de-channel-settings-configure

チャネル設定の構成

このスキルでできること

既存の Enhanced MessagingChannel（{CHANNEL_ID}で識別）に、あらゆるメッセージタイプの設定を構成します。5つの項目に分かれており、呼び出し元から依頼された項目だけを実行します。

#	項目	書き込み方法	対象
1	同意 — チャネル上のConsentTypeとOptInPrompt／DoubleOptInPrompt、および言語ごとのMsgChannelLanguageKeywordレコード	Data/SObjects API（sf data update/create record）	すべてのEnhancedタイプ
2	自動応答 — <automatedResponses>（初回、エージェント対応開始／終了、オプトインプロンプト／確認、ヘルプ、オプトアウト、非アクティブ／アイドル）	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）したところ、項目2～5のフィールドをData／Connect／Toolingで読み取ろうとすると、すべてINVALID_TYPE／「No such column」エラーになります。これらはMetadata APIでのみ操作できます。

タイプごとの適用範囲は推測ではなく、検証済みです（各タイプの実チャネルを取得して確認）。項目2と3は実際にタイプを問いません。項目4の4つのタイムアウトフィールドはMIAWにのみ存在します。isAgentMessageResetInactivityEnabledのみApple／Facebookにも適用され、SMS／WhatsApp／LINEには非アクティブ状態に関するフィールドはありません。項目5はチャット前設定を使用するMIAWチャネルにのみ存在します。タイプごとの適用範囲に従い、対応していない項目をデプロイしないでください。

使用するタイミング（トリガー）

ユーザーが既存のチャネル設定の構成や変更を求めている場合に、このスキルを実行します。例：

• 「WhatsAppチャネルのオプトアウトキーワード／同意タイプを設定して」
• 「このメッセージングチャネルにダブルオプトイン確認を追加して」
• 「Appleチャネルの初回／エージェント対応開始／ヘルプ自動応答を構成して」
• 「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	ファセット 1：MsgChannelLanguageKeyword レコードの作成／更新 — フィールド一覧、CSV キーワードの仕様、作成と更新の違い、Unified-SMS のヘルプ／カスタムルール。
references/channel-settings-facets.md	ファセット 2～5：Metadata-API の取得→編集→デプロイのフロー、<automatedResponses> の型／形式の全カタログ（12 種類の型、2 種類のコンテンツ形式）、<messagingKeywords>、非アクティブ関連フィールド、型ごとの適用可否。
references/gotchas.md	想定外の結果のトラブルシューティング、またはこのスキルを変更する前。
references/worked-examples.md	ImplicitOptIn／ExplicitOptIn／DoubleOptIn の同意フローの実行例。

このスキルを使用しないケース

• チャネルが Enhanced ではありません。 これらの設定は PlatformType=Enhanced のチャネルにのみ適用されます。ステージ 1 で確認し、該当しない場合は停止します。
• チャネルがまだ存在しません。 先に service-de-channel-create を実行してください。このスキルでは実在する MessagingChannel.Id（接頭辞 0Mj）が必要です。
• 送信専用チャネルで同意を設定しようとしています。 送信専用チャネルは同意準備状況のチェックに自動的に合格するため、ファセット 1 の設定は不要です。

入力（呼び出し元から）

• {CHANNEL_ID} — 15／18 文字の MessagingChannel.Id（接頭辞 0Mj）。チャネルはすでに存在し、Enhanced である必要があります。
• {FACETS} — 任意。設定するファセット（consent、auto-responses、keywords、inactivity、parameters）。省略された場合は、リクエストから推測するか、確認してください。
• {CONSENT_TYPE} — 任意（ファセット 1）。ImplicitOptIn | ExplicitOptIn | DoubleOptIn。
• {LANGUAGE} — 任意。キーワード／応答レコードのロケール（例：en_US）。既定値は en_US です。
• {ORG_ALIAS} — 任意。sf のターゲット組織エイリアス。既定値：sf config get target-org。

ファセット固有の値（プロンプト、キーワードリスト、応答テキスト、タイムアウトの分数）は、ファセットごとに対話形式で収集するか、事前に指定された値を使用します。

出力（呼び出し元へ）

成功：

{"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": "..."}

---

ステージ 1：チャネルを読み取り、ファセットを決定する

チャネルを読み取り、存在することと 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} またはリクエストに基づいて、実行するファセットを決定します。リクエストされた各ファセットについて、型ごとの適用可否（上の表／references/channel-settings-facets.md）を確認します。ファセットがこの MessageType に適用されない場合は、サポートされていないフィールドをデプロイするのではなく、そのファセットについて {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 が null 以外で、かつ既存のキーワードレコードがその 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 では、準備完了の条件として OptInPrompt は任意です（Enhanced の MessageType IN ('Text','WhatsApp','Rcs')）。それでも設定を推奨します。ImplicitOptIn は変更不要になることはありません。オプトアウトキーワードレコードが必要です。

チャネルフィールドを 1 回の 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

終了ステータスが 0 以外の場合は、{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 を読み込み、その手順に従ってください。**取得→編集→デプロイのフロー、12 個の <automatedResponses> の type 値、2 種類のコンテンツ形式（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 件。これは UI でデプロイ後に行う Tooling 専用のマッピングです）。

---

Stage 4: ファセット 4 & 5 — 非アクティブ状態 + チャット前パラメーター（スコープ指定の Metadata API）

要求され、かつこの MessageType に適用できる場合にのみ実行します。

• ファセット 4（非アクティブ状態）： 4 つのタイムアウトフィールド（endUserIdleTimeOut 5～30、endUserIdleAction = Inactivate|End|InactivateAndEnd、endInactiveSessionTimeOut、isAgentMessageResetInactivityEnabled）は、<embeddedConfig> の内側ではなく、そのトップレベルの兄弟要素です。4 つすべてのフィールドに対応するのは MIAW のみです。isAgentMessageResetInactivityEnabled は Apple/Facebook でも有効です。SMS/WhatsApp/LINE には適用されないため、facet-not-applicable を出力します。（262 行のポッドでは endUserIdleTimeOut のみデプロイされます。references/gotchas.md を参照してください。）
• ファセット 5（パラメーター）： <customParameters>（name、masterLabel、externalParameterName、parameterDataType=String、任意の maxLength）と <standardParameters> は、MIAW のチャット前設定のみに適用されます。使用されることはまれです。呼び出し元がチャット前設定を明示的に構成する場合を除き、スキップします。

どちらも、Stage 3 と同じ取得→編集→デプロイのフローを使用します（references/channel-settings-facets.md）。

---

Stage 5: 検証と報告

ファセット 1 では、チャネルとキーワードのレコードを再読み込みし、選択した ConsentType に必要なすべてのフィールドが null ではないことを確認します（チャネルレコードと 1 件以上の言語レコードが必要です）。そうでない場合は {ok:false, kind:"verify-failed", hint:"..."} を返します。メタデータのファセットでは、デプロイの 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}（失敗）