service-digital-engagement-deployment-configure

埋め込みメッセージングのデプロイメントを設定する

Salesforce Messaging for In-App and Web（MIAW）の EmbeddedServiceConfig メタデータを設定します。Connect API を使用して新しいデプロイメントを作成するワークフローと、Metadata API を使用して既存のデプロイメントを更新するワークフローの 2 種類をサポートします。

対象範囲

• 対象：Connect API を使用した新しい Embedded Service Deployments（API、Mobile、Web タイプ）の作成、Metadata API を使用した既存のデプロイメントのフォーム、ブランディング、チャネル設定、機能の更新、更新用の EmbeddedServiceConfig XML の生成
• 対象外：メッセージングチャネル自体の作成（service-digital-engagement-channel-configure を使用してください）、Web サイトのコードスニペットの生成（次のステップとしてのみ提供されます。references/code_snippet.md を参照してください）、Experience Sites の作成（Web タイプの Connect API の前提条件）

---

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

• 委任モード（context.calledFrom == "service-onboarding"）：承認済みの values を使用し、質問はせず、必須キーが不足している場合は、そのキーを明記して failed を返します。スタンドアロンモード（context なし）：Clarifying Questions を実行します。
• トランスポート A（優先）：/services/data/vXX.0/headless/metadata での headless-360 MCP dispatch / dispatch_readonly。トランスポート B：以下の sf コマンド。トランスポート A が利用できないことをプローブで確認できた場合に限り使用します。例外：Web の作成では常に sf CLI を使用します（ステップ 17a）。

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

---

確認事項

生成前に、すでに明らかでない場合はユーザーに質問します（スタンドアロンのみ）。

• 作成または更新ですか？ 新しいデプロイメントを作成しますか、それとも既存のものを更新しますか？
• デプロイメントタイプは？ API（ヘッドレス）、Mobile（ネイティブアプリ）、Web（ブラウザーウィジェット）のどれですか？
• チャネル名は？ 関連付けるメッセージングチャネルの channelPlatformKey は何ですか？
• 作成の場合：デプロイメント名は何にしますか？
• 更新の場合：どの機能を設定しますか？（プレチャットフォーム、営業時間、利用規約、UI の切り替え）
• プレチャットの場合（リクエストされた場合）：references/prechat_forms.md の「収集する入力」§を参照してください。
• 更新（Web）の場合：Experience Site 名は何ですか？ブランディングのオーバーライドは必要ですか？

---

必須入力

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

• 操作：create または update
• デプロイメントタイプ：API、Mobile、または Web
• デプロイメント名：masterLabel として使用します。名前から API 名（fullName / DeveloperName、Connect の name）を導出します。英字および数字以外の文字が連続する箇所をそれぞれ _ に置き換え、先頭と末尾の _ を削除します（Acme Support Chat → Acme_Support_Chat）。結果は ^[a-zA-Z][a-zA-Z0-9_]*$ に一致する必要があります。すべての検索と書き込みには API 名を使用します。
• チャネル名：関連付けるメッセージングチャネルの channelPlatformKey

update 操作の場合は、さらに以下が必要です。

• サイト名（Web のみ）：Experience Site 名（形式：ESW_<name>_<timestamp>）
• ブランディング名（任意）：既存の BrandingSet への参照
• プレチャットフォームのフィールド（任意）：references/prechat_forms.md の「収集する入力」§を参照してください。
• 営業時間（任意）：既存の BusinessHours レコード名

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

• isEnabled：true
• deploymentFeature：EmbeddedMessaging

---

ワークフロー

すべてのステップを順番に実行します。スキップしたり順序を変更したりしないでください。操作タイプに応じて分岐します。

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

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

2. 操作を決定する — 単独実行の場合：新しいデプロイメントを作成するのか、既存のものを更新するのかをユーザーに確認します。委任実行の場合：values.operation から取得し、事前スキャン（ステップ 4a）で確認します。

3. 入力を収集する — 単独実行の場合：「確認事項」に従います。委任実行の場合：values から取得します（deploymentName、deploymentType、channelName は必須）。

3a. トランスポートを調査する — EmbeddedServiceConfig に対して読み取り専用の GET を実行します（契約 §2）。

4. デプロイメント設定リファレンスを読む — references/deployment_settings.md を読み込み、利用可能なすべての設定オプションを確認します。

4a. 事前スキャン — 導出した API 名でデプロイメントを検索します（契約 §3）：該当なし → create（フェーズ 2A）；一致 → 書き込みなしで already-configured とし、フェーズ 3 に進みます；相違あり → update（フェーズ 2B）とし、各変更を通知します（単独実行の場合は事前に確認します）；別のチャネルにリンクされている場合 → 単独実行では付け替えの前に確認し、委任実行では failed とします。単独実行でデプロイメントが存在する場合は、次の 3 つの選択肢のみを提示します — 変更しない／上書き／既存の設定に追加する。

フェーズ 2A — 新しいデプロイメントの作成

操作が create の場合は、この手順を使用します。

5. タイプに応じて API メソッドを決定する — API／モバイル：Metadata API によるデプロイ。Web：Connect API（Experience Site を作成します）。すべてのタイプで、チャネルが存在している必要があります。

6. API／モバイルタイプの場合 — テンプレート assets/esd_api_mobile_template.xml を読み込み、次の内容で EmbeddedServiceConfig XML を生成します。

   • deploymentType を API または Mobile に設定
   • deploymentFeature を EmbeddedMessaging に設定
   • すべてのデフォルト値を適用

7. Web タイプの場合 — Network と CustomSite の間に循環依存関係があるため、Web デプロイメントの初期作成には Connect API が必要であることをユーザーに伝えます。Connect API のペイロードと手順については、references/connect_api_creation.md を読み込みます。

8. 出力を生成する — .EmbeddedServiceConfig-meta.xml ファイル（API／モバイルの場合）、または Connect API の手順（Web の場合）を作成します。

9. 出力と次の手順を提示する — ステップ 17 と同様です。

フェーズ 2B — 既存のデプロイメントを更新する（Metadata API）

操作が update の場合は、この手順を使用します。

10. 既存のデプロイメントを取得する — 変更を加える前に、組織から現在の EmbeddedServiceConfig を取得します。トランスポート A：手順 3a／4a の GET に含まれる xmlRep。トランスポート B：

    sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>
    

    取得したものをベース構造として使用します。更新では常にドキュメント全体が必要です（「ルール」を参照）。取得できない場合は、代替の参考資料として assets/esd_web_update_template.xml を読み込みます。

11. メッセージングチャネルの設定を適用する — <embeddedServiceMessagingChannel> で messagingChannel（チャネルの channelPlatformKey）と UI の切り替え設定（shouldShow*、shouldStartNewLineOnEnter、招待フラグ）を設定します。false の場合も含め、すべてのブール値を指定してください。完全な一覧は references/deployment_settings.md にあります。取得した値（何も取得できなかった場合の既定値は false）を各 shouldShow*／shouldStartNewLineOnEnter に維持します。ユーザーがその機能を明示的に求めた場合に限り、いずれかを true に設定してください。例から推測して設定してはいけません。

12. プレチャットフォームを適用する — プレチャットは既定で OFF です。会話の前にデータを収集するようユーザーが求めない限り、<embeddedServiceForms> は省略します。ユーザーが求めた場合は、まず references/prechat_forms.md を読み、その指示（フィールド属性、非表示フィールド、ChoiceList、displayNameFormat、無効化と削除の違い）に従ってください。

    • 生成する前に、取得したチャネルに対して、その §Validating and Remediating Prerequisites に記載されたチェックを実行します。チャネルの修正には service-digital-engagement-channel-configure を使用してください。この手順でチャネルを直接編集してはいけません。
    • ベースのデプロイメントに組み込む差分：examples/esd_web_prechat_fields.xml

13. ブランディングのカスタマイズを適用する（Web のみ）— Connect API を使用してデプロイメントを作成すると、既定値を含む BrandingSet が自動的に作成されます。特定のブランディングプロパティ（色、フォント、寸法）を上書きする場合は、個々のプロパティを更新するための Tooling API の手順が記載された references/branding_and_tooling.md を読んでください。

14. 招待を適用する（Web のみ）— isInvitationEnabled を true に設定し、<embdMsgChannelInvitationConditions> を追加します（フィールドと演算子は references/deployment_settings.md を参照）。条件が変更された場合は、formula（例：1 AND 2）を条件の sequence 番号と必ず同期させてください。

15. 追加設定を適用する：

    • isTermsAndConditionsEnabled／isTermsAndConditionsRequired — プレチャットの利用規約
    • site — Web：取得した値をそのまま使用します（「ルール」を参照）。API／Mobile では省略します。

16. ファイルを生成する — ユーザーが指定したパスに .EmbeddedServiceConfig-meta.xml ファイルを出力します。指定がない場合は、プロジェクトのメタデータソースパスにある EmbeddedServiceConfig/ を既定の出力先とします。

17. 出力と次の手順を提示する — 生成したファイルを表示し、設定内容を要約します。次の手順として、以下を推奨します：

    • 公開（Web）— 手順 17c に従い、ユーザーの承認後にのみ実行します
    • コードスニペットを生成して統合します — references/code_snippet.md を参照してください

フェーズ 2C — 組織に適用する

事前スキャンで already-configured が返された場合を除き、フェーズ 2A と 2B の両方で実行します。単独実行の場合：書き込み前に確認します。委任実行の場合：計画の承認を確認とみなします。ただし、書き込みのたびに通知します。

17a. デプロイを書き込む — - Web の作成：sf api request rest を使用して Connect API を呼び出します（references/connect_api_creation.md を参照）。常にこれを使用し、dispatch は使いません（MCP の dispatch はサイト作成時に INTERNAL_ERROR で失敗します）。 - API／Mobile の作成：Transport A では POST EmbeddedServiceConfig（本文に type、fullName、xmlRep を含めます）。Transport B では sf project deploy start を実行します。 - 更新：Transport A ではドキュメント全体を PUT します。Transport B では sf project deploy start を実行します。 HTTP ステータスだけでなく、results[].success を確認します。失敗した場合は停止して、該当ステップを報告します。通知なしで再試行してはいけません。

17b. 再読み込みして差分を確認する — コンポーネントをもう一度 GET し、意図したすべてのフィールドが反映され、インラインブロック（embeddedServiceMessagingChannel、フォーム）が失われていないことを確認します。

17c. 公開する（Web のみ）— 自動では行いません。 公開すると変更がお客様に反映されます。デプロイではドラフトが保存されるだけです。17b の後に停止し、変更内容を要約して、ユーザーがドラフトを確認できるよう通常の Setup リンク <instanceUrl>/lightning/setup/EmbeddedServiceDeployments/<EmbeddedServiceConfigId>/view を提示し、今すぐ公開するか尋ねます。そのターンで明確な承認があった場合にのみ公開します（元の依頼に「公開」とあっても承認とはみなしません）。完全修飾の公開パスに対して dispatch で POST します。パス／ルートエラーが返された場合、または Transport B の場合は、references/connect_api_creation.md に記載されている sf 公開コマンドを実行します。委任実行の場合：公開せず、published: false を返します。注：Connect API による Web の作成では自動的に公開されます（isPublishSuccess: true）。作成前に計画でそのことを伝えます。

フェーズ 3 — 検証する

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

19. 報告する — 委任実行の場合：コントラクト §5 の結果を返します。単独実行の場合：同じ結果を平易な言葉で伝えます。

---

ルール／制約

制約	理由
deploymentType は API、Mobile、または Web である必要があります	プラットフォームがそれ以外の値を拒否します
Web の更新には site を含め、取得した値を変更せずに設定する必要があります	Site（ESW_<name>_<timestamp>）は作成時に自動生成されます。値がない場合や変更された場合、プラットフォームが拒否します
embeddedServiceMessagingChannelName は既存のチャネルを参照する必要があります	チャネルが存在しない場合、デプロイは失敗します
ファイル拡張子は .EmbeddedServiceConfig-meta.xml です	Metadata API ではこの特定の拡張子が使われます
ファイルパスをハードコードしないでください — sfdx-project.json のパッケージディレクトリに従ってください	顧客の組織ではソースパスがカスタマイズされています
生成したファイルや成果物にデプロイ／プッシュコマンドを埋め込まないでください	成果物の移植性を保ち、セッション中の書き込みはフェーズ 2C で選択したトランスポートを通じて行います
更新時は取得したドキュメント全体を使用し、最小限の内容で PUT しないでください	省略されたインラインブロックは、更新時に通知なく消去される場合があります

---

注意点

問題	解決方法
ブランディングのオーバーライドが適用されない	デプロイ作成後に、Tooling API を使用して個々の BrandingSet プロパティを更新します
事前チャットフォーム、フィールド、ChoiceList、または displayNameFormat の問題	references/prechat_forms.md の「注意点」テーブルを参照してください
ウィジェットに変更が表示されない	公開されるまでデプロイはドラフトです（ステップ 17c）
sf api request rest が失敗する（"No 'mode' found"、"Nonexistent flag: --url"）	references/connect_api_creation.md §Publishing After Updates を参照してください
"required field missing" または "upsert failed null" でデプロイが失敗する	すべての属性が必須です。embeddedServiceMessagingChannel のブール値フィールド（デフォルトが false でもすべて含めます）と、事前チャットフォームのすべてのフィールド属性が必要です

---

検証チェックリスト

共通チェック

• deploymentType は API、Mobile、Web のいずれかですか？
• masterLabel が入力され、一意ですか？
• messagingChannel は既存のチャネルを参照していますか？
• deploymentFeature は EmbeddedMessaging に設定されていますか？
• isEnabled は true に設定されていますか？

Web タイプのチェック

• site に Experience Site の名前が入力されていますか？
• ブランディングが設定されている場合、embeddedServiceBrandingName は既存の BrandingSet を参照していますか？
• 事前チャット（設定されている場合）：references/prechat_forms.md の検証チェックリストにあるすべての項目に合格していますか？
• isInvitationEnabled が true の場合、formula が入力され、<embdMsgChannelInvitationConditions> 内のすべての sequence 番号と整合していますか？

API／Mobile タイプのチェック

• siteUrl は空ですか（サイトは不要）？
• deploymentType は API または Mobile に正しく設定されていますか？

デプロイ後のチェック

• Web：公開前に停止し、レビュー用リンクを提示して、ユーザーが明示的に承諾した後にのみ公開しましたか？デプロイしたメッセージングコンポーネントを有効化するよう（Tooling API）、ユーザーに念を押しましたか？

---

出力要件

成果物：

• API／Mobile の作成および更新：<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml
• Web の作成：Connect API のペイロードと手順（XML ファイルなし）

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

---

スキル間の連携

必要な作業	委任先
メッセージングチャネルの作成	service-digital-engagement-channel-configure スキル
チャネルのカスタムパラメーター、フロー変数のマッピング、またはキューから Omni-Flow へのルーティング	service-digital-engagement-channel-configure スキル（取得済みのチャネルを渡してください。手順 12 を参照）
Omni-Channel ルーティングフローの作成	automation-flow-generate スキル
エージェント用権限セットの作成	platform-permission-set-generate スキル

---

参照ファイル一覧

ファイル	読み込むタイミング
references/onboarding_contract.md	事前スキャン（§3、両方のモード）；委任モード（context.calledFrom == "service-onboarding"）、組織への書き込み（トランスポート）、モジュール登録
assets/esd_api_mobile_template.xml、assets/esd_web_update_template.xml	それぞれ API／Mobile デプロイと Web 更新を生成する前
references/deployment_settings.md	デフォルト以外のデプロイオプションを設定する場合；あまり一般的でない注意点（埋め込みフロー、reCAPTCHA、営業時間）
references/prechat_forms.md	事前チャットがリクエストされた場合は必ず参照 — 入力、フィールドルール、ChoiceList、displayNameFormat、無効化と削除の違い、事前チャットに関する注意点とチェックリスト
references/connect_api_creation.md	Web タイプのデプロイを作成する場合（Connect API が必要）；公開コマンドと ID クエリ
references/branding_and_tooling.md	ユーザーがブランディング設定について尋ねた場合
references/code_snippet.md	ユーザーが Web サイト用の JavaScript 埋め込みコードスニペットを希望する場合
scripts/check-api-version.sh	フェーズ 1 — 組織の API バージョンが指定された最小バージョン（67.0）を満たしていることを確認
examples/esd_api.xml、esd_mobile.xml、esd_web_full.xml、esd_web_prechat_fields.xml	タイプごとに出力を検証する場合；事前チャット用ファイルは esd_web_full.xml に組み込むフォーム差分です