forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-digital-engagement-channel-configure
service-digital-engagement-channel-configure
VerifiedConfigures 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.
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
MessagingChannelmetadata with Omni-Channel Flow routing, Omni-Channel Queue routing, User 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 — useservice-digital-engagement-deployment-configure), creating permission sets for messaging (useplatform-permission-set-generate), configuring the Embedded Service Code Snippet
Entry points and transport
- Delegated (
context.calledFrom == "service-onboarding"): use the approvedvaluesand ask nothing for changes the plan row describes; confirm drift on an existing channel with the user (step 3a). Returnfailednaming any missing required key. Standalone (nocontext): ask for the Inputs below. - Shell safety: org alias and bot name must match
^[A-Za-z0-9_.@+-]+$before use in a command; otherwise stop and ask (delegated:failed). Pass the channel label single-quoted, escaping any'as'\''. - Transport A (primary): headless-360 MCP
dispatch/dispatch_readonlyon/headless/metadata. Transport B: thesfcommands below, only where a probe shows Transport A unavailable.
Details: references/onboarding_contract.md (§1 entry points, §2 transport, §3 pre-scan, §5 result).
Inputs
Standalone: ask for anything not already clear. Delegated: take values.
- Channel name:
masterLabeland file name (<Name>.messagingChannel-meta.xml) - Routing type:
Queue,Flow,User, orAgentforceServiceAgent - Routing target: developer name of the queue, flow, user, or ASA bot
- Fallback queue (Flow and ASA): developer name for escalation. Routing config (User):
QueueRoutingConfigDeveloperName - User verification: JWT-based identity verification (default
false, soauthModeUnAuth).truemakes anAuthchannel; a keyset name is optional (with one, also anauthIdentifier, a free-form label defaulting to the file name). Creating keys is a separate setup - Pre-chat fields (optional): which fields and types
Apply every other default from references/channel_settings.md unless the user specifies otherwise.
Workflow
Run in order; step 3a may jump to step 15 or Phase 4. All SOQL below: Transport A dispatch_readonly first, sf data query as fallback.
Phase 1 — Gather Context
-
Verify org API version — run
scripts/check-api-version.sh 67.0 '<org-alias>'(skip it when Transport A is in use). Exit 1 = org below 67.0: stop and relay the script's next step (delegated:failed). Exit 2 = version could not be read: warn that it is unverified and continue; the deploy confirms it. Createsfdx-project.jsonin the output folder only if none exists, withsourceApiVersionset to the script'sORG_API_VERSION(67.0 if exit 2). -
Collect inputs — standalone: ask for the Inputs. Delegated: from
values. Then probe transport with a read-onlyGETofMessagingChannel(contract §2). -
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 and end your turn; no record update or deploy until the user continues. Delegated: confirm the drift with the user first (contract §3). This applies to any change to an existing channel, however small, and naming the exact change in the request is not consent. If sessionHandlerType changes, also follow references/routing_transitions.md.
-
Verify routing target exists — skip when step 3a ended in
already-configuredor activate-only, so a re-run never creates a queue. Names must match^[A-Za-z0-9_.@+-]+$before they go into a query. Confirm the routing target exists with the lookup inreferences/routing_transitions.md→ Target lookups (also the fallback queue for Flow and ASA, and the routing config for User).If a target is not found, never write its metadata here. Delegated — return
failednaming the missing target. Standalone — tell the user which target is missing and ask whether to create it. A queue or routing config: on yes, hand off to the owning skill in Cross-Skill Integration with an explicit name, then resume at step 4; on no, stop. If that skill is unavailable or returnsblocked, stop and tell the user what to create — never write the queue or routing config yourself. A flow, user or bot has no owning skill here: stop and tell the user to create it. A new queue needs aQueueRoutingConfig, or sessions fail with "Agents are not available. Try again later" even though the channel deploys and activates. -
Read the channel settings reference — load
references/channel_settings.mdto understand all available configuration options and their valid values.
Phase 2 — Generate Metadata
-
Read the metadata template — new channel: load
assets/messaging_channel_template.xmlas the starting structure. Existing channel (3a): start from its current document (Transport AGETxmlRep; Transport Bsf project retrieve start -m MessagingChannel:<Name>) and change only the targeted elements, so pre-chat, responses, and authorizations survive. -
Apply routing configuration — set
sessionHandlerTypeand the corresponding handler field:Routing Type sessionHandlerTypeRequired Fields Omni-Channel Queue QueuesessionHandlerQueueOmni-Channel Flow FlowsessionHandlerFlow+sessionHandlerQueue(fallback)User UsersessionHandlerUser(username) +queueRoutingConfig; nosessionHandlerQueueAgentforce Service Agent AgentforceServiceAgentsessionHandlerQueue(fallback) +sessionHandlerAsa(bot dev name — required, see v67 note below)For ASA,
<sessionHandlerAsa>is required and the bot must be Active; seereferences/routing_transitions.md→ Agentforce Service Agent. -
Apply user verification — not enabled: set
embeddedConfig.authModetoUnAuthand omit<messagingAuthorizations>. Enabled: followreferences/user_verification.md(add<messagingAuthorizations>only for a keyset name the user gave; never invent one, and without one still writeAuth). -
Configure embedded settings — populate
<embeddedConfig>perreferences/channel_settings.md:anonymousUserJwtExpirationTimefor UnAuth,verifiedUserJwtExpirationTimefor Auth.
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".
9b. Write automated responses (only if requested) — for every type except OptOutConfirmation and HelpResponse, write exactly <autoResponseContentType>MessageDefinition</autoResponseContentType>, <messageDefinitionName> (the CMD DeveloperName) and <type> directly under <automatedResponses>. There is no <response> wrapper and no <conversationMessageDefinition> element.
-
Configure messaging keywords — generate
<messagingKeywords>elements (each has<keyword>s,<keywordType>,<language>; never<type>):OptOuttype with individual<keyword>elements: cancel, end, quit, stop, stopall, unsubscribeHelptype with<keyword>: help
-
Apply standard parameters — if the user needs standard pre-chat fields, follow
references/prechat_params.md→ Standard parameters. -
Apply custom parameters — if the user needs pre-chat data collection, follow
references/prechat_params.md→ Custom parameters (parameterDataTypeis alwaysString). -
Generate the file — produce the
.messagingChannel-meta.xmlfile following the template structure. Place at the path the user specifies, or default to<source-path>/messagingChannels/<ChannelName>.messagingChannel-meta.xmlunder the project's metadata source path.
Phase 3 — Deploy and Activate
-
Write the channel — if 3a found a routing-type change, first run
references/routing_transitions.mdProcedure steps 1–3; if the write fails, run its step 4 restore. Transport A:POSTto create,PUTthe full document to update (a minimal PUT dropsembeddedConfig); checkresults[].success, then re-GET. Transport B:sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias> -
Activate the channel — after a successful write, activate the messaging channel (
IsActiveis not part of the metadata). Transport A: sObject update{"IsActive": true}throughdispatch. Transport B:sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>
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.
Phase 4 — Validate
-
Verify against checklist — confirm all items in the Verification Checklist below pass before presenting output.
-
Report — delegated: return the contract §5 result and stop. Standalone: continue.
-
Present output (standalone) — in a few lines: confirm the channel is created and its activation status, and list each setting the user asked for with its final value, whatever field it is. Say everything else uses the defaults, without listing them. Give transport details, file paths and record Ids only after a failure or if asked. Then offer next steps:
- Automated responses — ask which messages the user wants using the Setup labels per
references/channel_settings.md→ "Setup Prompts: Automated Responses", then redeploy. - reCAPTCHA — not settable by this skill; say this skill does not set or check it and offer the admin handoff in
references/recaptcha_handoff.md.
- Automated responses — ask which messages the user wants using the Setup labels per
Rules / Constraints
| Constraint | Rationale |
|---|---|
| File name serves as the channel API name | No channelPlatformKey field in the XML body |
sessionHandlerType must match the handler fields present | Setting Queue but populating sessionHandlerFlow causes deployment error |
Flow routing requires both sessionHandlerFlow and sessionHandlerQueue | Queue is the mandatory fallback for human escalation |
User routing requires sessionHandlerUser and queueRoutingConfig, and no sessionHandlerQueue | The platform rejects a fallback queue on User routing |
masterLabel max 40 characters | Platform limit on channel labels |
File name must match ^[a-zA-Z][a-zA-Z0-9_]*$ | API name format enforced by Metadata API |
allowedFileTypes is a comma-separated string with no spaces | Not a nested list or array |
keyword elements are individual — one per trigger word | Not a comma-separated list |
customParameters need name, masterLabel, parameterDataType, and externalParameterName | Incomplete parameters fail silently |
File extension is .messagingChannel-meta.xml | Metadata API uses this specific extension |
Do not hardcode file paths — respect sfdx-project.json package directories | Customer orgs customize source paths |
| Channel must be activated after deployment | Channels are inactive by default — messages won't route until activated |
isSynchronousChatEnabled defaults to false; can only be true for UnAuth channels upon user request | Platform rejects "You can't enable Session-Based Chat for verified users" for Auth channels |
Gotchas
| Issue | Resolution |
|---|---|
| Routing-type change fails with a fallback-queue or "Only a Queue or Flow Routing Method…" error | The old type's fields are still set; see references/routing_transitions.md |
| Channel name conflicts with existing channel | Check org for existing channels; file name must be unique |
| Queue not found on deploy | Ensure the referenced queue exists and has MessagingSession as a queueSobject type |
| Channel deploys and activates fine, but widget shows "Agents are not available. Try again later." at session start | The queue has no QueueRoutingConfig — this is silent at deploy time. Check SELECT QueueRoutingConfigId FROM Group WHERE Id='<QUEUE_ID>'; if null, create one with service-omni-queue-routing-config-deploy |
| Omni-Channel Flow not found on deploy | Ensure the referenced flow exists and is active before deploying the channel |
| ASA bot reference invalid | Bot must be published and active; use exact developer name from BotDefinition metadata |
ASA channel deployed but SessionHandlerId is null after deploy | Bot was not Active at deploy time — run sf agent activate, confirm BotVersion.Status = Active, then redeploy |
| JWT verification not working | The keyset (PublicKeyCertificateSet) named in messagingAuthorizations must exist in the org and match the token's kid and issuer |
| 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 |
Verification Checklist
Universal, Verification, Config, and Keyword Checks
- File name matches
^[a-zA-Z][a-zA-Z0-9_]*$,masterLabelis 40 characters or fewer,messagingChannelTypeisEmbeddedMessaging? -
embeddedConfig.authModeisAuthwhen verification is enabled,UnAuthwhen not, with the matching JWT expiration set in range (references/channel_settings.md)? -
chatAbandonmentTimeoutis a positive integer,allowedFileTypesis comma-separated with no spaces,maxFileSizeis 1-5 MB? - An
OptOutkeyword is defined, keywords are individual<keyword>elements, andlanguageis set on each keyword block? - Session inactivity / automated responses (only if requested) checked against
references/channel_settings.md?
Routing Checks
- Exactly one
sessionHandlerTypevalue is set (Queue,Flow,User, orAgentforceServiceAgent)? - Queue:
sessionHandlerQueuein the XML? Flow:sessionHandlerFlowplussessionHandlerQueueas fallback? User:sessionHandlerUserplusqueueRoutingConfig, nosessionHandlerQueue? ASA: bothsessionHandlerQueueandsessionHandlerAsa? - ASA: step 15a run, with
SessionHandlerIdandFallbackQueueIdnon-null after the deploy? - The routing target references an existing entity in the org?
Activation Checks
- Was the channel deployed successfully?
- Was the channel activated after deployment (
IsActive=true)?
Cross-Skill Integration
| Need | Delegate to |
|---|---|
| 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 |
| Creating the routing or fallback queue | service-omni-queue-deploy skill |
Creating the QueueRoutingConfig a queue or User routing needs | service-omni-queue-routing-config-deploy skill |
Reference File Index
| File | When to read |
|---|---|
references/onboarding_contract.md | Delegated mode (context.calledFrom == "service-onboarding"), org writes (transport), module registration |
assets/messaging_channel_template.xml | Before generating — use as the starting structure |
references/channel_settings.md | When configuring channel options beyond defaults |
references/routing_transitions.md | Changing a channel's routing type, or looking up routing targets |
references/user_verification.md | The user turns user verification (Auth mode) on |
references/prechat_params.md | The user needs standard or custom pre-chat parameters |
references/recaptcha_handoff.md | The user asks about reCAPTCHA / captcha, or at the end of standalone output |
scripts/check-api-version.sh | Phase 1 — verify org API version meets the passed minimum (67.0) |
scripts/normalize-channel-name.sh | Phase 1 — derive file API name from channel label |
examples/omni_flow_channel.xml, omni_queue_channel.xml, user_channel.xml, asa_agent_channel.xml, auth_queue_channel.xml (Auth with keyset) | To verify output for Flow, Queue, User, or Agentforce Service Agent routing |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |