Configures Embedded Messaging Deployments for Messaging for In-App and Web (MIAW). Use when the user needs to create a new embedded messaging deployment from scratch using Connect API with defaults, or update an existing deployment's settings using Metadata API. Produces Connect API request payloads

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 and transport Delegated ( context.calledFrom == "service onboarding" ): use the approved values , ask nothing, and return failed naming any missing required key. Standalone (no context ): run Clarifying Questions. Transport A (primary): headless 360 MCP dispatch / dispatch readonly on /services/data/vXX.0/headless/metadata . Transport B : the sf commands below, only where a probe shows Transport A unavailable. Exception: Web create always uses the sf CLI (step 17a). Details: references/onboarding contract.md (§1 entry points, §2 transport, §3 pre scan, §5 result). 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 pre chat (if requested): the questions in references/prechat forms.md §Inputs to Gather 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): see references/prechat forms.md §Inputs to Gather 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: per Clarifying Questions. Delegated: from values ( deploymentName , deploymentType , channelName required). 3a. Probe transport — read only GET of EmbeddedServiceConfig (contract §2). 4. Read deployment settings reference — load references/deployment settings.md to understand all available configuration options. 4a. Pre scan — look up the deployment by its derived API name (contract §3): none → create (Phase 2A); matches → no write, already configured , skip to Phase 3; differs → update (Phase 2B), announce each change (standalone: ask first); linked to a different channel → standalone: ask before repointing, delegated: failed . Standalone, deployment exists: offer exactly three choices — 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 — API/Mobile: Metadata API deploy. Web: Connect API (creates the Experience Site). All types need the channel to exist. 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 — as in step 17. 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: Use it as the starting structure — the update is always a full document (see Rules). If retrieval is not possible, load assets/esd web update template.xml as a fallback reference. 11. Apply messaging channel settings — in <embeddedServiceMessagingChannel set messagingChannel (the channel's channelPlatformKey ) and the UI toggles ( shouldShow , shouldStartNewLineOnEnter , invitation flags). Include every boolean, even when false ; full list in references/deployment settings.md . Leave each shouldShow / shouldStartNewLineOnEnter at its retrieved value (default false if nothing was retrieved); set one to true only when the user explicitly asks for that feature — never infer it from an example. 12. Apply pre chat forms — pre chat is OFF by default: omit <embeddedServiceForms unless the user asks to collect data before the conversation. If they do, read references/prechat forms.md first and follow it (field attributes, hidden fields, ChoiceList, displayNameFormat , deactivate vs. remove). Before generating , run the checks in its §Validating and Remediating Prerequisites against the retrieved channel. Channel fixes go through service digital engagement channel configure ; never hand edit the channel here. Delta to graft onto a base deployment: examples/esd web prechat fields.xml . 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) — set isInvitationEnabled to true , add <embdMsgChannelInvitationConditions (fields and operators in references/deployment settings.md ), and keep formula (e.g. 1 AND 2 ) in sync with the condition sequence numbers whenever conditions change. 15. Apply additional settings : isTermsAndConditionsEnabled / isTermsAndConditionsRequired — T&C in pre chat site — Web: the retrieved value, unchanged (see Rules); omit for API/Mobile 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 (Web) — only after the user approves, per step 17c 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) — never automatic. Publishing makes the changes live to customers; the deploy only saves a draft. After 17b, stop: summarize what changed, give the plain Setup link <instanceUrl /lightning/setup/EmbeddedServiceDeployments/<EmbeddedServiceConfigId /view so the user can review the draft, and ask whether to publish now. Publish only on an explicit yes in that turn (a "publish" in the original request does not count). Then dispatch POST on the fully qualified publish path; if it returns a path/route error, or on Transport B, run the sf publish command from references/connect api creation.md . Delegated: do not publish; return published: false . Note: a Web create via Connect API publishes by itself ( isPublishSuccess: true ); say so in the plan before creating. Phase 3 — Validate 18. Verify against checklist — confirm all items in the Verification Checklist below pass. 19. Report — delegated: return the contract §5 result. Standalone: the same outcome in plain language. Rules / Constraints Constraint Rationale deploymentType must be API , Mobile , or Web Platform rejects other values Web updates must include site , set to the retrieved value unchanged Site ( ESW <name <timestamp ) is auto generated at creation; the platform rejects a missing or changed value embeddedServiceMessagingChannelName must reference an existing channel Deployment fails if channel doesn't exist File extension is .EmbeddedServiceConfig meta.xml Metadata API uses this specific extension Do not hardcode file paths — respect sfdx project.json package directories Customer orgs customize source paths Do not embed deploy/push commands inside generated files or artifacts Artifacts stay portable; in session writes happen in Phase 2C through the chosen transport Update with the full retrieved document, never a minimal PUT Omitted inline blocks can be silently cleared by the update Gotchas Issue Resolution Branding overrides not applied Use Tooling API to update individual BrandingSet properties after the deployment is created Pre chat form, field, ChoiceList, or displayNameFormat issues See the Gotchas table in references/prechat forms.md Changes not appearing in widget The deploy is a draft until published (step 17c) sf api request rest fails ("No 'mode' found", "Nonexistent flag: url") See references/connect api creation.md §Publishing After Updates Deploy fails with "required field missing" or "upsert failed null" All attributes are mandatory: boolean fields in embeddedServiceMe

service-digital-engagement-deployment-configure