service-digital-engagement-channel-configure

拡張チャットチャネルの設定

Salesforce Messaging for In-App and Web（MIAW）用の MessagingChannel メタデータ XML を作成します。このスキルでは、ルーティング、ユーザー検証、プレチャット、自動応答の設定がすべて整った拡張チャットチャネルを生成し、Metadata API でデプロイできる状態にします。

対象範囲

• 対象：Omni-Channel Flow ルーティング、Omni-Channel Queue ルーティング、または Agentforce Service Agent（ASA）ルーティングを使用する MessagingChannel メタデータの作成、ユーザー検証の有効化、すべてのチャネル設定（プレチャットフォーム、自動応答、同意キーワード、ファイル添付、カスタムパラメーター）の設定
• 対象外：参照される Omni-Channel Flow／Queue 定義の作成（automation-flow-generate を使用）、Embedded Service Deployment の作成（別のメタデータ型です。service-digital-engagement-deployment-configure を使用）、メッセージング用権限セットの作成（platform-permission-set-generate を使用）、Embedded Service Code Snippet の設定

---

エントリーポイントとトランスポート

• 委任モード（context.calledFrom == "service-onboarding"）：承認済みの values を使用し、質問はせず、不足している必須キーがあればその名前を挙げて failed を返します。スタンドアロンモード（context なし）：確認の質問を行います。
• トランスポート A（優先）：/headless/metadata 上の headless-360 MCP dispatch／dispatch_readonly。トランスポート B：以下の sf コマンド。トランスポート A が利用できないことをプローブで確認した場合に限り使用します。

詳細は references/onboarding_contract.md（§1 エントリーポイント、§2 トランスポート、§3 事前スキャン、§5 結果）を参照してください。

---

確認の質問

生成する前に、まだ明確でない場合はユーザーに質問してください（スタンドアロンのみ）。

• チャネル名／表示ラベルは何ですか？（masterLabel とファイル名に使用します）
• ルーティングの種類は何ですか？（Omni-Channel Flow、Omni-Channel Queue、User、Agentforce Service Agent のいずれか）
• ルーティング先は何ですか？（Flow API 名、Queue の開発者名、User ID、または ASA ボット名）
• Flow、User、ASA のルーティングの場合、フォールバックキュー名は何ですか？
• ユーザー検証を有効にしますか？（このスキルではデフォルトで true です）
• 必須のプレチャットフォーム項目はありますか？ある場合は、項目と型を教えてください。

---

必須入力

続行する前に、以下を収集または推定します。

• チャネル名：masterLabel とファイル名（<Name>.messagingChannel-meta.xml）に使用します
• ルーティングの種類：Queue、Flow、User、AgentforceServiceAgent のいずれか
• ルーティング先：Queue、Flow、User、または ASA ボットの開発者名
• フォールバックキュー（Flow、User、ASA）：エスカレーション用フォールバックキューの開発者名
• ユーザー検証：JWT ベースのID検証を必須にするかどうか（デフォルト：true）

指定がない場合のデフォルト：

• messagingChannelType：EmbeddedMessaging
• authMode：Auth
• chatAbandonmentTimeout：5（分）
• endUserIdleTimeOut：5（分）
• isAttachmentUploadEnabled：true
• maxFileSize：5（MB）
• allowedFileTypes：bmp,csv,doc,docx,gif,jpg,pdf,png,tiff,txt,xls,xml
• anonymousUserJwtExpirationTime：360（分。UnAuth に必須。範囲は 60～4320）
• verifiedUserJwtExpirationTime：60（分。Auth に必須。範囲は 60～240）
• isAbandonedChatsEnabled：false
• isSaveTranscriptEnabled：false
• isFallbackMessageEnabled：false
• isEstimatedWaitTimeEnabled：false
• isFileAttachmentExtUnrestricted：false
• isQueuePositionEnabled：false
• isSynchronousChatEnabled：false
• isVoiceModeEnabled：false

---

ワークフロー

すべての手順を順番どおりに実行します。省略したり、順序を入れ替えたりしないでください。

フェーズ 1 — コンテキストの収集

1. 組織の API バージョンを確認する — scripts/check-api-version.sh 67.0 <org-alias> を実行し、返されたエラーを報告します。スクリプトが失敗した場合は、メタデータ出力フォルダーに "sourceApiVersion": "67.0" を含む sfdx-project.json を生成します。

2. 入力を収集する — 単独実行の場合：Clarifying Questions に従います。委任実行の場合：values から取得します。その後、MessagingChannel の読み取り専用 GET でトランスポートを確認します（契約 §2）。

3. ファイル名を決定する — scripts/normalize-channel-name.sh "<LABEL>" を実行し、返されたエラーを提示します。

3a. 事前スキャン — 手順 3 の名前で MessagingChannel を GET します（契約 §3）：一致なし → 作成します。一致し、有効 → 書き込みは行わず、already-configured として Phase 4 に進みます。一致するが無効 → 有効化のみ行います（手順 15）。相違あり → 変更点をそれぞれ通知してから、ドキュメント全体を書き込みます（単独実行の場合：先に確認します）。

4. ルーティング先の存在を確認する — 手順 3a が already-configured または有効化のみで終了した場合はスキップします。再実行時にキューを作成しないためです。組織をクエリし、参照されているルーティング先の存在を確認します。

   • Queue の場合：sf data query --query "SELECT Id, DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='<QUEUE_NAME>'" --target-org <org-alias>
   • Flow の場合：sf data query --query "SELECT Id, ApiName FROM FlowDefinitionView WHERE ApiName='<FLOW_NAME>' AND IsActive=true" --target-org <org-alias>
   • User の場合：sf data query --query "SELECT Id, Username FROM User WHERE Id='<USER_ID>' AND IsActive=true" --target-org <org-alias>
   • ASA の場合：sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName='<BOT_NAME>'" --target-org <org-alias>
   • フォールバックキューの存在も確認します（Flow、User、ASA のルーティングで必須です）。

   ルーティング先が見つからない場合：単独実行の場合 — ユーザーに通知し、作成するかどうか確認します。委任実行の場合 — 見つからないルーティング先を示して failed を返します。作成してはいけません。単独実行のユーザーが作成を確認した場合：

   • Queue の場合：MessagingSession を queueSobject のタイプとして指定した .queue-meta.xml を生成し、チャネルより先にデプロイします。**新しいキューには QueueRoutingConfig が必要です。ない場合、チャネルのデプロイと有効化が成功しても、セッションは「Agents are not available. Try again later」というエラーで失敗します。**キューのデプロイ直後に、service-agentforce-channel-configure の references/queue-resolution.md の手順 4 に従って解決または作成します。後回しにしてはいけません。
   • Flow/User/ASA の場合：フロー、ユーザー、ボットは別途作成する必要があることをユーザーに伝えます（このスキルの対象外です）。

5. チャネル設定リファレンスを読む — references/channel_settings.md を読み込み、利用可能な設定オプションと有効な値をすべて確認します。

フェーズ 2 — メタデータの生成

6. メタデータテンプレートを読み込む — assets/messaging_channel_template.xml を基本構造として読み込みます。

7. ルーティング設定を適用する — sessionHandlerType と対応するハンドラーフィールドを設定します。

   ルーティングタイプ	sessionHandlerType	必須フィールド
   Omni-Channel Queue	Queue	sessionHandlerQueue
   Omni-Channel Flow	Flow	sessionHandlerFlow + sessionHandlerQueue（フォールバック）
   User	User	sessionHandlerUser + sessionHandlerQueue（フォールバック）
   Agentforce Service Agent	AgentforceServiceAgent	sessionHandlerQueue（フォールバック）+ sessionHandlerAsa（ボットの開発者名 — 必須。下記の v67 に関する注記を参照）

   v67 に関する注記 — <sessionHandlerAsa> は必須です（省略すると「Missing required Agentforce Service Agent」で失敗します）。デプロイ時に SessionHandlerId がバインドされるため、PATCH は不要です。ボットはあらかじめ Active にしておく必要があります。sf agent activate -o <org> --api-name <BotDevName> を実行し、BotVersion.Status = Active を確認してください。

8. ユーザー検証を適用する — 有効にする場合は、embeddedConfig.authMode を Auth に設定し、<messagingAuthorizations> を含めます。有効にしない場合は、embeddedConfig.authMode を UnAuth に設定し、<messagingAuthorizations> を省略します。

9. 埋め込み設定を構成する — <embeddedConfig> に以下を設定します。

   • allowedFileTypes — カンマ区切りのファイル拡張子（スペースなし）
   • anonymousUserJwtExpirationTime — JWT の有効期限（分単位。UnAuth で必須）
   • verifiedUserJwtExpirationTime — JWT の有効期限（分単位。Auth で必須）
   • chatAbandonmentTimeout — 放棄された会話をクリーンアップするまでの時間（分）
   • isAbandonedChatsEnabled — 放棄されたチャットの検出を有効にする
   • isAttachmentUploadEnabled — ファイルのアップロードを有効にする
   • isEstimatedWaitTimeEnabled — 推定待ち時間を表示する
   • isFallbackMessageEnabled — エージェントが対応できない場合のフォールバックを有効にする
   • isFileAttachmentExtUnrestricted — 任意のファイル拡張子を許可する
   • isSaveTranscriptEnabled — 会話のトランスクリプトを保存する
   • maxFileSize — 添付ファイルの最大サイズ（MB）

10. メッセージングキーワードを構成する — <messagingKeywords> 要素を生成します。

    • OptOut タイプに、個別の <keyword> 要素として次を設定します：cancel、end、quit、stop、stopall、unsubscribe
    • Help タイプに、<keyword> として help を設定します

11. 標準パラメーターを適用する — ユーザーが標準の事前チャットフィールドを必要とする場合は、parameterType を含む <standardParameters> 要素を生成します。チャネルが Flow ベースのルーティングを使用し、ユーザーがフロー変数のマッピングを指定した場合は、actionParameterName を含む <actionParameterMappings> を追加して、各パラメーターをフローの入力変数にマッピングします。

12. カスタムパラメーターを適用する — ユーザーが事前チャットデータの収集を必要とする場合は、name、masterLabel、parameterDataType、externalParameterName、maxLength を含む <customParameters> 要素を生成します。parameterDataType は必ず String に設定してください。チャネルではほかの値を受け付けません（フィールドの実際の型（Checkbox／Number／ドロップダウンなど）はここではなく、デプロイレベルで formFieldType を使用して設定します）。チャネルが Flow ベースのルーティングを使用し、ユーザーがフロー変数のマッピングを指定した場合は、actionParameterName を含む <actionParameterMappings> を追加して、各パラメーターをフローの入力変数にマッピングします。

13. ファイルを生成する — テンプレートの構造に従って .messagingChannel-meta.xml ファイルを作成します。ユーザーが指定したパスに配置するか、指定がない場合はプロジェクトのメタデータソースパス内の messagingChannels/ に配置します。

フェーズ 3 — デプロイと有効化

14. チャネルを書き込む — トランスポート A：作成には POST、更新にはドキュメント全体を PUT します（最小限の PUT では embeddedConfig が失われます）。results[].success を確認してから、再度 GET します。トランスポート B：

    sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias>
    

15a. ASA ルーティングのみ — バインドが反映されたことを確認する（Queue、Flow、User の場合はスキップ）：

```bash
sf data query -o <org> --json \
  -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<CHANNEL_DEV_NAME>'"
```

両方とも null 以外である必要があります。そうでない場合は、両方のハンドラー要素が XML に含まれていたこと、およびデプロイ前にボットが有効だったことを確認します。

15. チャネルを有効化する — 書き込みの成功後、メッセージングチャネルを有効化します（IsActive はメタデータに含まれません）。トランスポート A：dispatch を通じて sObject を {"IsActive": true} に更新します。トランスポート B： bash sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>

フェーズ 4 — 検証

16. チェックリストに照らして確認する — 出力を提示する前に、以下の検証チェックリストのすべての項目に合格していることを確認します。

17. 結果を報告する — 委任されている場合：契約 §5 の結果を返して終了します。単独で実行している場合：続行します。

18. 出力を提示する（単独実行の場合） — 生成したファイルと、設定した内容の概要をユーザーに示し、有効化の状態を確認します。次の手順を提案します：

    • 自動応答 — ユーザーに <automatedResponses>（OptOutConfirmation、HelpResponse）を設定するか尋ねます。設定する場合は、autoResponseContentType: TextResponse、language、XML エスケープした response テキストを含む要素を生成してから、再デプロイします。

---

ルール／制約

制約	理由
ファイル名がチャネルの API 名になります	XML 本文に channelPlatformKey フィールドがないため
sessionHandlerType は、存在するハンドラーフィールドと一致させる必要があります	Queue を設定して sessionHandlerFlow を指定すると、デプロイエラーになります
Flow ルーティングには sessionHandlerFlow と sessionHandlerQueue の両方が必要です	人へのエスカレーションには Queue が必須のフォールバックとなります
User ルーティングには sessionHandlerUser と sessionHandlerQueue の両方が必要です	ユーザーが対応できない場合、Queue が必須のフォールバックとなります
ASA ルーティング：XML に sessionHandlerQueue と sessionHandlerAsa の両方を含めます	v67 では sessionHandlerAsa が必須です。省略すると「Missing required Agentforce Service Agent」でデプロイに失敗します。デプロイ自体が SessionHandlerId をバインドするため、PATCH は不要です
SessionHandlerId をバインドするメタデータのデプロイ前に、ボットを有効化しておく必要があります	ボットが無効の場合、API は「Only active Agentforce Service Agents are supported」で拒否します
masterLabel は最大 40 文字です	チャネルラベルのプラットフォーム上の上限です
ファイル名は ^[a-zA-Z][a-zA-Z0-9_]*$ に一致する必要があります	Metadata API によって API 名の形式が強制されます
allowedFileTypes はスペースを含まない、カンマ区切りの文字列です	ネストされたリストや配列ではありません
keyword 要素は個別に指定します。トリガー語ごとに 1 つ必要です	カンマ区切りのリストではありません
customParameters には name、masterLabel、parameterDataType、externalParameterName が必要です	パラメーターが不完全でも、エラーが通知されずに失敗します
ファイル拡張子は .messagingChannel-meta.xml です	Metadata API はこの特定の拡張子を使用します
ファイルパスをハードコードせず、sfdx-project.json のパッケージディレクトリに従います	顧客の組織ではソースパスがカスタマイズされている場合があります
デプロイ後にチャネルを有効化する必要があります	チャネルはデフォルトで無効になっており、有効化するまでメッセージはルーティングされません
isSynchronousChatEnabled のデフォルト値は false です。ユーザーからの依頼がある場合に限り、UnAuth チャネルで true にできます	Auth チャネルでは、プラットフォームが「You can't enable Session-Based Chat for verified users」で拒否します

---

注意事項

問題	解決方法
チャネル名が既存のチャネルと重複している	組織内に既存のチャネルがないか確認してください。ファイル名は一意である必要があります
デプロイ時にキューが見つからない	参照先のキューが存在し、queueSobject 型として MessagingSession が設定されていることを確認してください
チャネルのデプロイと有効化は正常に完了するが、セッション開始時にウィジェットに「エージェントを利用できません。後でもう一度お試しください。」と表示される	キューに QueueRoutingConfig が設定されていません。これはデプロイ時に通知されません。SELECT QueueRoutingConfigId FROM Group WHERE Id='<QUEUE_ID>' を実行して確認してください。null の場合は、queue-resolution.md のステップ 4 に従って設定を解決または作成してください
デプロイ時に Omni-Channel Flow が見つからない	チャネルをデプロイする前に、参照先のフローが存在し、有効になっていることを確認してください
ASA ボットの参照が無効	ボットは公開済みで、有効になっている必要があります。BotDefinition メタデータの正確な開発者名を使用してください
ASA チャネルのデプロイが「必須の Agentforce Service Agent がありません」というエラーで失敗する	XML に <sessionHandlerAsa>{BotDevName}</sessionHandlerAsa> がありません。v67 では必須であり、省略できません
ASA チャネルのデプロイ後、SessionHandlerId が null になっている	デプロイ時にボットが有効ではありませんでした。sf agent activate を実行し、BotVersion.Status = Active を確認してから再デプロイしてください
デプロイ時に「アクティブな Agentforce Service Agent のみがサポートされています」と表示される	ボットが無効です。デプロイ前に sf agent activate を実行してください
フォールバックキューがないため、フローまたは ASA のルーティングに失敗する	sessionHandlerType が Flow または AgentforceServiceAgent の場合、sessionHandlerQueue は必須です
JWT 検証が機能しない	接続アプリと証明書を組織用に設定する必要があります
カスタムパラメーターが収集されない	name はチャネルごとに一意である必要があります
<customParameters> のデプロイが「制限付き選択リスト項目の値が不正です」というエラーで失敗する	parameterDataType に String 以外の値が設定されています。チャネルのカスタムパラメーターは常に String です。フィールドの実際の型（Number、Checkbox、ドロップダウン）は、ここではなくデプロイレベルで設定してください
カスタムパラメーターの削除時に「別の場所で参照されているため削除できません」と表示される	デプロイ後ではなく、デプロイ前に確認してください。 このチャネルで、そのパラメーターを使用するプレチャットフォームが含まれるデプロイでは、対象フィールドを先に削除して公開する必要があります（ユーザーの承認が必要です）。まず別のデプロイで、そのパラメーターの actionParameterMappings を削除してください。references/channel_settings.md §カスタムパラメーターの削除を参照してください
自動応答が表示されない	正確な type 値（OptOutConfirmation、HelpResponse）を使用し、特殊文字を XML エスケープしてください
チャネルはデプロイされたが、メッセージがルーティングされない	デプロイ後にチャネルを有効化する必要があります。デフォルトでは無効です
「検証済みユーザーにセッションベースのチャットを有効にすることはできません」と表示される	Auth チャネルでは isSynchronousChatEnabled を false に設定してください。セッションベースのチャットが有効なのは UnAuth のみです

---

検証チェックリスト

共通チェック

• ファイル名は ^[a-zA-Z][a-zA-Z0-9_]*$ に一致していますか？
• masterLabel は 40 文字以内ですか？
• messagingChannelType は EmbeddedMessaging に設定されていますか？

ルーティングチェック

• sessionHandlerType の値は 1 つだけ設定されていますか（Queue、Flow、User、または AgentforceServiceAgent）？
• Queue ルーティングの場合、XML に sessionHandlerQueue が含まれていますか？
• Flow ルーティングの場合、XML に sessionHandlerFlow とフォールバック用の sessionHandlerQueue が含まれていますか？
• User ルーティングの場合、XML に sessionHandlerUser とフォールバック用の sessionHandlerQueue が含まれていますか？
• ASA ルーティングの場合、XML に sessionHandlerQueue と sessionHandlerAsa の両方が含まれていますか？
• ASA ルーティングの場合、ステップ 15a を実行しましたか？デプロイ後、SessionHandlerId と FallbackQueueId は null 以外ですか？
• ルーティング先は、組織内に存在するエンティティを参照していますか？

ユーザー検証チェック

• 検証が有効な場合、embeddedConfig.authMode は Auth に設定されていますか？
• 検証が無効な場合、embeddedConfig.authMode は UnAuth に設定されていますか？

埋め込み設定の確認

• chatAbandonmentTimeout は正の整数（分単位）ですか？
• allowedFileTypes はスペースを含まないカンマ区切りの文字列ですか？
• maxFileSize は1～5 MBの値ですか？
• UnAuth の場合、anonymousUserJwtExpirationTime は設定されていますか（デフォルトは360、範囲は60～4320）？
• Auth の場合、verifiedUserJwtExpirationTime は設定されていますか（デフォルトは60、範囲は60～240）？

自動応答の確認（ユーザーから依頼された場合のみ）

• すべての type の値に有効な ID（OptOutConfirmation、HelpResponse）が使用されていますか？
• response テキスト内の特殊文字は XML エスケープされていますか？

キーワードの確認

• 少なくとも1つの OptOut キーワードタイプが定義されていますか？
• キーワードは個別の <keyword> 要素になっていますか（カンマ区切りではありませんか）？
• 各キーワードブロックに language が設定されていますか？

有効化の確認

• チャネルは正常にデプロイされましたか？
• デプロイ後にチャネルは有効化されましたか（IsActive=true）？

---

出力要件

成果物：

• Messaging Channel メタデータ：<source-path>/messagingChannels/<ChannelName>.messagingChannel-meta.xml

ファイル構造は assets/messaging_channel_template.xml のテンプレートに従います。

---

スキル間連携

必要な作業	委任先
ルーティング用の Omni-Channel Flow の作成	automation-flow-generate スキル
メッセージングエージェント用の権限セットの作成	platform-permission-set-generate スキル
Embedded Service Deployment の作成	service-digital-engagement-deployment-configure スキル

---

参照ファイル一覧

ファイル	読み取るタイミング
references/onboarding_contract.md	委任モード（context.calledFrom == "service-onboarding"）、組織への書き込み（トランスポート）、モジュール登録
assets/messaging_channel_template.xml	生成前 — 開始構造として使用
references/channel_settings.md	デフォルト以外のチャネルオプションを設定する場合
scripts/check-api-version.sh	フェーズ1 — 組織の API バージョンが指定された最小値（67.0）を満たしていることを確認
scripts/normalize-channel-name.sh	フェーズ1 — チャネルラベルからファイルの API 名を導出
examples/omni_flow_channel.xml	Omni-Channel Flow ルーティングの出力を確認する場合
examples/omni_queue_channel.xml	Omni-Channel Queue ルーティングの出力を確認する場合
examples/asa_agent_channel.xml	Agentforce Service Agent ルーティングの出力を確認する場合