/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"
  minApiVersion: "67.0"
  relatedSkills:
    - "automation-flow-generate"
    - "platform-permission-set-generate"
    - "service-digital-engagement-channel-configure"
  cliTools:
    - 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`), publishing deployments (Connect API post-step), creating Experience Sites (Connect API prerequisite for Web type)

---

Clarifying Questions

Before generating, ask the user if not already clear:

• **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 **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 for `masterLabel` and the API name
• **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): Field names and required status
• **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, generate a `sfdx-project.json` in the metadata output folder with `"sourceApiVersion": "67.0"`.

2. **Determine operation** — ask whether the user wants to create a new deployment or update an existing one.

3. **Collect inputs** — gather deployment name, type, and channel name per Clarifying Questions above.

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

Phase 2A — Create New Deployment

Use this path when the operation is `create`.

5. **Determine API method by type**:

| Deployment Type | Creation Method | Prerequisites | |----------------|-----------------|---------------| | API | Metadata API deploy | Channel must exist | | Mobile | Metadata API deploy | Channel must exist | | Web | Connect API | Channel must exist + Experience Site required |

6. **For API/Mobile types** — read the template `assets/esd_api_mobile_template.xml` and generate the `EmbeddedServiceConfig` XML with:

• `deploymentType` set to `API` or `Mobile`
• `deploymentFeature` set to `EmbeddedMessaging`
• All defaults applied

7. **For Web type** — inform the user that Web deployments require Connect API for initial creation because of a circular dependency between Network and CustomSite. Read `references/connect_api_creation.md` for the Connect API payload and instructions.

8. **Generate output** — produce the `.EmbeddedServiceConfig-meta.xml` file (for API/Mobile) or Connect API instructions (for Web).

9. **Present output and next steps** — show the generated file and summarize what was configured. Recommend as next steps:

• **Publish** the deployment via Connect API to make it live:

     sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>

To obtain the `EMBEDDED_SERVICE_CONFIG_ID`:

     sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>

• **Generate code snippet** for integration — see `references/code_snippet.md`

Phase 2B — Update Existing Deployment (Metadata API)

Use this path when the operation is `update`.

10. **Retrieve the existing deployment** — retrieve the current `EmbeddedServiceConfig` metadata from the org before making changes:

    sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOY