/service-digital-engagement-messaging-site-integrate

name: service-digital-engagement-messaging-site-integrate
description: "Integrates a Messaging for In-App and Web (MIAW) Embedded Messaging chat widget into an Experience Cloud site by patching the site's LWR or Aura page bundle, deploying, publishing, and verifying guest access. Use when the user wants to embed messaging on an Experience site, add a chat widget to a community, place the Embedded Messaging component on an LWR or Aura page, wire an embedded service deployment to a site, references the retrieved bundle artifacts (`content.json`, `homeGuestLayout.json`, or a `*.site-meta.xml` file), or automates the retrieve/patch-JSON/deploy/publish flow instead of clicking through Experience Builder. DO NOT TRIGGER when creating the messaging channel (use service-digital-engagement-channel-configure), when creating or updating the EmbeddedServiceConfig deployment (use service-digital-engagement-deployment-configure), or when generating a standalone JavaScript snippet for a non-Experience website."
metadata:
  version: "1.0"
  minApiVersion: "62.0"
  relatedSkills:
    - "experience-lwr-site-generate"
    - "service-digital-engagement-channel-configure"
    - "service-digital-engagement-deployment-configure"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["jq"]
      semver: ">=1.6.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

Embed Messaging Widget on an Experience Cloud Site

Wires an existing Embedded Messaging (MIAW) deployment onto an Experience Cloud site by retrieving the site's bundle (LWR `DigitalExperienceBundle` or Aura `ExperienceBundle`), patching the home page JSON to place the `experience_messaging:embeddedMessaging` component, staging the bundle into the local project, deploying it, publishing the site, and verifying guest access.

The operation is idempotent: if the component is already present it is updated in place (its `id` is preserved), so re-running with different ESD coordinates cleanly updates.

Scope

• **In scope**: Detecting LWR vs Aura bundle type; scaffolding missing LWR template routes required by the site template (e.g. `too-many-requests`); patching the home-page JSON to insert or update the Embedded Messaging component; staging the bundle into `force-app`; async deploy with polling; resolving the `Network.Name` and publishing the site; guest-URL smoke test; manual Experience Builder fallback with a deep link.
• **Out of scope**: Creating the `EmbeddedServiceConfig` (Embedded Service Deployment) itself — use `service-digital-engagement-deployment-configure`; creating the `MessagingChannel` — use `service-digital-engagement-channel-configure`; creating the Experience Cloud site itself — use `experience-lwr-site-generate`; generating a standalone JS snippet for a non-Experience website.

---

Clarifying Questions

Before executing, ask the user if not already clear:

• **Site name?** The `DeveloperName` of the Experience Cloud site (the metadata folder name under `digitalExperiences/site/<siteName>/` or `experiences/<siteName>/`).
• **Deployment coordinates?** The `deploymentName` (Embedded Service Deployment `DeveloperName`), the `scrtUrl`, and the `siteEndpoint` (Experience site base URL). All three come from the published `EmbeddedServiceConfig` — obtain from `service-digital-engagement-deployment-configure` output if not provided.
• **Target org alias?** For the `sf` commands.
• **URL path prefix?** The site's `UrlPathPrefix` (needed to resolve `Network.Name` for publish and to hit the guest URL for verification).

---

Required Inputs

Gather or infer before proceeding:

• **Site name** — `DeveloperName` of the site
• **Deployment name** — `DeveloperName` of the `EmbeddedServiceConfig`
• **scrtUrl** — SCRT2 endpoint URL from the deployment
• **siteEndpoint** — Base URL of the Experience site
• **Target org alias**
• **URL path prefix** — Site's public URL path segment (e.g. `esw-site`)

Defaults applied to the component's attributes when writing:

• `isExpSiteAuthMode`: `false`
• `hideChatButtonOnLoad`: `"Default"`
• `clientVersion`: `"WebV1"`

---

Workflow

Steps are sequential. If any automated step fails, proceed to the manual fallback (Phase 6) and do not claim the widget is "live" until either the guest-URL smoke test returns `200` or the user confirms manual publish.

Phase 1 — Detect Bundle Type

1. **Retrieve both candidate bundles** into `<retrieve-dir>`. The script only performs a deterministic path check, so the retrieve calls must run first:

   sf project retrieve start --metadata "DigitalExperienceBundle:site/<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
   sf project retrieve start --metadata "ExperienceBundle:<siteName>" \
     --target-org <org-alias> --target-metadata-dir <retrieve-dir>

Either call may return "no metadata found" — that is expected; the missing bundle simply means the site is the other type.

2. **Run `scripts/detect_bundle_type.sh <retrieve-dir> <siteName>`.** It emits exactly one token to stdout:

• `LWR` → the LWR marker file exists (`digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json`). Go to Phase 2.
• `AURA` → the Aura marker file exists (`experiences/<siteName>/views/homeGuestLayout.json`). Go to Phase 3.
• `UNKNOWN` (exit code 1) → neither marker exists. Skip to the manual fallback in Phase 6.

Read `references/bundle_detection.md` for retrieval command shapes and troubleshooting.

Phase 2 — Patch the LWR Bundle

3. **Scaffold any missing LWR template routes** (commonly `too-many-requests`) before patching — missing routes fail the deploy. Route+view scaffolding is owned by `experience-lwr-site-generate` (see its `configure-content-route.md`, `configure-content-view.md`, and `handle-component-and-region-ids.md`). Delegate to that skill for the actual scaffold; this skill only supplies the messaging-specific context (which route th