@salesforce/afv-skills 1.66.0 → 1.68.0

package/skills/platform-widget-generate/references/widget-labels.md

@@ -0,0 +1,78 @@
+# Widget Localization with Custom Labels
+
+A widget shows translated text by referencing a Salesforce Custom Label instead of a hardcoded string.
+
+---
+
+## Syntax
+
+```text
+{!$Label.c.<LabelName>}
+```
+
+- `c` is the org's default namespace. Always write it.
+- The label name is static. Never build it from data — `{!$Label.c.$attrs.key}` can't be validated when the widget is saved.
+- A `$Label` reference is not a `$attrs` binding and has no entry in `schema.json`.
+
+---
+
+## What to localize
+
+Replace every static, user-visible string in an allowed attribute, unless the user limited the request to specific strings.
+
+**Allowed**
+
+- Display text: `text`, `label`, `placeholder`, `title`, and other free-form string attributes (per `getUiComponentSchemas`)
+- Text results inside a formula, e.g. the branches of an `IF` or `CASE`
+
+**Not allowed**
+
+- `meta` directives (`if`, `forEach`, `forItem`)
+- Enum-valued attributes (`variant`, `size`, `color`, `gap`, `align`, `justify`) and icon names
+- Anything inside `actions` (`url`, `target`, `sendMessage` `content`)
+- Data bound with `$attrs` / `$item` — payload values are not translated
+- `schema.json` and the `-meta.xml`
+
+---
+
+## Label names
+
+Reuse existing labels first. If the user names labels, or the project's CustomLabels file (`labels/CustomLabels.labels-meta.xml`) already has a label whose value matches the text, reference that label's `fullName` verbatim. Otherwise propose `<WidgetName>_<Role>`.
+
+---
+
+## Combining labels with data
+
+- Join a label and data with `&` (see `references/widget-formulas.md`):
+  `"text": "{!$Label.c.<LabelName> & ' ' & TEXT($attrs.<attrName>)}"`
+- Choose between labels with `IF` / `CASE`:
+  `"label": "{!IF($attrs.<booleanAttr>, $Label.c.<LabelWhenTrue>, $Label.c.<LabelWhenFalse>)}"`
+
+---
+
+## Creating labels
+
+This skill gives no guidance on authoring label metadata, and the widget is complete without it. Create labels only when the user asks you to. When you do, add them to the project's existing CustomLabels file instead of overwriting it, and never redefine a label that already exists. The user is responsible for checking the labels and any translations in the org and for deploying them with or before the widget.
+
+---
+
+## Label report
+
+End the response with this report:
+
+```markdown
+### Custom Labels used by this widget
+
+These labels must exist in the target org before you deploy — deploying a widget that references a missing label fails.
+
+| Label name | Value (default language) | Status | Used in |
+|---|---|---|---|
+| OrderStatus_Heading | Order status | Existing | `tile/text` `text` (widget heading) |
+| OrderStatus_TrackButton | Track order | To create | `tile/button` `label` |
+```
+
+- List each distinct label once, in the order it first appears in the widget.
+- **Label name** is the `fullName`, without the `c.` prefix.
+- **Value** is the literal text the label replaced.
+- **Status** is `Existing` (already in the project or named by the user), `Created` (you wrote it), or `To create` (the user must create it).
+- **Used in** names the block definition and attribute.

package/skills/platform-widget-generate/references/widget-styling.md

@@ -0,0 +1,12 @@
+# Widget Styling Best Practices
+
+Widgets express *intent*, not pixels. Each surface provides a default look and feel; brand/theme overrides apply automatically.
+
+- **Style semantically.** Use `variant`, `size`, and other enum-typed attributes (`primary`, `destructive`, `success`, `warning`). Do not pin literal colors or pixel values.
+- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary` or `destructive` for additional actions (see the `tile/button` schema for the full variant enum).
+- **Every `tile/button` needs a `click` action.** See SKILL.md *Actions* — an action-less button renders disabled.
+- **One `h1` per widget.** Use `h2`/`h3` for sub-section headings, `body` for prose, `caption` for helper text.
+- **Use semantic state variants on state-bearing blocks** (`tile/badge`, `tile/callout`).
+- **Omit attributes that equal the schema default.** Check each property's `default` in the `getUiComponentSchemas` metadata (step 4). If the value you would write matches it — e.g. `gap`, `size`, or `action/openLink` `target: "_blank"` — leave the attribute out. Set an attribute only to change it.
+- **Don't pin `width`** unless a content constraint requires it.
+- **Use the Lucide icon set.** Pass the Lucide name (`"check"`, `"alert-circle"`); other icon libraries are not supported.

package/skills/sales-call-scoring-configure/SKILL.md

@@ -146,12 +146,19 @@ Classify the org into one of 4 states:
 ### Phase 3 — Prerequisite enablement (State 2 only)
 
 - **License gate (checked first):** query `OrganizationSettingsDetail`
-  (Tooling API) for the `ECICallScoringAI` OrgPermission. If it isn't
-  `true`, exit with: "AI call coaching is not available in this org and org
-  requires Agentforce for Sales license." Non-zero exit. This runs even
-  when `enableCallCoaching`/`enableECICallScoring` already read favorably,
-  since those settings don't by themselves confirm the org is licensed.
-  **Must run before the ECI-off check below** — a genuinely unlicensed org
+  (Tooling API) for the `ECICallScoringAI` OrgPermission. Only an **explicit
+  `false`** refuses — exit with: "AI call coaching is not available in this
+  org and org requires Agentforce for Sales license." (Non-zero exit.) If the
+  permission **can't be read** — the query is rejected with `INVALID_TYPE`
+  (some org editions, for example Developer Edition) or returns no row — treat
+  it as **unknown and proceed**; do NOT fail closed on an unreadable signal.
+  The Einstein GenAI `TYPE_UNAVAILABLE` pre-check catches most unlicensed
+  orgs; the enable `updateMetadata` write is the final check. This mirrors the Phase 0
+  `ConversationPilot` gate, which defers on any non-conclusive read.
+  This runs even when `enableCallCoaching`/`enableECICallScoring`
+  already read favorably, since those settings don't by themselves confirm the
+  org is licensed. **Must run before the ECI-off check below** — a genuinely
+  unlicensed org
   and a licensed-but-toggled-off org both read `enableCallCoaching=false`,
   so checking ECI first would misdiagnose a licensing gap as a self-serve
   Setup toggle (the regression the `NoLicense` eval dataset guards against).
@@ -217,7 +224,7 @@ Re-read `enableECICallScoring`. Require `true`. Print SOAP response on failure.
   is server-side read-only and `updateMetadata` returns
   `INSUFFICIENT_ACCESS_OR_READONLY`. `enable-call-scoring.sh` maps this to a
   transient "still finishing turning on — wait a few minutes and re-run"
-  message rather than a terminal failure (W-23968462).
+  message rather than a terminal failure.
 - **Every SOAP call is bounded by a 30s timeout** (`CURL_TIMEOUT` in
   `enable-call-scoring.sh`, matching the only existing timeout precedent in
   this repo — the Pipeline skill's `setup-all.sh`) and classified via
@@ -243,14 +250,14 @@ Re-read `enableECICallScoring`. Require `true`. Print SOAP response on failure.
 - **SOAP helpers**: `scripts/shared/soap.sh` (copied from the Pipeline skill —
   `redact_token`, `parse_soap_response`)
 - **Server-side gate** (declarative access check):
-  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.accessChecks.xml`
+  `ConversationalIntelligence.accessChecks.xml`
   — `orgHasCallScoring` = ECI arm OR River Rush arm; `orgHasECICallScoringWithAI`
   adds Einstein GenAI + `ECICallScoringAI` license perm on top.
 - **Pref declaration**:
-  `core/conversation-udd/java/resources/udd/conversation-udd/ConversationalIntelligence.settings.xml`
+  `ConversationalIntelligence.settings.xml`
   — `<orgPreference name="ECICallScoringEnabled" mdApiName="enableECICallScoring" ...>`
 - **Java feature registration** (would be the entry point if a
-  SetupDiscoveryService REST/MCP wrapper existed): `core/conversation-impl/java/src/conversation/features/CoachingCompetenciesFeature.java`
+  SetupDiscoveryService REST/MCP wrapper existed): `CoachingCompetenciesFeature.java`
 
 ## Competency CRUD workflow
 

package/skills/sales-call-scoring-configure/scripts/enable-call-scoring.sh

@@ -61,14 +61,14 @@ resolve_org_auth_with_token "$ORG_ALIAS" || exit 1
 # orgs) reject the OrganizationSettingsDetail query with INVALID_TYPE. That's
 # not a licensing signal — it's a metadata-availability signal. Treat any
 # non-conclusive result as "unknown, defer to SOAP" and only refuse when the
-# query explicitly comes back "false" (W-24022554).
+# query explicitly comes back "false".
 CONVERSATIONPILOT_ENABLED=""
 if CONVERSATIONPILOT_RAW=$(sf data query --target-org "$ORG_ALIAS" --use-tooling-api \
     --query "SELECT SettingValue FROM OrganizationSettingsDetail WHERE SettingName='ConversationPilot' AND DataType='OrgPermissionSettings'" \
     --json 2>/dev/null); then
   CONVERSATIONPILOT_JSON=$(echo "$CONVERSATIONPILOT_RAW" | awk '/^{/,EOF')
   if echo "$CONVERSATIONPILOT_JSON" | jq -e '.status == 0' >/dev/null 2>&1; then
-    CONVERSATIONPILOT_ENABLED=$(echo "$CONVERSATIONPILOT_JSON" | jq -r '.result.records[0].SettingValue // empty')
+    CONVERSATIONPILOT_ENABLED=$(echo "$CONVERSATIONPILOT_JSON" | jq -r '.result.records[0].SettingValue | select(. != null)')
   fi
 fi
 
@@ -215,7 +215,6 @@ fi
 # doing a write — Einstein GenAI Platform is a hard prerequisite for AI
 # Call Scoring, so an org that can't even see that settings type won't be
 # able to enable Call Coaching regardless of what the ECI toggle says.
-# W-24026047.
 #
 # Not perfect: an org could have the GenAI platform present but still lack
 # the specific Call Scoring license. State 2c's ECICallScoringAI
@@ -245,19 +244,33 @@ if ECICALLSCORINGAI_RAW=$(sf data query --target-org "$ORG_ALIAS" --use-tooling-
     --json 2>/dev/null); then
   ECICALLSCORINGAI_JSON=$(echo "$ECICALLSCORINGAI_RAW" | awk '/^{/,EOF')
   if echo "$ECICALLSCORINGAI_JSON" | jq -e '.status == 0' >/dev/null 2>&1; then
-    ECICALLSCORINGAI_ENABLED=$(echo "$ECICALLSCORINGAI_JSON" | jq -r '.result.records[0].SettingValue // "false"')
+    # A missing row means "couldn't read it", NOT "license is off" — default
+    # to empty (unknown), never to "false". OrganizationSettingsDetail is not
+    # queryable (INVALID_TYPE) on some org editions (for example Developer
+    # Edition) and can return zero rows even when queryable; both are "can't
+    # tell", and collapsing them to "false" fails closed. Use select(), not
+    # `// empty`: SettingValue is a boolean and `//` drops an explicit false.
+    ECICALLSCORINGAI_ENABLED=$(echo "$ECICALLSCORINGAI_JSON" | jq -r '.result.records[0].SettingValue | select(. != null)')
   fi
 fi
 
-if [[ -z "$ECICALLSCORINGAI_ENABLED" ]]; then
-  echo "Could not determine AI call coaching license state — ECICallScoringAI query failed."
-  echo "   Verify the CLI session is valid (sf org login web --alias $ORG_ALIAS) and re-run."
+# Only an EXPLICIT negative refuses. An unknown result — the query was
+# rejected (INVALID_TYPE on this org shape) or returned no row — must NOT
+# hard-fail: doing so blocks legitimately-licensed orgs where
+# OrganizationSettingsDetail simply isn't queryable. This mirrors the Phase 0
+# ConversationPilot gate, which defers to SOAP on any non-conclusive read. The
+# 2a-pre GenAI TYPE_UNAVAILABLE gate above catches most unlicensed orgs, and
+# the updateMetadata write below is the final check — a truly unlicensed org
+# faults on the write. Closes the residual gap the earlier
+# GenAI-proxy fix left behind.
+if [[ "$ECICALLSCORINGAI_ENABLED" == "false" ]]; then
+  echo "AI call coaching is not available in this org and org requires Agentforce for Sales license."
   exit 1
 fi
 
-if [[ "$ECICALLSCORINGAI_ENABLED" != "true" ]]; then
-  echo "AI call coaching is not available in this org and org requires Agentforce for Sales license."
-  exit 1
+if [[ -z "$ECICALLSCORINGAI_ENABLED" ]]; then
+  echo "Couldn't confirm the AI Call Scoring license on this org — continuing;"
+  echo "   if the license is missing, the enable step will report it."
 fi
 
 # 2b. ECI must be enabled — this skill is ECI-only.
@@ -363,7 +376,7 @@ EOF
     # read-only and updateMetadata returns INSUFFICIENT_ACCESS_OR_READONLY.
     # This is a transient state that self-resolves in a few minutes, not a
     # permanent failure — surface a wait-and-retry message instead of the
-    # generic error. W-23968462.
+    # generic error.
     case "$CS_RESULT" in
       WRITE_ERROR:INSUFFICIENT_ACCESS_OR_READONLY*)
         echo "   Einstein Conversation Insights is still finishing turning on."
@@ -388,31 +401,40 @@ CCR_LOOKUP=$(sf api request rest \
   "services/data/v68.0/tooling/query/?q=SELECT+Id,SettingValue+FROM+OrganizationSettingsDetail+WHERE+SettingName='CallCoachingReady'+AND+DataType='OrgPermissionSettings'" \
   --target-org "$ORG_ALIAS" 2>/dev/null) || true
 
-CCR_COUNT=$(echo "$CCR_LOOKUP" | jq -r '.totalSize // 0' 2>/dev/null || echo 0)
-if [[ "$CCR_COUNT" == "0" ]]; then
-  echo "Could not locate the CallCoachingReady OrgPermission record on this org."
-  exit 1
-fi
+# On some org editions (for example Developer Edition), OrganizationSettingsDetail
+# isn't exposed at all (INVALID_TYPE) — the same unqueryable shape the Phase 3
+# license gate tolerates. The authoritative enable (enableECICallScoring, flipped
+# above and re-verified below) has already succeeded, so a CallCoachingReady
+# lookup we physically cannot run must not fail the enable closed.
+if echo "$CCR_LOOKUP" | grep -q '"errorCode"[[:space:]]*:[[:space:]]*"INVALID_TYPE"'; then
+  echo "CallCoachingReady OrgPermission isn't queryable on this org — skipping (Call Coaching is already enabled)."
+else
+  CCR_COUNT=$(echo "$CCR_LOOKUP" | jq -r '.totalSize // 0' 2>/dev/null || echo 0)
+  if [[ "$CCR_COUNT" == "0" ]]; then
+    echo "Could not locate the CallCoachingReady OrgPermission record on this org."
+    exit 1
+  fi
 
-CCR_ID=$(echo "$CCR_LOOKUP" | jq -r '.records[0].Id')
-CCR_CURRENT=$(echo "$CCR_LOOKUP" | jq -r '.records[0].SettingValue')
+  CCR_ID=$(echo "$CCR_LOOKUP" | jq -r '.records[0].Id')
+  CCR_CURRENT=$(echo "$CCR_LOOKUP" | jq -r '.records[0].SettingValue')
 
-if [[ "$CCR_CURRENT" == "true" ]]; then
-  echo "CallCoachingReady is already enabled — skipping."
-else
-  echo "Enabling CallCoachingReady..."
-  if CCR_PATCH_RESP=$(sf api request rest \
-      "services/data/v68.0/tooling/sobjects/OrganizationSettingsDetail/${CCR_ID}" \
-      --target-org "$ORG_ALIAS" \
-      --method PATCH \
-      --header 'Content-Type: application/json' \
-      --body '{"SettingValue": true}' \
-      2>/dev/null); then
-    echo "   CallCoachingReady enabled"
+  if [[ "$CCR_CURRENT" == "true" ]]; then
+    echo "CallCoachingReady is already enabled — skipping."
   else
-    echo "   Failed to enable CallCoachingReady"
-    echo "   $CCR_PATCH_RESP"
-    exit 1
+    echo "Enabling CallCoachingReady..."
+    if CCR_PATCH_RESP=$(sf api request rest \
+        "services/data/v68.0/tooling/sobjects/OrganizationSettingsDetail/${CCR_ID}" \
+        --target-org "$ORG_ALIAS" \
+        --method PATCH \
+        --header 'Content-Type: application/json' \
+        --body '{"SettingValue": true}' \
+        2>/dev/null); then
+      echo "   CallCoachingReady enabled"
+    else
+      echo "   Failed to enable CallCoachingReady"
+      echo "   $CCR_PATCH_RESP"
+      exit 1
+    fi
   fi
 fi
 

package/skills/service-digital-engagement-channel-configure/SKILL.md

@@ -138,13 +138,15 @@ All steps are sequential. Do not skip or reorder.
    - `isSaveTranscriptEnabled` — save conversation transcripts
    - `maxFileSize` — maximum attachment size in MB
 
+9a. **Configure session inactivity (optional)** — ask using the Setup labels and set the top-level fields per `references/channel_settings.md` → "Setup Prompts: Session Inactivity".
+
 10. **Configure messaging keywords** — generate `<messagingKeywords>` elements:
     - `OptOut` type with individual `<keyword>` elements: cancel, end, quit, stop, stopall, unsubscribe
     - `Help` type with `<keyword>`: help
 
 11. **Apply standard parameters** — if the user needs standard pre-chat fields, generate `<standardParameters>` elements with `parameterType`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
-12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
+12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. Always set `parameterDataType` to `String` — the channel accepts no other value (the field's actual type, including Checkbox/Number/dropdown, is set at the deployment level via `formFieldType`, not here). If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
 13. **Generate the file** — produce the `.messagingChannel-meta.xml` file following the template structure. Place at the path the user specifies, or default to the project's metadata source path under `messagingChannels/`.
 
@@ -176,7 +178,7 @@ All steps are sequential. Do not skip or reorder.
 17. **Report** — delegated: return the contract §5 result and stop. Standalone: continue.
 
 18. **Present output** (standalone) — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
-    - **Automated responses** — ask if the user wants to configure `<automatedResponses>` (OptOutConfirmation, HelpResponse). If yes, generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text, then redeploy.
+    - **Automated responses** — ask which messages the user wants using the Setup labels per `references/channel_settings.md` → "Setup Prompts: Automated Responses", then redeploy.
 
 ---
 
@@ -216,8 +218,10 @@ All steps are sequential. Do not skip or reorder.
 | "Only active Agentforce Service Agents are supported" on deploy | Bot is inactive — run `sf agent activate` before deploying |
 | Flow or ASA routing fails without fallback queue | `sessionHandlerQueue` is mandatory when `sessionHandlerType` is `Flow` or `AgentforceServiceAgent` |
 | JWT verification not working | Connected app and certificate must be configured for the org |
-| Custom parameters not collected | `name` must be unique per channel; `parameterDataType` defaults to `Text` |
-| Automated responses not showing | Use exact `type` values (`OptOutConfirmation`, `HelpResponse`); XML-escape special characters |
+| Custom parameters not collected | `name` must be unique per channel |
+| `<customParameters>` deploy fails: "bad value for restricted picklist field" | `parameterDataType` was set to something other than `String`. Channel custom parameters are always `String`; set the field's actual type (Number, Checkbox, dropdown) at the deployment level, not here |
+| Removing a custom parameter: "can't be deleted as it is referenced elsewhere" | **Check before deploying, not after.** Every deployment on this channel whose pre-chat form uses the param must first drop that field and be published (user-approved); remove the param's `actionParameterMappings` in a separate deploy first. See `references/channel_settings.md` §Removing a Custom Parameter |
+| Automated response / session-inactivity deploy fails | See `references/channel_settings.md` → "Automated Responses", "Session Settings" |
 | Channel deployed but messages not routing | Channel must be activated after deployment — it defaults to inactive |
 | "You can't enable Session-Based Chat for verified users" | Set `isSynchronousChatEnabled` to `false` for Auth channels — session-based chat is only valid for UnAuth |
 
@@ -250,9 +254,8 @@ All steps are sequential. Do not skip or reorder.
 - [ ] If UnAuth, is `anonymousUserJwtExpirationTime` set (default 360, range 60-4320)?
 - [ ] If Auth, is `verifiedUserJwtExpirationTime` set (default 60, range 60-240)?
 
-### Automated Response Checks (only if user requested)
-- [ ] Do all `type` values use valid IDs (`OptOutConfirmation`, `HelpResponse`)?
-- [ ] Are special characters XML-escaped in `response` text?
+### Session Inactivity / Automated Response Checks (only if user requested)
+- [ ] Checked against `references/channel_settings.md` (Session Settings, Automated Responses)?
 
 ### Keyword Checks
 - [ ] Is there at least an `OptOut` keyword type defined?
@@ -281,6 +284,7 @@ File structure follows the template in `assets/messaging_channel_template.xml`.
 | Creating the Omni-Channel Flow for routing | `automation-flow-generate` skill |
 | Creating permission sets for messaging agents | `platform-permission-set-generate` skill |
 | Creating the Embedded Service Deployment | `service-digital-engagement-deployment-configure` skill |
+| Creating the `ConversationMessageDefinition` an automated response references | `conversation-message-definition-builder` skill |
 
 ---
 

package/skills/service-digital-engagement-channel-configure/assets/messaging_channel_template.xml

@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <MessagingChannel xmlns="http://soap.sforce.com/2006/04/metadata">
     <!-- Automated Responses (optional, repeat per response) -->
+    <!-- Shape depends on type — see references/channel_settings.md "Automated Responses" -->
+    <!-- TextResponse shape: OptOutConfirmation, HelpResponse only -->
     <!--
     <automatedResponses>
         <autoResponseContentType>TextResponse</autoResponseContentType>
@@ -10,6 +12,18 @@
     </automatedResponses>
     -->
 
+    <!-- MessageDefinition shape: InitialResponse, AgentEngagedResponse, AgentEndEngagementResponse, EndUserInactiveResponse, EndUserIdleResponse, RerouteResponse, RoutingUnavailableResponse -->
+    <!-- messageDefinitionName must reference an existing ConversationMessageDefinition (build via conversation-message-definition-builder first) -->
+    <!-- Do NOT include language or response on this shape -->
+    <!-- Optional responseTimeoutInMins (4-30): only for EndUserIdleResponse / EndUserInactiveResponse -->
+    <!--
+    <automatedResponses>
+        <autoResponseContentType>MessageDefinition</autoResponseContentType>
+        <messageDefinitionName>{CONVERSATION_MESSAGE_DEFINITION_DEV_NAME}</messageDefinitionName>
+        <type>{InitialResponse|AgentEngagedResponse|AgentEndEngagementResponse|EndUserInactiveResponse|EndUserIdleResponse|RerouteResponse|RoutingUnavailableResponse}</type>
+    </automatedResponses>
+    -->
+
     <!-- Standard Parameters (optional, repeat per parameter) -->
     <!-- actionParameterMappings is optional — include when using Flow routing to map to flow input variables -->
     <!--
@@ -58,10 +72,29 @@
         <isFileAttachmentExtUnrestricted>{true|false}</isFileAttachmentExtUnrestricted>
         <isSaveTranscriptEnabled>{true|false}</isSaveTranscriptEnabled>
         <maxFileSize>{SIZE_IN_MB}</maxFileSize>
+
+        <!-- Messaging Authorizations (only when authMode is Auth; omit entirely for UnAuth) -->
+        <!--
+        <messagingAuthorizations>
+            <authIdentifier>{AUTH_IDENTIFIER}</authIdentifier>
+            <authorizationType>PublicKeyCertificateSet</authorizationType>
+            <enabled>{true|false}</enabled>
+            <publicKeyCertificateSetName>{KEYSET_NAME}</publicKeyCertificateSetName>
+        </messagingAuthorizations>
+        -->
     </embeddedConfig>
 
     <!-- Session Settings -->
     <endUserIdleTimeOut>{IDLE_TIMEOUT_MINUTES}</endUserIdleTimeOut>
+
+    <!-- Session Inactivity (optional) — top-level siblings of embeddedConfig, not nested inside it -->
+    <!-- endUserIdleAction must be Inactivate, End, or InactivateAndEnd -->
+    <!--
+    <endUserIdleAction>{Inactivate|End|InactivateAndEnd}</endUserIdleAction>
+    <endInactiveSessionTimeOut>{MINUTES_AFTER_IDLE_ACTION}</endInactiveSessionTimeOut>
+    <isAgentMessageResetInactivityEnabled>{true|false}</isAgentMessageResetInactivityEnabled>
+    -->
+
     <isEstimatedWaitTimeEnabled>{true|false}</isEstimatedWaitTimeEnabled>
     <isQueuePositionEnabled>{true|false}</isQueuePositionEnabled>
     <isSynchronousChatEnabled>{true|false}</isSynchronousChatEnabled>

package/skills/service-digital-engagement-channel-configure/references/channel_settings.md

@@ -133,12 +133,24 @@ Configures the authorization settings for verified user identity in the messagin
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `endUserIdleTimeOut` | Integer | `5` | Minutes of user inactivity before idle warning |
+| `endUserIdleTimeOut` | Integer | `5` | Minutes of user inactivity before idle warning (range 5-30) |
+| `endUserIdleAction` | Enum | — | Action taken when the idle timeout elapses: `Inactivate`, `End`, or `InactivateAndEnd` |
+| `endInactiveSessionTimeOut` | Integer | — | Minutes after `endUserIdleAction` fires before the inactive session itself ends |
+| `isAgentMessageResetInactivityEnabled` | Boolean | — | Restart the customer's inactivity timer when a rep sends a message (Setup label: "Rep messages reset customer's inactivity timer"). Only takes effect when `endUserIdleTimeOut` is set; it is forced to `false` otherwise |
 | `isEstimatedWaitTimeEnabled` | Boolean | `false` | Show estimated wait time |
 | `isQueuePositionEnabled` | Boolean | `false` | Show queue position to user |
 | `isSynchronousChatEnabled` | Boolean | `false` | Enable real-time synchronous chat |
 | `isVoiceModeEnabled` | Boolean | `false` | Enable voice mode capability |
 
+Setup UI (Customer Inactivity card): `endUserIdleTimeOut` is "Minutes to Inactivate Session" / "Minutes to End Session" (5-30); `endUserIdleAction` is "Choose action when customer is idle" with values "Inactivate Session" (`Inactivate`), "End Session" (`End`), and "Inactivate & End Session" (`InactivateAndEnd`); `endInactiveSessionTimeOut` is "Minutes to End Session After Inactivation" (5-30, only meaningful with `InactivateAndEnd`).
+
+`endUserIdleTimeOut`, `endUserIdleAction`, `endInactiveSessionTimeOut`, and `isAgentMessageResetInactivityEnabled` are **MIAW (EmbeddedMessaging) only** — not applicable to SMS/WhatsApp/LINE. These can be deployed together with `isAbandonedChatsEnabled`/`chatAbandonmentTimeout` with no conflict.
+
+```xml
+<endUserIdleTimeOut>5</endUserIdleTimeOut>
+<endUserIdleAction>InactivateAndEnd</endUserIdleAction>
+<endInactiveSessionTimeOut>10</endInactiveSessionTimeOut>
+```
 
 ---
 
@@ -196,11 +208,13 @@ Repeatable element — one block per pre-chat field for data collection.
 |-------|------|----------|-------------|
 | `name` | String | Yes | Unique API name for the parameter |
 | `masterLabel` | String | Yes | Display label shown to agent/user |
-| `parameterDataType` | Enum | Yes | `String`, `Number`, `Boolean` |
+| `parameterDataType` | String | Yes | **Always `String`** — see note below |
 | `externalParameterName` | String | Yes | External mapping name for the parameter |
-| `maxLength` | Integer | No | Max chars for Text type (default 255) |
+| `maxLength` | Integer | No | Max chars (default 255) |
 | `actionParameterMappings` | Object | No | Maps this parameter to an Omni-Channel Flow action input variable |
 
+> **`parameterDataType` is always `String`.** Every channel custom parameter deploys as `String`, regardless of the field's logical type. The metadata field's declared type is the broad `FlowDataType` enum (`Apex`, `Boolean`, `Currency`, `Date`, `DateTime`, `Multipicklist`, `Number`, `Picklist`, `SObject`, `String`, `Time`), but `MessagingChannel` restricts it at deploy time to `String` only — any other value fails with *"bad value for restricted picklist field."* The parameter's actual data type (Number, Checkbox/Boolean, dropdown, etc.) is not set on the channel; it is chosen at the **deployment** level in the pre-chat New Custom Parameter screen — i.e. via the Embedded Service form field's `formFieldType` (see `service-digital-engagement-deployment-configure`).
+
 ### Action Parameter Mappings
 
 When the channel uses Flow-based routing, `actionParameterMappings` maps a custom parameter to a flow input variable so the value collected from the user is passed into the routing flow.
@@ -222,34 +236,89 @@ When the channel uses Flow-based routing, `actionParameterMappings` maps a custo
 </customParameters>
 ```
 
+### Removing a Custom Parameter
+
+A parameter still used by a pre-chat form can't be deleted ("can't be deleted as it is referenced elsewhere"). Several deployments can share one channel, so **check every deployment before writing**: retrieve all `EmbeddedServiceConfig` and find each one whose `<messagingChannel>` is this channel and whose form has `<formField>` = the param `name`. Don't use a failed channel deploy to find them.
+
+1. If another deployment the user didn't mention still uses the param, stop and ask; changing it is outside the request.
+2. Each referencing deployment: remove the field (via `service-digital-engagement-deployment-configure`) and publish it after the user approves.
+3. If the param has `actionParameterMappings`, deploy the channel with the mapping removed first.
+4. Deploy the channel without that parameter's `<customParameters>` block; keep every other parameter.
+
 ---
 
 ## Automated Responses (`<automatedResponses>`)
 
-Repeatable element — automated messages sent at specific events.
+Repeatable element — automated messages sent at specific events. There are two mutually exclusive content shapes, and **which shape applies depends on the `type`** (EmbeddedMessaging channel).
+
+### Shape 1 — `TextResponse` (inline text)
+
+Applies only to `OptOutConfirmation` and `HelpResponse`.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `autoResponseContentType` | Enum | Yes | `TextResponse` or `MessageDefinition` |
+| `autoResponseContentType` | Enum | Yes | `TextResponse` |
 | `language` | String | Yes | Locale code (e.g., `en_US`) |
 | `response` | String | Yes | The response message text (XML-escape special chars) |
-| `type` | Enum | Yes | The event type — see table below |
+| `type` | Enum | Yes | `OptOutConfirmation` or `HelpResponse` |
+
+### Shape 2 — `MessageDefinition` (reference to a Messaging Component)
+
+Applies to `InitialResponse`, `AgentEngagedResponse`, `AgentEndEngagementResponse`, `EndUserInactiveResponse`, `EndUserIdleResponse`, `RerouteResponse`, and `RoutingUnavailableResponse` — the "Conversation Acknowledgement," "Start Conversation," "End Conversation," "Inactive Conversation," "Warning Message," "Reroute Conversation," and "Routing Unavailable" fields in the Setup UI, all backed by a "Messaging Components" (`ConversationMessageDefinition`) picker.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `autoResponseContentType` | Enum | Yes | `MessageDefinition` |
+| `messageDefinitionName` | String | Yes | `DeveloperName` of an existing `ConversationMessageDefinition`. Must already exist in the org — build it with the `conversation-message-definition-builder` skill before deploying this reference (see Cross-Skill Integration in SKILL.md) |
+| `type` | Enum | Yes | `InitialResponse`, `AgentEngagedResponse`, `AgentEndEngagementResponse`, `EndUserInactiveResponse`, `EndUserIdleResponse`, `RerouteResponse`, or `RoutingUnavailableResponse` |
+| `responseTimeoutInMins` | Integer | No | **Only** on `EndUserIdleResponse` and `EndUserInactiveResponse` (range 4-30). Minutes before the idle action fires at which the message is shown (Setup label "Minutes to Show Warning"; Help: "select 4 to show the message 4 minutes before the session inactivates"). On `EndUserIdleResponse` it must be less than `endUserIdleTimeOut` (Setup caps it at `endUserIdleTimeOut` - 1). Rejected on every other type and on `TextResponse` |
+
+**Do not include `<language>` or `<response>` on a `MessageDefinition`-shaped block.** The language comes from the referenced CMD's own `<language>` field. Including `<language>` here causes the deploy to fail — with `"unexpected metadata"` for `InitialResponse`/`AgentEngagedResponse`/`AgentEndEngagementResponse`, and with an internal server error for `EndUserInactiveResponse`. Omitting it is the fix, not a schema quirk to work around another way.
+
+```xml
+<!-- TextResponse shape -->
+<automatedResponses>
+    <autoResponseContentType>TextResponse</autoResponseContentType>
+    <language>en_US</language>
+    <response>Text STOP to opt out of further messages.</response>
+    <type>HelpResponse</type>
+</automatedResponses>
+
+<!-- MessageDefinition shape -->
+<automatedResponses>
+    <autoResponseContentType>MessageDefinition</autoResponseContentType>
+    <messageDefinitionName>Customer_Inactive_Message</messageDefinitionName>
+    <type>EndUserInactiveResponse</type>
+</automatedResponses>
+
+<!-- Idle warning with responseTimeoutInMins (only valid on EndUserIdleResponse / EndUserInactiveResponse) -->
+<automatedResponses>
+    <autoResponseContentType>MessageDefinition</autoResponseContentType>
+    <messageDefinitionName>Idle_Warning_Message</messageDefinitionName>
+    <responseTimeoutInMins>4</responseTimeoutInMins>
+    <type>EndUserIdleResponse</type>
+</automatedResponses>
+```
 
 ### Response Types
 
-| `type` Value | When Sent |
-|-------------|-----------|
-| `OptOutConfirmation` | When user opts out of receiving messages |
-| `HelpResponse` | When user sends a help keyword |
-| `InitialResponse` | Let a customer know that their initial message was received |
-| `AgentEngagedResponse` | Let a customer know that their messaging session was accepted by a service rep |
-| `AgentEndEngagementResponse` | Let a customer know that their messaging session ended, and optionally provide a post-chat URL. This auto-response is sent when the service rep or end user ends the session |
-| `EndUserInactiveResponse` | Let a customer know that their messaging conversation has ended because they stopped responding |
-| `EndUserIdleResponse` | When end user idle response |
+| `type` Value | Content Shape | When Sent |
+|-------------|---------------|-----------|
+| `OptOutConfirmation` | `TextResponse` | When user opts out of receiving messages |
+| `HelpResponse` | `TextResponse` | When user sends a help keyword |
+| `InitialResponse` | `MessageDefinition` | Let a customer know that their initial message was received |
+| `AgentEngagedResponse` | `MessageDefinition` | Let a customer know that their messaging session was accepted by a service rep |
+| `AgentEndEngagementResponse` | `MessageDefinition` | Let a customer know that their messaging session ended, and optionally provide a post-chat URL. Sent when the service rep or end user ends the session |
+| `EndUserInactiveResponse` | `MessageDefinition` | Let a customer know that their messaging conversation has ended because they stopped responding |
+| `EndUserIdleResponse` | `MessageDefinition` | Warn a customer that their conversation will be inactivated or ended because they are idle. Set in the Customer Inactivity card ("Warning Message"); `responseTimeoutInMins` is how many minutes before the idle action it is shown |
+| `RerouteResponse` | `MessageDefinition` | Sent when a conversation is rerouted to a different queue or agent ("Reroute Conversation") |
+| `RoutingUnavailableResponse` | `MessageDefinition` | Sent when no routing target is available ("Routing Unavailable") |
+
+Only `OptOutConfirmation` and `HelpResponse` use the `TextResponse` shape; every other type is `MessageDefinition`-only. `OptIn*` and `CustomResponse` types are not used for EmbeddedMessaging channels.
 
 ### XML Escaping
 
-Special characters in `response` must be XML-escaped:
+Special characters in a `TextResponse` block's `response` must be XML-escaped:
 - `'` → `&apos;`
 - `"` → `&quot;`
 - `&` → `&amp;`
@@ -292,3 +361,41 @@ Repeatable element — keyword groups that trigger automated responses. Each key
     <language>en_US</language>
 </messagingKeywords>
 ```
+
+---
+
+## Setup Prompts: Session Inactivity
+
+Ask using the Setup labels (Customer Inactivity card), with the field in parentheses:
+
+- "Inactivate or end a session after a period of customer inactivity?" If yes, "Minutes to Inactivate Session / End Session?" (`endUserIdleTimeOut`, 5-30).
+- "Choose action when customer is idle": **Inactivate Session** (`Inactivate`), **End Session** (`End`), or **Inactivate & End Session** (`InactivateAndEnd`) (`endUserIdleAction` — no other values). **Validate before editing or deploying:** if the user names any other value (e.g. `EndChatSession`, "close", "terminate"), do not write it; say it is not an option, list the three, and ask which one. Never deploy to see whether it is accepted. For Inactivate & End Session also ask "Minutes to End Session After Inactivation?" (`endInactiveSessionTimeOut`, 5-30).
+- "Should rep messages reset the customer's inactivity timer?" (`isAgentMessageResetInactivityEnabled`; needs `endUserIdleTimeOut`).
+- Optional idle warning: the **Warning Message** prompt under Automated Responses below.
+
+Set all of these as **top-level fields, siblings of `<embeddedConfig>`** (not nested inside it). MIAW (EmbeddedMessaging) only.
+
+Checks:
+- [ ] `endUserIdleAction`/`endInactiveSessionTimeOut` are top-level siblings of `<embeddedConfig>`, not nested inside it.
+- [ ] `endUserIdleAction` is one of `Inactivate`, `End`, `InactivateAndEnd`, checked before the file is edited (free text such as `EndChatSession` fails with "not a valid value for the enum").
+- [ ] `endUserIdleTimeOut` is in range 5-30.
+
+## Setup Prompts: Automated Responses
+
+Ask which messages the user wants, using the Setup labels (Automated Responses card), with the `type` in parentheses. Two content shapes, chosen by `type`:
+
+- Consent text — **Opt-Out Confirmation** (`OptOutConfirmation`) and **Help Response** (`HelpResponse`): `TextResponse` shape; generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text.
+- Messaging Components — `MessageDefinition` shape; the referenced `ConversationMessageDefinition` must exist first. If it doesn't, delegate to `conversation-message-definition-builder` to create it, then generate the element with `autoResponseContentType: MessageDefinition` and `messageDefinitionName` (no `language`, no `response`):
+  - **Conversation Acknowledgement** (`InitialResponse`), **Start Conversation** (`AgentEngagedResponse`), **End Conversation** (`AgentEndEngagementResponse`), **Inactive Conversation** (`EndUserInactiveResponse`), **Reroute Conversation** (`RerouteResponse`), **Routing Unavailable** (`RoutingUnavailableResponse`).
+  - **Warning Message** (`EndUserIdleResponse`) — the idle warning; ask "How many minutes before the session inactivates/ends should the warning show?" (Setup: "Minutes to Show Warning"; `responseTimeoutInMins`, 4-30, less than `endUserIdleTimeOut`). `responseTimeoutInMins` is allowed only on `EndUserIdleResponse` and `EndUserInactiveResponse`.
+
+Offer **every** type above (nine in all), never a subset. A question tool that allows only four options means asking in several rounds; do not merge types into buckets or drop any. If the user says only "automated responses", ask round by round until each type is accepted or declined. Ask for the `TextResponse` wording (Opt-Out, Help) instead of inventing it. Create any missing component by **invoking the `conversation-message-definition-builder` skill** (Skill tool) and deploying what it produces. Never write, copy, or adapt a `ConversationMessageDefinition` by hand, including by copying the shape of an existing one: the builder owns the required layout, `AutoResponse` type, and `Title` constant. If the builder skill is not available, stop and tell the user; do not fall back to hand-writing.
+
+When adding to an existing channel, retrieve it first and keep **one** `automatedResponses` block per `type`. A second block of the same type fails the deploy with `duplicate value found: MessagingChannelId`; the cause is the duplicate block, not the component.
+
+Checks:
+- [ ] Every type was offered, and each answer (accepted or declined) was recorded.
+- [ ] `OptOutConfirmation`/`HelpResponse`: `TextResponse` shape with `language` + `response`, special characters XML-escaped.
+- [ ] Every other type: `MessageDefinition` shape with `messageDefinitionName` set and `language`/`response` both absent.
+- [ ] `messageDefinitionName` references a `ConversationMessageDefinition` that already exists in the org (otherwise: "reference not found" — build it with `conversation-message-definition-builder` first).
+- [ ] `responseTimeoutInMins` (4-30) appears only on `EndUserIdleResponse`/`EndUserInactiveResponse`, and on `EndUserIdleResponse` is less than `endUserIdleTimeOut`.