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), publishing deployments (Connect API post-step), creating Experience Sites (Connect API prerequisite for Web type)

Clarifying Questions

Before generating, ask the user if not already clear:

• 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 for masterLabel and the API name
• 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".

1. Determine operation — ask whether the user wants to create a new deployment or update an existing one.

1. Collect inputs — gather deployment name, type, and channel name per Clarifying Questions above.

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

Phase 2A — Create New Deployment

Use this path when the operation is create.

1. Determine API method by type:

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

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

1. 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/connectapicreation.md for the Connect API payload and instructions.

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

1. 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: ``bash sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDEDSERVICECONFIGID>" -X POST -o <org-alias> ` To obtain the EMBEDDEDSERVICECONFIGID: `bash sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENTNAME>'" --target-org <org-alias> ` - Generate code snippet for integration — see references/codesnippet.md`

Phase 2B — Update Existing Deployment (Metadata API)

Use this path when the operation is update.

1. Retrieve the existing deployment — retrieve the current EmbeddedServiceConfig metadata from the org before making changes:

``bash sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENTNAME> --target-org <org-alias> ` Use the retrieved file as the starting structure. If retrieval is not possible, load assets/esdwebupdatetemplate.xml` as a fallback reference.

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

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

1. 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/brandingandtooling.md for the Tooling API steps to update individual properties.

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

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

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

1. 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: ``bash sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDEDSERVICECONFIGID>" -X POST -o <org-alias> ` To obtain the EMBEDDEDSERVICECONFIGID: `bash sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENTNAME>'" --target-org <org-alias> ` - Generate code snippet for integration — see references/codesnippet.md`

Phase 3 — Validate

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

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