/service-digital-engagement-deployment-configure

name: service-digital-engagement-deployment-configure
description: "Configures Embedded Messaging Deployments for Messaging for In-App and Web (MIAW). Use when the user needs to create a new embedded messaging deployment from scratch using Connect API with defaults, or update an existing deployment's settings using Metadata API. Produces Connect API request payloads for new deployments and EmbeddedServiceConfig metadata XML for updates. TRIGGER when the user mentions embedded messaging deployment, embedded service deployment, MIAW deployment, messaging widget setup, chat widget configuration, embedded chat deployment, or references a .EmbeddedServiceConfig-meta.xml file. DO NOT TRIGGER when the user is creating a messaging channel (use service-digital-engagement-channel-configure), configuring legacy Live Agent embedded service, or generating the JavaScript code snippet for website embedding."
metadata:
  version: "1.0"
  domains: ["Service"]
  minApiVersion: "67.0"
  relatedSkills:
    - "automation-flow-generate"
    - "platform-permission-set-generate"
    - "service-digital-engagement-channel-configure"
  cliTools:
    - tool: ["python3"]
      semver: ">=3.8"
    - tool: ["sf"]
      semver: ">=2.0.0"

Configuring Embedded Messaging Deployment

Configures `EmbeddedServiceConfig` metadata for Salesforce Messaging for In-App and Web (MIAW). Supports two distinct workflows: creating new deployments via Connect API and updating existing deployments via Metadata API.

Scope

• **In scope**: Creating new Embedded Service Deployments (API, Mobile, Web types) via Connect API; updating existing deployments with forms, branding, channel settings, and features via Metadata API; generating `EmbeddedServiceConfig` XML for updates
• **Out of scope**: Creating the messaging channel itself (use `service-digital-engagement-channel-configure`), generating the website code snippet (offered only as a next step, see `references/code_snippet.md`), creating Experience Sites (Connect API prerequisite for Web type)

---

Entry points and transport

• **Delegated** (`context.calledFrom == "service-onboarding"`): use the approved `values`, ask nothing, and return `failed` naming any missing required key. **Standalone** (no `context`): run Clarifying Questions.
• **Transport A** (primary): headless-360 MCP `dispatch` / `dispatch_readonly` on `/services/data/vXX.0/headless/metadata`. **Transport B**: the `sf` commands below, only where a probe shows Transport A unavailable. Exception: Web create always uses the `sf` CLI (step 17a).

Details: `references/onboarding_contract.md` (§1 entry points, §2 transport, §3 pre-scan, §5 result).

---

Clarifying Questions

Before generating, ask the user if not already clear (standalone only):

• **Create or update?** Are you creating a new deployment or updating an existing one?
• **Deployment type?** API (headless), Mobile (native apps), or Web (browser widget)?
• **Channel name?** What is the `channelPlatformKey` of the messaging channel to associate?
• For **create**: What should the deployment be named?
• For **update**: What features to configure? (pre-chat forms, business hours, T&C, UI toggles)
• For **pre-chat** (if requested): the questions in `references/prechat_forms.md` §Inputs to Gather
• For **update (Web)**: What is the Experience Site name? Branding overrides needed?

---

Required Inputs

Gather or infer before proceeding:

• **Operation**: `create` or `update`
• **Deployment type**: `API`, `Mobile`, or `Web`
• **Deployment name**: Used as `masterLabel`. Derive the API name (`fullName` / `DeveloperName`, Connect `name`) from it: replace each run of characters other than letters and digits with `_`, then trim leading/trailing `_` (`Acme Support Chat` → `Acme_Support_Chat`). The result must match `^[a-zA-Z][a-zA-Z0-9_]*$`. Use the API name for every lookup and write
• **Channel name**: The `channelPlatformKey` of the associated messaging channel

For **update** operations additionally:

• **Site name** (Web only): The Experience Site name (format `ESW_<name>_<timestamp>`)
• **Branding name** (optional): Reference to existing `BrandingSet`
• **Pre-chat form fields** (optional): see `references/prechat_forms.md` §Inputs to Gather
• **Business hours** (optional): Name of existing `BusinessHours` record

Defaults unless specified:

• `isEnabled`: `true`
• `deploymentFeature`: `EmbeddedMessaging`

---

Workflow

All steps are sequential. Do not skip or reorder. Branch based on the operation type.

Phase 1 — Gather Context

1. **Verify org API version** — run `scripts/check-api-version.sh 67.0 <org-alias>` and report any errors it returns. If the script fails (unknown or below-minimum version), STOP all org-write phases. Report the version failure. Only non-org-write operations (local template generation) may continue.

2. **Determine operation** — standalone: ask whether the user wants to create a new deployment or update an existing one. Delegated: taken from `values.operation`, then confirmed by the pre-scan (step 4a).

3. **Collect inputs** — standalone: per Clarifying Questions. Delegated: from `values` (`deploymentName`, `deploymentType`, `channelName` required).

3a. **Probe transport** — read-only `GET` of `EmbeddedServiceConfig` (contract §2).

4. **Read deployment settings reference** — load `references/deployment_settings.md` to understand all available configuration options.

4a. **Pre-scan** — look up the deployment by its derived API name (contract §3): none → `create` (Phase 2A); matches → no write, `already-configured`, skip to Phase 3; differs → `update` (Phase 2B), announce each change (standalone: ask first); linked to a different channel → standalone: ask before repointing, delegated: `failed`. Standalone, deployment exists: offer exactly three choices — no change / override / add to existing.

Phase 2A — Create New Deployment

Use this path when the operation is `create`.

5. **Determine API method by type** — AP