/service-digital-engagement-channel-configure

name: service-digital-engagement-channel-configure
description: "Configures and deploys enhanced chat Messaging Channels for Messaging for In-App and Web (MIAW). Use when the user needs to create, deploy, and activate a messaging channel configured with Omni-Channel Flow, Omni-Channel Queue, User, or Agentforce Service Agent routing. Generates MessagingChannel metadata, deploys it to the target org, and activates the channel with User Verification, pre-chat forms, automated responses, consent settings, and all customizable channel options via Metadata API. TRIGGER when the user mentions messaging channel, MIAW, enhanced chat, in-app messaging, web messaging setup, or references a .messagingChannel-meta.xml file. DO NOT TRIGGER when the user is configuring legacy Live Agent chat, Embedded Service deployments without messaging, or standard Omni-Channel routing rules without a messaging channel."
metadata:
  version: "1.0"
  domains: ["Service"]
  minApiVersion: "67.0"
  relatedSkills:
    - "automation-flow-generate"
    - "platform-permission-set-generate"
    - "service-agentforce-channel-configure"
    - "service-digital-engagement-deployment-configure"
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
    - tool: ["python3"]
      semver: ">=3.8"

Configuring Enhanced Chat Channel

Creates `MessagingChannel` metadata XML for Salesforce Messaging for In-App and Web (MIAW). This skill produces a fully configured enhanced chat channel with routing, user verification, pre-chat, and automated response settings ready for Metadata API deployment.

Scope

• **In scope**: Creating `MessagingChannel` metadata with Omni-Channel Flow routing, Omni-Channel Queue routing, or Agentforce Service Agent (ASA) routing; enabling User Verification; configuring all channel settings (pre-chat forms, automated responses, consent keywords, file attachments, custom parameters)
• **Out of scope**: Creating the referenced Omni-Channel Flow/Queue definitions (use `automation-flow-generate`), creating the Embedded Service Deployment (separate metadata type — use `service-digital-engagement-deployment-configure`), creating permission sets for messaging (use `platform-permission-set-generate`), configuring the Embedded Service Code Snippet

---

Clarifying Questions

Before generating, ask the user if not already clear:

• What is the channel name / label? (used for `masterLabel` and file name)
• What routing type? (Omni-Channel Flow, Omni-Channel Queue, User, or Agentforce Service Agent)
• What is the routing target? (Flow API name, Queue developer name, User ID, or ASA bot name)
• For Flow, User, or ASA routing: What is the fallback queue name?
• Should User Verification be enabled? (defaults to `true` per this skill)
• Are there pre-chat form fields required? If so, which fields and types?

---

Required Inputs

Gather or infer before proceeding:

• **Channel name**: Used for `masterLabel` and the file name (`<Name>.messagingChannel-meta.xml`)
• **Routing type**: One of `Queue`, `Flow`, `User`, or `AgentforceServiceAgent`
• **Routing target**: The developer name of the queue, flow, user, or ASA bot
• **Fallback queue** (Flow, User, and ASA): The developer name of the fallback queue for escalation
• **User verification**: Whether to require JWT-based identity verification (default: `true`)

Defaults unless specified:

• `messagingChannelType`: `EmbeddedMessaging`
• `authMode`: `Auth`
• `chatAbandonmentTimeout`: `5` (minutes)
• `endUserIdleTimeOut`: `5` (minutes)
• `isAttachmentUploadEnabled`: `true`
• `maxFileSize`: `5` (MB)
• `allowedFileTypes`: `bmp,csv,doc,docx,gif,jpg,pdf,png,tiff,txt,xls,xml`
• `anonymousUserJwtExpirationTime`: `360` (minutes, required for UnAuth, range 60-4320)
• `verifiedUserJwtExpirationTime`: `60` (minutes, required for Auth, range 60-240)
• `isAbandonedChatsEnabled`: `false`
• `isSaveTranscriptEnabled`: `false`
• `isFallbackMessageEnabled`: `false`
• `isEstimatedWaitTimeEnabled`: `false`
• `isFileAttachmentExtUnrestricted`: `false`
• `isQueuePositionEnabled`: `false`
• `isSynchronousChatEnabled`: `false`
• `isVoiceModeEnabled`: `false`

---

Workflow

All steps are sequential. Do not skip or reorder.

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. **Collect inputs** — confirm the channel label, routing type, routing target, and verification settings from the user per Clarifying Questions above.

3. **Determine file name** — run `scripts/normalize-channel-name.sh "<LABEL>"` and surface any errors it returns.

4. **Verify routing target exists** — query the org to confirm the referenced routing target exists:

• For Queue: `sf data query --query "SELECT Id, DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='<QUEUE_NAME>'" --target-org <org-alias>`
• For Flow: `sf data query --query "SELECT Id, ApiName FROM FlowDefinitionView WHERE ApiName='<FLOW_NAME>' AND IsActive=true" --target-org <org-alias>`
• For User: `sf data query --query "SELECT Id, Username FROM User WHERE Id='<USER_ID>' AND IsActive=true" --target-org <org-alias>`
• For ASA: `sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName='<BOT_NAME>'" --target-org <org-alias>`
• Also verify the fallback queue exists (required for Flow, User, and ASA routing)

If any target is not found, inform the user and ask whether to create it. If the user confirms:

• For Queue: generate a `.queue-meta.xml` with `MessagingSession` as the `queueSobject` type and deploy it before the channel. **A new queue is unusable for routing without a `QueueRoutingConfig` — a channel deployed against a queue with none fails at session-start with "Agents are not available. Try again later," even though the channel itself deploys and activates cleanly.** I