Configuring Embedded Messaging Deployment

Configures EmbeddedServiceConfig metadata for Salesforce Messaging for In-App and Web (MIAW). Supports two distinct workflows: creating new deployments via Connect API and updating existing deployments via Metadata API.

Scope

• In scope: Creating new Embedded Service Deployments (API, Mobile, Web types) via Connect API; updating existing deployments with forms, branding, channel settings, and features via Metadata API; generating EmbeddedServiceConfig XML for updates
• Out of scope: Creating the messaging channel itself (use service-digital-engagement-channel-configure), generating the website code snippet (offered only as a next step, see references/code_snippet.md), creating Experience Sites (Connect API prerequisite for Web type)

Entry points: delegated or standalone

Decide this before asking anything.

• Delegated — the invocation carries { values, context } with context.calledFrom == "service-onboarding". The admin already approved values in the onboarding plan. Ask nothing; skip Clarifying Questions. If a required key is missing, stop and return failed naming it — do not guess.
• Standalone — no context. Run Clarifying Questions as written.

Both paths run the same pre-scan, write and validate steps. Full contract (payload, wording rules, result shape, registration entry): references/onboarding_contract.md.

Transport

Org reads and writes go through the headless-360 MCP dispatch / dispatch_readonly tools on /services/data/vXX.0/headless/metadata (Transport A, primary). Use the sf CLI (Transport B) only for a type/verb that a read-only probe shows is not onboarded, or when the MCP is unavailable. Probe each type separately — never infer onboarding from a different type. Details, the GET → modify → full-document PUT rule, and the credential trap are in references/onboarding_contract.md §2. The sf commands in the steps below are the Transport B form. Exception: Web create always uses the sf CLI (step 17a).

Clarifying Questions

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

• Create or update? Are you creating a new deployment or updating an existing one?
• Deployment type? API (headless), Mobile (native apps), or Web (browser widget)?
• Channel name? What is the channelPlatformKey of the messaging channel to associate?
• For create: What should the deployment be named?
• For update: What features to configure? (pre-chat forms, business hours, T&C, UI toggles)
• For update (Web): What is the Experience Site name? Branding overrides needed?

Required Inputs

Gather or infer before proceeding:

• Operation: create or update
• Deployment type: API, Mobile, or Web
• Deployment name: Used as masterLabel. Derive the API name (fullName / DeveloperName, Connect name) from it: replace each run of characters other than letters and digits with _, then trim leading/trailing _ (Acme Support Chat → Acme_Support_Chat). The result must match ^[a-zA-Z][a-zA-Z0-9_]*$. Use the API name for every lookup and write
• Channel name: The channelPlatformKey of the associated messaging channel

For update operations additionally:

• Site name (Web only): The Experience Site name (format ESW_<name>_<timestamp>)
• Branding name (optional): Reference to existing BrandingSet
• Pre-chat form fields (optional): Field names and required status
• Business hours (optional): Name of existing BusinessHours record

Defaults unless specified:

• isEnabled: true
• deploymentFeature: EmbeddedMessaging

Workflow

All steps are sequential. Do not skip or reorder. Branch based on the operation type.

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. Determine operation — standalone: ask whether the user wants to create a new deployment or update an existing one. Delegated: taken from values.operation, then confirmed by the pre-scan (step 4a).

3. Collect inputs — standalone: gather deployment name, type, and channel name per Clarifying Questions above. Delegated: bind them from values; stop with failed if deploymentName, deploymentType or channelName is missing.

3a. Probe transport — read-only GET of EmbeddedServiceConfig via dispatch_readonly. Onboarded → Transport A. UNSUPPORTED_OPERATION or MCP unavailable → Transport B for that call. See references/onboarding_contract.md §2.

4. Read deployment settings reference — load references/deployment_settings.md to understand all available configuration options.

4a. Pre-scan — using the step 3a read, look for a deployment whose API name is the one derived from deploymentName (Required Inputs):

• none → operation is create (Phase 2A)
• exists and every targeted field already matches → make no write; return already-configured (delegated) or say so plainly (standalone). Skip to Phase 3
• exists with differences → operation is update (Phase 2B); announce each change, then write (standalone: ask for a yes first)
• exists but linked to a different channel → standalone: ask before repointing; delegated: return failed

Standalone with an existing deployment: offer no change / override / add to existing.

Phase 2A — Create New Deployment

Use this path when the operation is create.

5. Determine API method by type:

   Deployment Type	Creation Method	Prerequisites
   API	Metadata API deploy	Channel must exist
   Mobile	Metadata API deploy	Channel must exist
   Web	Connect API	Channel must exist + Experience Site required

6. For API/Mobile types — read the template assets/esd_api_mobile_template.xml and generate the EmbeddedServiceConfig XML with:

   • deploymentType set to API or Mobile
   • deploymentFeature set to EmbeddedMessaging
   • All defaults applied

7. For Web type — inform the user that Web deployments require Connect API for initial creation because of a circular dependency between Network and CustomSite. Read references/connect_api_creation.md for the Connect API payload and instructions.

8. Generate output — produce the .EmbeddedServiceConfig-meta.xml file (for API/Mobile) or Connect API instructions (for Web).

9. Present output and next steps — show the generated file and summarize what was configured. Recommend as next steps:

   • Publish the deployment via Connect API to make it live:

     sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -b '{}' -o <org-alias>
     

     To obtain the EMBEDDED_SERVICE_CONFIG_ID:

     sf data query --use-tooling-api --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
     

   • Generate code snippet for integration — see references/code_snippet.md

Phase 2B — Update Existing Deployment (Metadata API)

Use this path when the operation is update.

10. Retrieve the existing deployment — take the current EmbeddedServiceConfig from the org before making changes. Transport A: the xmlRep from the step 3a/4a GET. Transport B:

    sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>
    

    Use it as the starting structure — the update is always a full document, never a minimal payload (omitted inline blocks can be silently cleared). If retrieval is not possible, load assets/esd_web_update_template.xml as a fallback reference.

11. Apply messaging channel settings — configure <embeddedServiceMessagingChannel> with:

    • messagingChannel — the channel's channelPlatformKey
    • shouldShowAgentforceTagline — Agentforce branding
    • shouldShowDeliveryReceipts — delivery receipts
    • shouldShowEmojiSelection — emoji picker
    • shouldShowReadReceipts — read receipts
    • shouldShowTypingIndicators — typing indicators
    • shouldStartNewLineOnEnter — Enter key behavior
    • isChatInvitationCustomizable / isInvitationEnabled — chat invitation settings

12. Apply pre-chat forms — if the user needs pre-chat data collection, generate <embeddedServiceForms> with <embeddedServiceFormFields> elements containing embeddedServiceFormFieldName and isRequired.

13. Apply branding customization (Web only) — a BrandingSet is automatically created with defaults when the deployment is created via Connect API. If the user wants to override specific branding properties (colors, fonts, dimensions), read references/branding_and_tooling.md for the Tooling API steps to update individual properties.

14. Apply invitation (Web only) — if the user wants the widget to proactively invite visitors based on conditions:

    • Set isInvitationEnabled to true in <embeddedServiceMessagingChannel>
    • Generate repeatable <embdMsgChannelInvitationConditions> elements with sequence, conditionType, operand, value, and optionally customVariableName
    • Update the formula field in <embeddedServiceMessagingChannel> to reference the condition sequences (e.g., 1 AND 2, 1 OR 2). The formula must be updated whenever conditions are added or removed to stay in sync with the sequence numbers
    • See references/deployment_settings.md for available condition types and operators

15. Apply additional settings:

    • isTermsAndConditionsEnabled / isTermsAndConditionsRequired — T&C in pre-chat
    • Do NOT update site — the site name is auto-generated during creation and must never be modified

16. Generate the file — produce the .EmbeddedServiceConfig-meta.xml file at the path the user specifies, or default to EmbeddedServiceConfig/ in the project's metadata source path.

17. Present output and next steps — show the generated file and summarize what was configured. Recommend as next steps:

    • Publish the deployment via Connect API to make changes live:

      sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -b '{}' -o <org-alias>
      

      To obtain the EMBEDDED_SERVICE_CONFIG_ID:

      sf data query --use-tooling-api --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
      

    • Generate code snippet for integration — see references/code_snippet.md

Phase 2C — Apply to the org

Runs for both Phase 2A and 2B, except when the pre-scan returned already-configured. Standalone: confirm before writing. Delegated: the plan approval is the confirmation; still announce each write.

17a. Write the deployment — - Web create: Connect API (see references/connect_api_creation.md) via sf api request rest — always, not dispatch (MCP dispatch fails with INTERNAL_ERROR during site creation). - API/Mobile create: Transport A POST EmbeddedServiceConfig (body carries type, fullName, xmlRep); Transport B sf project deploy start. - Update: Transport A PUT of the full document; Transport B sf project deploy start. Check results[].success, not just HTTP status. On failure stop and report the step — no silent retry.

17b. Re-read and diff — GET the component again and confirm every intended field landed and no inline block (embeddedServiceMessagingChannel, forms) was dropped.

17c. Publish (Web only, only if something was written) — dispatch POST on the fully-qualified publish path; if it returns a path/route error, run the sf publish command from the next-steps block above. Skip after a Web create alone when the create response has isPublishSuccess: true — the create already published.

Phase 3 — Validate

18. Verify against checklist — confirm all items in the Verification Checklist below pass.

19. Report — delegated: return { "status": "success" | "already-configured" | "failed", "errorMessage": "...", "outputs": { ... } } (shape in references/onboarding_contract.md §5). Standalone: the same outcome in plain language.

Rules / Constraints

Gotchas

Verification Checklist

Universal Checks

• Is deploymentType one of API, Mobile, or Web?
• Is masterLabel populated and unique?
• Does messagingChannel reference an existing channel?
• Is deploymentFeature set to EmbeddedMessaging?
• Is isEnabled set to true?

Web Type Checks

• Is site populated with the Experience Site name?
• If branding is configured, does embeddedServiceBrandingName reference an existing BrandingSet?
• Are pre-chat form field names valid (match channel custom parameters)?
• If isInvitationEnabled is true, is formula populated and consistent with all sequence numbers in <embdMsgChannelInvitationConditions>?

API/Mobile Type Checks

• Is siteUrl empty (no site needed)?
• Is deploymentType correctly set to API or Mobile?

Post-Deploy Checks

• Is user reminded to publish (Connect API) for Web deployments?
• Is user reminded to activate components (Tooling API) if messaging components were deployed?

Output Expectations

Deliverables:

• For API/Mobile create: <source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml
• For Web create: Connect API payload and instructions (no XML file)
• For update: <source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml

File structure follows the templates in assets/.

Cross-Skill Integration

Reference File Index