Service Digital Engagement Deployment Configure

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/esd_api_mobile_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/connect_api_creation.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/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias> ` To obtain the EMBEDDED_SERVICE_CONFIG_ID: `bash sf data query --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.

1. Retrieve the existing deployment — retrieve the current EmbeddedServiceConfig metadata from the org before making changes: ``bash sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias> ` Use the retrieved file as the starting structure. If retrieval is not possible, load assets/esd_web_update_template.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/branding_and_tooling.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/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias> ` To obtain the EMBEDDED_SERVICE_CONFIG_ID: `bash sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias> ``
• Generate code snippet for integration — see references/code_snippet.md

Phase 3 — Validate