Skip to content

forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-digital-engagement-channel-configure

service-digital-engagement-channel-configure

Verified

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.

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, 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 — 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 and ask nothing for changes the plan row describes; confirm drift on an existing channel with the user (step 3a). Return failed naming any missing required key. Standalone (no context): 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_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).


Inputs

Standalone: ask for anything not already clear. Delegated: take values.

  • Channel name: masterLabel and file name (<Name>.messagingChannel-meta.xml)
  • Routing type: Queue, Flow, User, or AgentforceServiceAgent
  • Routing target: developer name of the queue, flow, user, or ASA bot
  • Fallback queue (Flow and ASA): developer name for escalation. Routing config (User): QueueRoutingConfig DeveloperName
  • User verification: JWT-based identity verification (default false, so authMode UnAuth). true makes an Auth channel; a keyset name is optional (with one, also an authIdentifier, 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

  1. 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. Create sfdx-project.json in the output folder only if none exists, with sourceApiVersion set to the script's ORG_API_VERSION (67.0 if exit 2).

  2. Collect inputs — standalone: ask for the Inputs. 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 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.

  1. Verify routing target exists — skip when step 3a ended in already-configured or 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 in references/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 failed naming 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 returns blocked, 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 a QueueRoutingConfig, or sessions fail with "Agents are not available. Try again later" even though the channel deploys and activates.

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

Phase 2 — Generate Metadata

  1. Read the metadata template — new channel: load assets/messaging_channel_template.xml as the starting structure. Existing channel (3a): start from its current document (Transport A GET xmlRep; Transport B sf project retrieve start -m MessagingChannel:<Name>) and change only the targeted elements, so pre-chat, responses, and authorizations survive.

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

    Routing TypesessionHandlerTypeRequired Fields
    Omni-Channel QueueQueuesessionHandlerQueue
    Omni-Channel FlowFlowsessionHandlerFlow + sessionHandlerQueue (fallback)
    UserUsersessionHandlerUser (username) + queueRoutingConfig; no sessionHandlerQueue
    Agentforce Service AgentAgentforceServiceAgentsessionHandlerQueue (fallback) + sessionHandlerAsa (bot dev name — required, see v67 note below)

    For ASA, <sessionHandlerAsa> is required and the bot must be Active; see references/routing_transitions.md → Agentforce Service Agent.

  3. Apply user verification — not enabled: set embeddedConfig.authMode to UnAuth and omit <messagingAuthorizations>. Enabled: follow references/user_verification.md (add <messagingAuthorizations> only for a keyset name the user gave; never invent one, and without one still write Auth).

  4. Configure embedded settings — populate <embeddedConfig> per references/channel_settings.md: anonymousUserJwtExpirationTime for UnAuth, verifiedUserJwtExpirationTime for 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.

  1. Configure messaging keywords — generate <messagingKeywords> elements (each has <keyword>s, <keywordType>, <language>; never <type>):

    • OptOut type with individual <keyword> elements: cancel, end, quit, stop, stopall, unsubscribe
    • Help type with <keyword>: help
  2. Apply standard parameters — if the user needs standard pre-chat fields, follow references/prechat_params.md → Standard parameters.

  3. Apply custom parameters — if the user needs pre-chat data collection, follow references/prechat_params.md → Custom parameters (parameterDataType is always String).

  4. Generate the file — produce the .messagingChannel-meta.xml file following the template structure. Place at the path the user specifies, or default to <source-path>/messagingChannels/<ChannelName>.messagingChannel-meta.xml under the project's metadata source path.

Phase 3 — Deploy and Activate

  1. Write the channel — if 3a found a routing-type change, first run references/routing_transitions.md Procedure steps 1–3; if the write fails, run its step 4 restore. 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>
    
  2. 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:

    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

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

  2. Report — delegated: return the contract §5 result and stop. Standalone: continue.

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

Rules / Constraints

ConstraintRationale
File name serves as the channel API nameNo channelPlatformKey field in the XML body
sessionHandlerType must match the handler fields presentSetting Queue but populating sessionHandlerFlow causes deployment error
Flow routing requires both sessionHandlerFlow and sessionHandlerQueueQueue is the mandatory fallback for human escalation
User routing requires sessionHandlerUser and queueRoutingConfig, and no sessionHandlerQueueThe platform rejects a fallback queue on User routing
masterLabel max 40 charactersPlatform 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 spacesNot a nested list or array
keyword elements are individual — one per trigger wordNot a comma-separated list
customParameters need name, masterLabel, parameterDataType, and externalParameterNameIncomplete parameters fail silently
File extension is .messagingChannel-meta.xmlMetadata API uses this specific extension
Do not hardcode file paths — respect sfdx-project.json package directoriesCustomer orgs customize source paths
Channel must be activated after deploymentChannels are inactive by default — messages won't route until activated
isSynchronousChatEnabled defaults to false; can only be true for UnAuth channels upon user requestPlatform rejects "You can't enable Session-Based Chat for verified users" for Auth channels

Gotchas

IssueResolution
Routing-type change fails with a fallback-queue or "Only a Queue or Flow Routing Method…" errorThe old type's fields are still set; see references/routing_transitions.md
Channel name conflicts with existing channelCheck org for existing channels; file name must be unique
Queue not found on deployEnsure 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 startThe 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 deployEnsure the referenced flow exists and is active before deploying the channel
ASA bot reference invalidBot must be published and active; use exact developer name from BotDefinition metadata
ASA channel deployed but SessionHandlerId is null after deployBot was not Active at deploy time — run sf agent activate, confirm BotVersion.Status = Active, then redeploy
JWT verification not workingThe keyset (PublicKeyCertificateSet) named in messagingAuthorizations must exist in the org and match the token's kid and issuer
Custom parameters not collectedname 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 failsSee references/channel_settings.md → "Automated Responses", "Session Settings"
Channel deployed but messages not routingChannel 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_]*$, masterLabel is 40 characters or fewer, messagingChannelType is EmbeddedMessaging?
  • embeddedConfig.authMode is Auth when verification is enabled, UnAuth when not, with the matching JWT expiration set in range (references/channel_settings.md)?
  • chatAbandonmentTimeout is a positive integer, allowedFileTypes is comma-separated with no spaces, maxFileSize is 1-5 MB?
  • An OptOut keyword is defined, keywords are individual <keyword> elements, and language is set on each keyword block?
  • Session inactivity / automated responses (only if requested) checked against references/channel_settings.md?

Routing Checks

  • Exactly one sessionHandlerType value is set (Queue, Flow, User, or AgentforceServiceAgent)?
  • Queue: sessionHandlerQueue in the XML? Flow: sessionHandlerFlow plus sessionHandlerQueue as fallback? User: sessionHandlerUser plus queueRoutingConfig, no sessionHandlerQueue? ASA: both sessionHandlerQueue and sessionHandlerAsa?
  • ASA: step 15a run, with SessionHandlerId and FallbackQueueId non-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

NeedDelegate to
Creating the Omni-Channel Flow for routingautomation-flow-generate skill
Creating permission sets for messaging agentsplatform-permission-set-generate skill
Creating the Embedded Service Deploymentservice-digital-engagement-deployment-configure skill
Creating the ConversationMessageDefinition an automated response referencesconversation-message-definition-builder skill
Creating the routing or fallback queueservice-omni-queue-deploy skill
Creating the QueueRoutingConfig a queue or User routing needsservice-omni-queue-routing-config-deploy skill

Reference File Index

FileWhen to read
references/onboarding_contract.mdDelegated mode (context.calledFrom == "service-onboarding"), org writes (transport), module registration
assets/messaging_channel_template.xmlBefore generating — use as the starting structure
references/channel_settings.mdWhen configuring channel options beyond defaults
references/routing_transitions.mdChanging a channel's routing type, or looking up routing targets
references/user_verification.mdThe user turns user verification (Auth mode) on
references/prechat_params.mdThe user needs standard or custom pre-chat parameters
references/recaptcha_handoff.mdThe user asks about reCAPTCHA / captcha, or at the end of standalone output
scripts/check-api-version.shPhase 1 — verify org API version meets the passed minimum (67.0)
scripts/normalize-channel-name.shPhase 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
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall