@salesforce/afv-skills 1.65.1 → 1.67.0

package/skills/service-digital-engagement-deployment-configure/assets/esd_web_update_template.xml

@@ -3,25 +3,98 @@
     <areGuestUsersAllowed>false</areGuestUsersAllowed>
 
     <!-- Branding (optional — reference an existing BrandingSet) -->
-    <!-- <branding>{BRANDING_SET_NAME}</branding> -->
+    <!-- To set branding, add a branding element whose value is {BRANDING_SET_NAME} -->
 
     <deploymentFeature>EmbeddedMessaging</deploymentFeature>
     <deploymentType>{Web|API|Mobile}</deploymentType>
 
+    <!-- Pre-Chat Form (OPTIONAL) -->
+    <!-- Pre-chat is OFF by default. DELETE this entire block if the deployment
+         collects no pre-chat data (that is the correct default).
+         Each formField must resolve to a standard parameter (_-prefixed) OR an
+         existing customParameter on the channel below. ChoiceList fields also need
+         a choiceList record that ALREADY EXISTS in the org (created in Setup —
+         it is not a deployable artifact). -->
+    <embeddedServiceForms>
+        <displayContext>Conversation</displayContext>
+
+        <!-- 1. Standard field -->
+        <embeddedServiceFormFields>
+            <displayOrder>0</displayOrder>
+            <formField>_FirstName</formField>
+            <formFieldType>Text</formFieldType>
+            <isHidden>false</isHidden>
+            <isRequired>true</isRequired>
+            <messagingChannelParameterType>Standard</messagingChannelParameterType>
+        </embeddedServiceFormFields>
+
+        <!-- 2. Visible custom text field (formField = an existing channel customParameter name) -->
+        <embeddedServiceFormFields>
+            <displayOrder>1</displayOrder>
+            <formField>{CUSTOM_PARAM_NAME}</formField>
+            <formFieldType>Text</formFieldType>
+            <isHidden>false</isHidden>
+            <isRequired>false</isRequired>
+            <messagingChannelParameterType>Custom</messagingChannelParameterType>
+        </embeddedServiceFormFields>
+
+        <!-- 3. Checkbox custom field -->
+        <embeddedServiceFormFields>
+            <displayOrder>2</displayOrder>
+            <formField>{CHECKBOX_PARAM_NAME}</formField>
+            <formFieldType>Checkbox</formFieldType>
+            <isHidden>false</isHidden>
+            <isRequired>false</isRequired>
+            <messagingChannelParameterType>Custom</messagingChannelParameterType>
+        </embeddedServiceFormFields>
+
+        <!-- 4. ChoiceList (dropdown) field — choiceList DeveloperName must already exist in the org -->
+        <embeddedServiceFormFields>
+            <choiceList>{CHOICELIST_DEVELOPER_NAME}</choiceList>
+            <displayOrder>3</displayOrder>
+            <formField>{CHOICELIST_PARAM_NAME}</formField>
+            <formFieldType>ChoiceList</formFieldType>
+            <isHidden>false</isHidden>
+            <isRequired>true</isRequired>
+            <messagingChannelParameterType>Custom</messagingChannelParameterType>
+        </embeddedServiceFormFields>
+
+        <!-- 5. Hidden / pre-populated field — displayOrder=-1, value captured but never shown -->
+        <embeddedServiceFormFields>
+            <displayOrder>-1</displayOrder>
+            <formField>{HIDDEN_PARAM_NAME}</formField>
+            <formFieldType>Text</formFieldType>
+            <isHidden>true</isHidden>
+            <isRequired>false</isRequired>
+            <messagingChannelParameterType>Custom</messagingChannelParameterType>
+        </embeddedServiceFormFields>
+
+        <isActive>true</isActive>
+    </embeddedServiceForms>
+
     <!-- Messaging Channel Configuration -->
     <embeddedServiceMessagingChannel>
+        <!-- Display name shown when pre-chat is enabled (OPTIONAL — delete this line if unused).
+             EXACTLY 3 brace tokens; leave unused slots EMPTY, e.g. {_firstName}{_lastName}{}.
+             Each non-empty token = a pre-chat field's externalParameterName (Channel Variable Name),
+             NOT the formField value. Standard: _firstName / _lastName / _email / _subject
+             (lowercase-first — the _FirstName formField spelling is REJECTED).
+             Custom: the channel param's externalParameterName (usually its name, e.g. CompanyName). -->
+        <displayNameFormat>{DISPLAY_NAME_FORMAT}</displayNameFormat>
         <isChatInvitationCustomizable>{true|false}</isChatInvitationCustomizable>
         <isEnabled>true</isEnabled>
         <isInvitationEnabled>{true|false}</isInvitationEnabled>
         <isSendInvtAllowedAfterAccept>{true|false}</isSendInvtAllowedAfterAccept>
         <isSendInvtAllowedAfterReject>{true|false}</isSendInvtAllowedAfterReject>
         <messagingChannel>{CHANNEL_PLATFORM_KEY}</messagingChannel>
-        <shouldShowAgentforceTagline>{true|false}</shouldShowAgentforceTagline>
-        <shouldShowDeliveryReceipts>{true|false}</shouldShowDeliveryReceipts>
-        <shouldShowEmojiSelection>{true|false}</shouldShowEmojiSelection>
-        <shouldShowReadReceipts>{true|false}</shouldShowReadReceipts>
-        <shouldShowTypingIndicators>{true|false}</shouldShowTypingIndicators>
-        <shouldStartNewLineOnEnter>{true|false}</shouldStartNewLineOnEnter>
+        <!-- shouldShow* / shouldStartNewLineOnEnter below: keep the retrieved value on update; with nothing retrieved, leave at the default false.
+             Set true only if the user explicitly asks for that feature. -->
+        <shouldShowAgentforceTagline>false</shouldShowAgentforceTagline>
+        <shouldShowDeliveryReceipts>false</shouldShowDeliveryReceipts>
+        <shouldShowEmojiSelection>false</shouldShowEmojiSelection>
+        <shouldShowReadReceipts>false</shouldShowReadReceipts>
+        <shouldShowTypingIndicators>false</shouldShowTypingIndicators>
+        <shouldStartNewLineOnEnter>false</shouldStartNewLineOnEnter>
     </embeddedServiceMessagingChannel>
 
     <isEnabled>true</isEnabled>
@@ -29,5 +102,7 @@
     <isTermsAndConditionsRequired>{true|false}</isTermsAndConditionsRequired>
     <masterLabel>{DEPLOYMENT_NAME}</masterLabel>
     <shouldHideAuthDialog>false</shouldHideAuthDialog>
-    <!-- Do NOT update <site> — auto-generated at creation, must not be modified -->
+    <!-- Web only: copy the site value UNCHANGED from the retrieved config (required for Web, can never be
+         changed). Omit this element entirely for Mobile/API deployments. -->
+    <site>{EXISTING_SITE_NAME}</site>
 </EmbeddedServiceConfig>

package/skills/service-digital-engagement-deployment-configure/examples/esd_web_prechat_fields.xml

@@ -0,0 +1,74 @@
+<!--
+Pre-chat forms delta. This is NOT a standalone deployable file; graft it onto a base
+Web deployment (see esd_web_full.xml for everything else: branding, site, etc.). Two pieces:
+  1. embeddedServiceForms goes directly under EmbeddedServiceConfig.
+  2. displayNameFormat goes INSIDE the existing embeddedServiceMessagingChannel (not
+     directly under EmbeddedServiceConfig). Merge it into that element if the base file
+     already has one; do not add a second embeddedServiceMessagingChannel.
+-->
+<embeddedServiceForms>
+    <displayContext>Conversation</displayContext>
+    <embeddedServiceFormFields>
+        <displayOrder>0</displayOrder>
+        <formField>_FirstName</formField>
+        <formFieldType>Text</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>true</isRequired>
+        <messagingChannelParameterType>Standard</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <displayOrder>1</displayOrder>
+        <formField>_LastName</formField>
+        <formFieldType>Text</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>true</isRequired>
+        <messagingChannelParameterType>Standard</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <displayOrder>2</displayOrder>
+        <formField>_Email</formField>
+        <formFieldType>Email</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>true</isRequired>
+        <messagingChannelParameterType>Standard</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <displayOrder>3</displayOrder>
+        <formField>CompanyName</formField>
+        <formFieldType>Text</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>false</isRequired>
+        <messagingChannelParameterType>Custom</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <displayOrder>4</displayOrder>
+        <formField>NewsletterOptIn</formField>
+        <formFieldType>Checkbox</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>false</isRequired>
+        <messagingChannelParameterType>Custom</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <choiceList>Customer_Inquiry_Type</choiceList>
+        <displayOrder>5</displayOrder>
+        <formField>InquiryType</formField>
+        <formFieldType>ChoiceList</formFieldType>
+        <isHidden>false</isHidden>
+        <isRequired>true</isRequired>
+        <messagingChannelParameterType>Custom</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <embeddedServiceFormFields>
+        <displayOrder>-1</displayOrder>
+        <formField>utm_campaign</formField>
+        <formFieldType>Text</formFieldType>
+        <isHidden>true</isHidden>
+        <isRequired>false</isRequired>
+        <messagingChannelParameterType>Custom</messagingChannelParameterType>
+    </embeddedServiceFormFields>
+    <isActive>true</isActive>
+</embeddedServiceForms>
+<!-- displayNameFormat tokens use each field's externalParameterName (e.g. _firstName),
+     NOT the formField spelling above (e.g. _FirstName). -->
+<embeddedServiceMessagingChannel>
+    <displayNameFormat>{_firstName}{_lastName}{}</displayNameFormat>
+</embeddedServiceMessagingChannel>

package/skills/service-digital-engagement-deployment-configure/references/connect_api_creation.md

@@ -15,9 +15,11 @@ Web-type Embedded Service Deployments cannot be created via Metadata API due to
 ## Connect API Endpoint
 
 ```text
-POST /connect/embeddedmessaging/deployment/setup
+POST /services/data/vXX.0/connect/embeddedmessaging/deployment/setup
 ```
 
+Always use the fully-qualified path (minimum `v67.0`). A bare `/connect/...` path is not routed.
+
 ### Request Body (Web)
 
 ```json
@@ -55,10 +57,13 @@ POST /connect/embeddedmessaging/deployment/setup
 
 ### Using Salesforce CLI (Web)
 
+Always create Web deployments with the CLI. The same call through the headless-360 MCP `dispatch` fails with an
+`INTERNAL_ERROR` server error during site creation.
+
 ```bash
 sf api request rest \
+  "/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
   --method POST \
-  --url "/connect/embeddedmessaging/deployment/setup" \
   --body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"Web","clientVersion":"WebV2","hostDomain":"<DOMAIN>","messagingChannelId":"<CHANNEL_ID>"}' \
   --target-org <org-alias>
 ```
@@ -67,8 +72,8 @@ sf api request rest \
 
 ```bash
 sf api request rest \
+  "/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
   --method POST \
-  --url "/connect/embeddedmessaging/deployment/setup" \
   --body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"API","messagingChannelId":"<CHANNEL_ID>"}' \
   --target-org <org-alias>
 ```
@@ -114,22 +119,36 @@ Save the `embeddedServiceDeploymentId` — it identifies the deployment for subs
 After creating the Web ESD via Connect API:
 
 1. **Update via Metadata API** — deploy `EmbeddedServiceConfig` XML with full configuration (forms, branding, channel settings, T&C)
-2. **Publish** — make changes live via Connect API publish endpoint
+2. **Publish** — see below
 
 ---
 
 ## Publishing After Updates
 
-After any update to a Web ESD (branding, forms, labels, settings), publish to make changes live:
+Updates to a Web ESD (branding, forms, labels, settings) stay in draft until published. Publish only after the user approves (SKILL.md step 17c):
 
 ```text
-POST /connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>
+POST /services/data/vXX.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>
 ```
 
 ```bash
 sf api request rest \
-  /services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID> \
+  "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" \
   --method POST \
+  --body '{}' \
+  --target-org <org-alias>
+```
+
+The `--body '{}'` is required: a POST with no body (or `--body ""`) fails in the CLI with
+"No 'mode' found in 'body' entry" before any request is sent. The URL is a positional
+argument, not a flag (`--url` fails with "Nonexistent flag"), and must be fully qualified
+(`/services/data/vXX.0/connect/...`).
+
+To obtain the `EMBEDDED_SERVICE_CONFIG_ID` (a Tooling API object, so `--use-tooling-api` is required):
+
+```bash
+sf data query --use-tooling-api \
+  --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" \
   --target-org <org-alias>
 ```
 

package/skills/service-digital-engagement-deployment-configure/references/deployment_settings.md

@@ -40,7 +40,7 @@ Links the deployment to a messaging channel and configures widget behavior. All
 |-------|------|---------|-------------|
 | `messagingChannel` | String | — | **Required.** Channel `channelPlatformKey` |
 | `businessHours` | String | — | BusinessHours `businessHoursName` |
-| `displayNameFormat` | String | — | Display name if pre-chat is enabled |
+| `displayNameFormat` | String | — | Display name shown when pre-chat is enabled. **Exactly 3 brace tokens** (empty for unused, e.g. `{_firstName}{_lastName}{}`); each token = a pre-chat field's `externalParameterName`, **not** its `formField`. See `references/prechat_forms.md` → displayNameFormat Rules |
 | `formula` | String | — | Condition logic expression referencing `sequence` numbers from `<embdMsgChannelInvitationConditions>` (e.g., `1 AND 2`, `1 OR 2 OR 3`). Required when `isInvitationEnabled` is `true`. Must be updated whenever conditions are added or removed |
 | `isChatInvitationCustomizable` | Boolean | `false` | **Required.** Allow customizing chat invitation. Can only be `true` for Web deployments; must be `false` for API/Mobile |
 | `isEnabled` | Boolean | `true` | **Required.** Whether messaging is enabled on this deployment |
@@ -56,84 +56,9 @@ Links the deployment to a messaging channel and configures widget behavior. All
 
 ---
 
-## Pre-Chat Forms (`<embeddedServiceForms>`)
+## Pre-Chat Forms (`<embeddedServiceForms>`) and `displayNameFormat`
 
-Collects information from users before conversation starts. Applicable to all deployment types.
-
-### Form Structure
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `displayContext` | Enum | Yes | `Conversation` or `Session` |
-| `isActive` | Boolean | Yes | Whether the form is active |
-| `embeddedServiceFormFields` | Repeatable | Yes | Individual form fields (see below) |
-
-### Form Field Structure (`<embeddedServiceFormFields>`)
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `displayOrder` | Integer | Yes | 0-based display position |
-| `formField` | String | Yes | Parameter name — use `_` prefix for standard fields (e.g., `_FirstName`), exact `name` for custom fields |
-| `formFieldType` | Enum | Yes | `Text`, `Email`, `Phone`, `Number` |
-| `isHidden` | Boolean | Yes | Whether field is hidden from user (still collected) |
-| `isRequired` | Boolean | Yes | Whether field must be filled |
-| `messagingChannelParameterType` | Enum | Yes | `Standard` or `Custom` |
-
-### Example
-
-```xml
-<embeddedServiceForms>
-    <displayContext>Conversation</displayContext>
-    <embeddedServiceFormFields>
-        <displayOrder>0</displayOrder>
-        <formField>_FirstName</formField>
-        <formFieldType>Text</formFieldType>
-        <isHidden>false</isHidden>
-        <isRequired>true</isRequired>
-        <messagingChannelParameterType>Standard</messagingChannelParameterType>
-    </embeddedServiceFormFields>
-    <embeddedServiceFormFields>
-        <displayOrder>1</displayOrder>
-        <formField>_Email</formField>
-        <formFieldType>Email</formFieldType>
-        <isHidden>false</isHidden>
-        <isRequired>true</isRequired>
-        <messagingChannelParameterType>Standard</messagingChannelParameterType>
-    </embeddedServiceFormFields>
-    <embeddedServiceFormFields>
-        <displayOrder>2</displayOrder>
-        <formField>CompanyName</formField>
-        <formFieldType>Text</formFieldType>
-        <isHidden>false</isHidden>
-        <isRequired>false</isRequired>
-        <messagingChannelParameterType>Custom</messagingChannelParameterType>
-    </embeddedServiceFormFields>
-    <isActive>true</isActive>
-</embeddedServiceForms>
-```
-
-### Standard Pre-Chat Fields
-
-Standard fields use a `_` prefix in the `formField` value:
-
-| `formField` Value | Maps to `parameterType` | Typical Usage |
-|-------------------|------------------------|---------------|
-| `_FirstName` | `FirstName` | User identification |
-| `_LastName` | `LastName` | User identification |
-| `_Email` | `Email` | Follow-up and case creation |
-| `_Subject` | `Subject` | Routing context |
-
-### Custom Pre-Chat Fields
-
-Custom fields use the exact `name` value from the channel's `customParameters` (no prefix). Custom fields must first be configured as `customParameters` on the messaging channel (via `service-digital-engagement-channel-configure`) before they can be referenced in the ESD form.
-
-### ChoiceList (Dropdown) Fields
-
-ChoiceList fields require a two-step deployment:
-1. Create the `ChoiceList` metadata record
-2. Assign it to the form field in the ESD
-
-The ChoiceList field must reference a custom parameter `name` on the messaging channel.
+Pre-chat is OFF by default. Form and field structure, hidden fields, the channel coupling and Omni-Flow routing prerequisites, ChoiceList (dropdown) fields, deactivating vs. removing fields, `displayNameFormat` rules, and pre-chat gotchas are all in `references/prechat_forms.md`.
 
 ---
 
@@ -191,3 +116,13 @@ Available since API v58.0. Repeatable. Configures conditions under which the mes
 | Create BrandingSet | No (auto-created by Connect API) | No | Yes |
 | Update BrandingSet properties | No | Yes | No |
 | Publish ESD | No | No | Yes |
+
+---
+
+## Less Common Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `embeddedServiceFlowConfig.enabled` error | Set to `false` unless you specifically need embedded flows (not routing flows) |
+| reCAPTCHA configuration rejected | reCAPTCHA is `@HideInWsdl` — must use Tooling API |
+| Business hours not taking effect | Only updating existing business hours works; creation is managed separately |

package/skills/service-digital-engagement-deployment-configure/references/onboarding_contract.md

@@ -0,0 +1,145 @@
+# Onboarding contract — delegated mode, transport, pre-scan, registration
+
+Read this when the invocation carries a `context` object, when you are about to write to the org, or when the
+skill is being registered in an onboarding module. It implements the Feature Setup Skill Guidelines (Conversational
+Onboarding, Service Cloud) for this skill.
+
+## 1. Two entry points, one write procedure
+
+| | Delegated | Standalone |
+|---|---|---|
+| Detected by | invocation has `context.calledFrom == "service-onboarding"` | no `context` object |
+| Values come from | `values` in the payload — already approved in the plan table | you ask, using the defaults in SKILL.md |
+| Questions | none. A missing required key is a caller bug: stop and report `failed` naming the key. Never default a value the admin did not approve | the Clarifying Questions in SKILL.md |
+| Wording | `discoveryMode == "guided"` → plain business language (§4). `"pickAreas"` → Salesforce terminology | Salesforce terminology (the Clarifying Questions as written) |
+| Ends with | the structured result in section 5 | a plain-language summary of the same outcome |
+
+Both paths converge on the same pre-scan → write → validate procedure. The only difference is where values come from.
+
+Delegated payload:
+
+```json
+{
+  "values": {
+    "operation": "create",
+    "deploymentType": "Web",
+    "deploymentName": "Acme Support Chat",
+    "channelName": "Acme_Support_Channel",
+    "siteName": "ESW_AcmeSupport_1700000000000"
+  },
+  "context": { "calledFrom": "service-onboarding", "discoveryMode": "guided" }
+}
+```
+
+Required `values`: `deploymentName`, `deploymentType`, `channelName`. `deploymentName` is the label; the API name is
+derived from it (SKILL.md Required Inputs: `Acme Support Chat` → `Acme_Support_Chat`). `operation` defaults to `create` when the pre-scan
+finds nothing and `update` when it finds a deployment. `siteName` is required for Web updates. Optional feature keys
+(pre-chat fields, business hours, T&C, branding) are applied only when present — do not invent them.
+
+## 2. Transport — `/headless/metadata` first, `sf` CLI as fallback
+
+**Transport A (primary): the headless-360 MCP `dispatch` / `dispatch_readonly` tools** against the synchronous
+Metadata-CRUD route, fully-qualified: `/services/data/vXX.0/headless/metadata/<Type>?type=<Type>&fullName=<Name>`.
+
+- `GET` = read (`dispatch_readonly`) → `{type, fullName, xmlRep}`. `POST` = create-only (duplicate → `DUPLICATE_VALUE`).
+  `PUT` = update. On writes the body must carry `type`, `fullName` **and** `xmlRep`.
+- Response is synchronous: `{results:[{success, errors[], ...}]}`. HTTP 200 can still be a failure — inner `success` wins.
+- **PUT is not a safe merge for `EmbeddedServiceConfig`.** Child collections survive an omitted block but inline
+  complex blocks can be silently cleared. Always GET → modify → PUT the **full** document. Never PUT a minimal payload.
+  Re-GET after the PUT and diff, so a dropped block is caught here and not in the widget.
+- Use the same `dispatch` tool for the probe and for the write. `sf api request rest` / `curl` carry the `sf` CLI's
+  separate credential, which can be expired while the MCP token is valid — a REST URL called through the CLI is
+  **not** Transport A.
+
+**Probe per type, per operation — do not infer from another type.** Before the first write run a read-only
+`GET` for `EmbeddedServiceConfig` (and for any other type you are about to touch).
+
+| Probe result | Meaning | Action |
+|---|---|---|
+| `xmlRep` returned, or "Metadata not found" style error | type is onboarded | Transport A |
+| `UNSUPPORTED_OPERATION` for the type or verb | not onboarded for that verb | Transport B for that call only |
+| auth / connection error | MCP unavailable | Transport B; say so |
+
+**Transport B (fallback): `sf` CLI** — the retrieve/deploy commands already in SKILL.md. Use it only when the probe
+says Transport A is unavailable for that type/verb, never as a convenience.
+
+What is not a transport choice:
+- **Web deployment creation is a Connect API call — send it with `sf api request rest`, not `dispatch`.** Through
+  `dispatch` it always fails with an `INTERNAL_ERROR` server error while building the ESW site; the same body via the CLI
+  succeeds. Do not try `dispatch` first.
+- **Publish is a Connect API call**, sent per SKILL.md step 17c (`dispatch`, `sf api request rest` on a route error).
+- **Tooling API** work (custom labels, branding, reCAPTCHA) is not verified through `dispatch`. Use `sf` CLI.
+
+## 3. Pre-scan (idempotency)
+
+Run before any write, both modes. Read `EmbeddedServiceConfig` by `fullName` = the API name derived from `deploymentName` (Transport A GET).
+
+| Finding | Outcome |
+|---|---|
+| No such deployment | not set up → create path |
+| Exists, and every targeted field already equals the target (channel link, `isEnabled`, type, and each optional feature supplied) | **already configured** — make no write, return `already-configured` |
+| Exists, some targeted field differs | **drift** — announce each change ("pre-chat form: on → off"), then write. Standalone: ask for a yes first. Delegated: the plan approval covers it |
+| Exists but links a different channel than `channelName` | Standalone: ask before repointing. Delegated: return `failed`, `errorMessage` = "deployment <name> already uses channel <other>" |
+
+Standalone, deployment exists: offer exactly three choices — no change / override / add to existing.
+
+The metadata read does not say whether the latest edits are **published**. Publishing is never automatic (SKILL.md
+step 17c); delegated returns `published: false` so the coordinator can ask the admin.
+
+## 4. Questions in the admin's language (guided mode)
+
+Ask about the outcome, not the Salesforce feature. Keep it to a handful; state the default with each.
+
+| Instead of | Ask |
+|---|---|
+| "Which deployment type: API, Mobile or Web?" | "Where will customers chat with you — on your website, in a mobile app, or through your own custom app?" (website=Web, mobile app=Mobile, custom=API) |
+| "Associate which `channelPlatformKey`?" | Not asked. Delegated: comes from the channel step. Standalone: "Which messaging channel should this chat use?" listing existing ones |
+| "Enable pre-chat form fields?" | "Do you want to ask customers for their name and email before the chat starts? (Default: yes — name and email.)" |
+| "Enable `isTermsAndConditionsEnabled`?" | "Do customers need to accept terms before chatting? (Default: no.)" |
+| "Business hours record?" | "Should the chat only be offered during your business hours? (Default: no.)" |
+| "Chat invitation conditions" | Skip in guided mode unless the admin raises it. It is a pickAreas/expert option |
+
+## 5. Result returned to the coordinator
+
+```json
+{
+  "status": "success | already-configured | failed",
+  "errorMessage": "<empty unless failed>",
+  "outputs": {
+    "deploymentName": "Acme_Support_Chat",
+    "embeddedServiceConfigId": "<id or null>",
+    "published": false
+  }
+}
+```
+
+`status` and `errorMessage` are the contract. `outputs` is always returned; it is an addition to the documented shape.
+On `failed`: `errorMessage` names the failed step and the platform error; stop; do not retry.
+
+## 6. Registration entry (draft for the onboarding team to place in a module)
+
+```yaml
+- id: messagingDeployment
+  title: "Chat widget for your website or app"
+  description: "Create the chat widget (embedded messaging deployment) that customers use to start a messaging conversation: where it appears, what it asks before chat starts, and publishing it live."
+  delegateSkill: service-digital-engagement-deployment-configure
+  dependsOn: [messagingChannel]
+  revisionOwner: service-digital-engagement-deployment-configure
+  # org perms: confirm exact names with Digital Engagement licensing (not yet confirmed)
+  values:
+    deploymentType:  { from: signal.messagingSurface,   default: "Web" }
+    deploymentName:  { from: signal.messagingWidgetName, default: "<company> Support Chat" }
+    channelName:     { from: outputs.messagingChannel.channelName }
+  writes: "EmbeddedServiceConfig (Metadata CRUD); Web create via Connect API embeddedmessaging/deployment/setup (sf CLI); publish via Connect API; optional BrandingSet / custom labels via Tooling API"
+  gating:
+    irreversible: false
+    note: "Reversible by disabling the deployment (isEnabled=false). Pre-chat form fields can be deactivated but the form cannot be fully deleted."
+  validate:
+    check: check-messaging-deployment
+    passWhen: "GET EmbeddedServiceConfig fullName=<derived API name> returns isEnabled=true and the embeddedServiceMessagingChannel links values.channelName; for Web, publishing is left to the admin after review (published may be false)"
+  alternative: "Setup > Embedded Service Deployments > New Deployment > Messaging for In-App and Web; choose the channel, set pre-chat, then Publish."
+```
+
+Open items for the onboarding team: the `signal.*` keys do not exist in `onboarding-state.schema.json` yet
+(`channels` allows only email/web); the coordinator must accept `outputs` and pass `outputs.messagingChannel.channelName`
+to this skill; org perm names are not yet confirmed.