forcedotcom/sf-skills / plugins/builder/service-engagement/skills/service-digital-engagement-deployment-configure
service-digital-engagement-deployment-configure
VerifiedConfigures 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 for new deployments and EmbeddedServiceConfig metadata XML for updates. TRIGGER when the user mentions embedded messaging deployment, embedded service deployment, MIAW deployment, messaging widget setup, chat widget configuration, embedded chat deployment, or references a .EmbeddedServiceConfig-meta.xml file. DO NOT TRIGGER when the user is creating a messaging channel (use service-digital-engagement-channel-configure), configuring legacy Live Agent embedded service, or generating the JavaScript code snippet for website embedding.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.0 KB |
| assets/esd_api_mobile_template.xml | config | 1.4 KB |
| assets/esd_web_update_template.xml | config | 5.7 KB |
| examples/esd_api.xml | config | 1.4 KB |
| examples/esd_mobile.xml | config | 1.4 KB |
| examples/esd_web_full.xml | config | 1.5 KB |
| examples/esd_web_prechat_fields.xml | config | 3.3 KB |
| references/branding_and_tooling.md | markdown | 3.9 KB |
| references/code_snippet.md | markdown | 2.8 KB |
| references/connect_api_creation.md | markdown | 5.1 KB |
| references/deployment_settings.md | markdown | 7.3 KB |
| references/onboarding_contract.md | markdown | 9.1 KB |
| references/prechat_forms.md | markdown | 21.7 KB |
| scripts/check-api-version.shexecutable | script | 1.6 KB |
references/connect_api_creation.md
View on GitHub# Creating Web ESD via Connect API
Web-type Embedded Service Deployments cannot be created via Metadata API due to a circular dependency between Network and CustomSite metadata types. Use Connect API instead.
---
## Prerequisites
1. Digital Experiences must be enabled in the org (Setup > Digital Experiences > Enable)
2. The messaging channel must already exist (need the `messagingChannelId` — the 18-char record ID)
3. Salesforce CLI (`sf`) must be authenticated to the target org
---
## Connect API Endpoint
```text
POST /services/data/vXX.0/connect/embeddedmessaging/deployment/setup
```
Always use the fully-qualified path (minimum `v67.0`). A bare `/connect/...` path is not routed.
### Request Body (Web)
```json
{
"name": "<DEPLOYMENT_API_NAME>",
"masterLabel": "<DEPLOYMENT_LABEL>",
"deploymentType": "Web",
"clientVersion": "WebV2",
"hostDomain": "<HOST_DOMAIN>",
"messagingChannelId": "<MESSAGING_CHANNEL_ID>"
}
```
### Request Body (API / Mobile)
```json
{
"name": "<DEPLOYMENT_API_NAME>",
"masterLabel": "<DEPLOYMENT_LABEL>",
"deploymentType": "API",
"messagingChannelId": "<MESSAGING_CHANNEL_ID>"
}
```
### Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | String | Yes | API name for the deployment (no spaces) |
| `masterLabel` | String | Yes | Display label for the deployment |
| `deploymentType` | String | Yes | `Web`, `API`, or `Mobile` |
| `messagingChannelId` | String | Yes | 18-character record ID of the messaging channel |
| `clientVersion` | String | Web only | Always `WebV2` for enhanced messaging web deployments |
| `hostDomain` | String | Web only | The domain where the widget will be hosted (e.g. `mysite.com`) |
### Using Salesforce CLI (Web)
Always create Web deployments with the CLI. The same call through the headless-360 MCP `dispatch` fails with an
`INTERNAL_ERROR` server error during site creation.
```bash
sf api request rest \
"/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
--method POST \
--body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"Web","clientVersion":"WebV2","hostDomain":"<DOMAIN>","messagingChannelId":"<CHANNEL_ID>"}' \
--target-org <org-alias>
```
### Using Salesforce CLI (API / Mobile)
```bash
sf api request rest \
"/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
--method POST \
--body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"API","messagingChannelId":"<CHANNEL_ID>"}' \
--target-org <org-alias>
```
### Getting the Messaging Channel ID
Query the messaging channel ID by developer name:
```bash
sf data query \
--query "SELECT Id FROM MessagingChannel WHERE DeveloperName = '<CHANNEL_PLATFORM_KEY>'" \
--target-org <org-alias>
```
---
## Response
```json
{
"isSuccess": true,
"embeddedServiceDeploymentId": "0Mbxx0000000001",
"isPublishSuccess": true,
"errorMsg": null
}
```
### Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `isSuccess` | Boolean | Whether the deployment was successfully created |
| `embeddedServiceDeploymentId` | String | 18-character record ID of the created deployment |
| `isPublishSuccess` | Boolean | Whether the deployment was successfully published |
| `errorMsg` | String | Error message if creation or publish failed (null on success) |
Save the `embeddedServiceDeploymentId` — it identifies the deployment for subsequent updates.
---
## Post-Creation Steps
After creating the Web ESD via Connect API:
1. **Update via Metadata API** — deploy `EmbeddedServiceConfig` XML with full configuration (forms, branding, channel settings, T&C)
2. **Publish** — see below
---
## Publishing After Updates
Updates to a Web ESD (branding, forms, labels, settings) stay in draft until published. Publish only after the user approves (SKILL.md step 17c):
```text
POST /services/data/vXX.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>
```
```bash
sf api request rest \
"/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" \
--method POST \
--body '{}' \
--target-org <org-alias>
```
The `--body '{}'` is required: a POST with no body (or `--body ""`) fails in the CLI with
"No 'mode' found in 'body' entry" before any request is sent. The URL is a positional
argument, not a flag (`--url` fails with "Nonexistent flag"), and must be fully qualified
(`/services/data/vXX.0/connect/...`).
To obtain the `EMBEDDED_SERVICE_CONFIG_ID` (a Tooling API object, so `--use-tooling-api` is required):
```bash
sf data query --use-tooling-api \
--query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" \
--target-org <org-alias>
```
---
## Known Limitations
- Site name is auto-generated — cannot be customized during creation
- The site format is always `ESW_<name>_<timestamp>`
- Web ESD creation is not idempotent — calling twice creates duplicate deployments
- Connect API does not support configuring forms, branding, or toggles at creation time — use Metadata API update afterward
- `messagingChannelId` requires querying the record ID (not the developer name)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |