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

Entry points and transport

• Delegated (context.calledFrom == "service-onboarding"): use the approved values, ask nothing, and return failed naming any missing required key. Standalone (no context): run Clarifying Questions.
• Transport A (primary): headless-360 MCP dispatch / dispatch_readonly on /headless/metadata. Transport B: the sf commands below, only where a probe shows Transport A unavailable.

Details: references/onboarding_contract.md (§1 entry points, §2 transport, §3 pre-scan, §5 result).

Clarifying Questions

Before generating, ask the user if not already clear (standalone only):

• 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 — standalone: per Clarifying Questions. Delegated: from values. Then probe transport with a read-only GET of MessagingChannel (contract §2).

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

3a. Pre-scan — GET MessagingChannel by the step 3 name (contract §3): none → create; matches and active → no write, already-configured, skip to Phase 4; matches but inactive → activate only (step 15); differs → announce each change, then write the full document (standalone: ask first).

4. Verify routing target exists — skip when step 3a ended in already-configured or activate-only, so a re-run never creates a queue. 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: standalone — inform the user and ask whether to create it. Delegated — return failed naming the missing target; never create it. If the standalone user confirms creating:

   • For Queue: generate a .queue-meta.xml with MessagingSession as the queueSobject type and deploy it before the channel. A new queue needs a QueueRoutingConfig, or sessions fail with "Agents are not available. Try again later" even though the channel deploys and activates. Right after the queue deploys, resolve or create one per service-agentforce-channel-configure's references/queue-resolution.md Step 4 — do not defer it.
   • For Flow/User/ASA: inform the user that the flow, user, or bot must be created separately (out of scope for this skill)

5. Read the channel settings reference — load references/channel_settings.md to understand all available configuration options and their valid values.

Phase 2 — Generate Metadata

6. Read the metadata template — load assets/messaging_channel_template.xml as the starting structure.

7. Apply routing configuration — set sessionHandlerType and the corresponding handler field:

   Routing Type	sessionHandlerType	Required Fields
   Omni-Channel Queue	Queue	sessionHandlerQueue
   Omni-Channel Flow	Flow	sessionHandlerFlow + sessionHandlerQueue (fallback)
   User	User	sessionHandlerUser + sessionHandlerQueue (fallback)
   Agentforce Service Agent	AgentforceServiceAgent	sessionHandlerQueue (fallback) + sessionHandlerAsa (bot dev name — required, see v67 note below)

   v67 note — <sessionHandlerAsa> is required (omitting it fails with "Missing required Agentforce Service Agent"); the deploy then binds SessionHandlerId, no PATCH needed. The bot must be Active first: run sf agent activate -o <org> --api-name <BotDevName> and confirm BotVersion.Status = Active.

8. Apply user verification — if enabled, set embeddedConfig.authMode to Auth and include <messagingAuthorizations>. If not enabled, set embeddedConfig.authMode to UnAuth and omit <messagingAuthorizations>.

9. Configure embedded settings — populate <embeddedConfig> with:

   • allowedFileTypes — comma-separated file extensions (no spaces)
   • anonymousUserJwtExpirationTime — JWT expiration in minutes (required for UnAuth)
   • verifiedUserJwtExpirationTime — JWT expiration in minutes (required for Auth)
   • chatAbandonmentTimeout — minutes before abandoned conversation cleanup
   • isAbandonedChatsEnabled — enable abandoned chat detection
   • isAttachmentUploadEnabled — file upload support
   • isEstimatedWaitTimeEnabled — show estimated wait time
   • isFallbackMessageEnabled — fallback when agents unavailable
   • isFileAttachmentExtUnrestricted — allow any file extension
   • isSaveTranscriptEnabled — save conversation transcripts
   • maxFileSize — maximum attachment size in MB

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. 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/.

Phase 3 — Deploy and Activate

14. Write the channel — Transport A: POST to create, PUT the full document to update (a minimal PUT drops embeddedConfig); check results[].success, then re-GET. Transport B:

    sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias>
    

    Copy

15a. ASA routing only — verify the bind landed (skip for Queue, Flow, User):

```bash
sf data query -o <org> --json \
  -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<CHANNEL_DEV_NAME>'"
```

Both must be non-null; if not, check both handler elements were in the XML and the bot was Active before the deploy.

15. Activate the channel — after a successful write, activate the messaging channel (IsActive is not part of the metadata). Transport A: sObject update {"IsActive": true} through dispatch. Transport B: bash sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>

Phase 4 — Validate

16. Verify against checklist — confirm all items in the Verification Checklist below pass before presenting output.

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.

Rules / Constraints

Gotchas

Verification Checklist

Universal Checks

• Does the file name match ^[a-zA-Z][a-zA-Z0-9_]*$?
• Is masterLabel 40 characters or fewer?
• Is messagingChannelType set to EmbeddedMessaging?

Routing Checks

• Is exactly one sessionHandlerType value set (Queue, Flow, User, or AgentforceServiceAgent)?
• For Queue routing: is sessionHandlerQueue in the XML?
• For Flow routing: is sessionHandlerFlow in the XML, plus sessionHandlerQueue as fallback?
• For User routing: is sessionHandlerUser in the XML, plus sessionHandlerQueue as fallback?
• For ASA routing: are both sessionHandlerQueue and sessionHandlerAsa in the XML?
• For ASA routing: was step 15a run? Are SessionHandlerId and FallbackQueueId non-null after the deploy?
• Does the routing target reference an existing entity in the org?

User Verification Checks

• If verification is enabled, is embeddedConfig.authMode set to Auth?
• If verification is disabled, is embeddedConfig.authMode set to UnAuth?

Embedded Config Checks

• Is chatAbandonmentTimeout a positive integer (minutes)?
• Is allowedFileTypes a comma-separated string with no spaces?
• Is maxFileSize a value between 1-5 MB?
• 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?

Keyword Checks

• Is there at least an OptOut keyword type defined?
• Are keywords individual <keyword> elements (not comma-separated)?
• Is language set on each keyword block?

Activation Checks

• Was the channel deployed successfully?
• Was the channel activated after deployment (IsActive=true)?

Output Expectations

Deliverables:

• Messaging Channel metadata: <source-path>/messagingChannels/<ChannelName>.messagingChannel-meta.xml

File structure follows the template in assets/messaging_channel_template.xml.

Cross-Skill Integration

Reference File Index