service-digital-engagement-deployment-configure
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseConfiguring Embedded Messaging Deployment
配置嵌入式消息部署
Configures 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.
EmbeddedServiceConfig为Salesforce应用内和网页消息服务(Messaging for In-App and Web,简称MIAW)配置元数据。支持两种独立工作流:通过Connect API创建新部署,以及通过Metadata API更新现有部署。
EmbeddedServiceConfigScope
适用范围
- 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 XML for updates
EmbeddedServiceConfig - Out of scope: Creating the messaging channel itself (use ), publishing deployments (Connect API post-step), creating Experience Sites (Connect API prerequisite for Web type)
service-digital-engagement-channel-configure
- 包含场景:通过Connect API创建新的嵌入式服务部署(API、移动端、网页类型);通过Metadata API更新现有部署的表单、品牌、渠道设置及功能;生成用于更新的XML
EmbeddedServiceConfig - 排除场景:创建消息渠道本身(请使用)、发布部署(Connect API后续步骤)、创建体验站点(网页类型部署的Connect API前置条件)
service-digital-engagement-channel-configure
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 of the messaging channel to associate?
channelPlatformKey - 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?
生成配置前,若信息不明确,请询问用户:
- 创建还是更新? 您是要创建新部署还是更新现有部署?
- 部署类型? API(无头)、移动端(原生应用)还是网页(浏览器小部件)?
- 渠道名称? 要关联的消息渠道的是什么?
channelPlatformKey - 若为创建:部署名称是什么?
- 若为更新:需要配置哪些功能?(预聊天表单、营业时间、条款与条件、UI开关)
- 若为网页类型更新:体验站点名称是什么?是否需要品牌覆盖设置?
Required Inputs
必填输入
Gather or infer before proceeding:
- Operation: or
createupdate - Deployment type: ,
API, orMobileWeb - Deployment name: Used for and the API name
masterLabel - Channel name: The of the associated messaging channel
channelPlatformKey
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 record
BusinessHours
Defaults unless specified:
- :
isEnabledtrue - :
deploymentFeatureEmbeddedMessaging
在开始前收集或推断以下信息:
- 操作类型:(创建)或
create(更新)update - 部署类型:、
API或MobileWeb - 部署名称:用于和API名称
masterLabel - 渠道名称:关联消息渠道的
channelPlatformKey
对于更新操作,还需额外收集:
- 站点名称(仅网页类型):体验站点名称(格式为)
ESW_<name>_<timestamp> - 品牌名称(可选):现有的引用
BrandingSet - 预聊天表单字段(可选):字段名称及必填状态
- 营业时间(可选):现有记录的名称
BusinessHours
默认设置(除非另行指定):
- :
isEnabledtrue - :
deploymentFeatureEmbeddedMessaging
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 — runand report any errors it returns. If the script fails, generate a
scripts/check-api-version.sh 67.0 <org-alias>in the metadata output folder withsfdx-project.json."sourceApiVersion": "67.0" -
Determine operation — ask whether the user wants to create a new deployment or update an existing one.
-
Collect inputs — gather deployment name, type, and channel name per Clarifying Questions above.
-
Read deployment settings reference — loadto understand all available configuration options.
references/deployment_settings.md
-
验证组织API版本 — 运行并报告返回的任何错误。若脚本执行失败,在元数据输出文件夹中生成
scripts/check-api-version.sh 67.0 <org-alias>文件,设置sfdx-project.json。"sourceApiVersion": "67.0" -
确定操作类型 — 询问用户是要创建新部署还是更新现有部署。
-
收集输入信息 — 根据上述澄清问题收集部署名称、类型和渠道名称。
-
读取部署设置参考文档 — 加载以了解所有可用配置选项。
references/deployment_settings.md
Phase 2A — Create New Deployment
阶段2A — 创建新部署
Use this path when the operation is .
create-
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 -
For API/Mobile types — read the templateand generate the
assets/esd_api_mobile_template.xmlXML with:EmbeddedServiceConfig- set to
deploymentTypeorAPIMobile - set to
deploymentFeatureEmbeddedMessaging - All defaults applied
-
For Web type — inform the user that Web deployments require Connect API for initial creation because of a circular dependency between Network and CustomSite. Readfor the Connect API payload and instructions.
references/connect_api_creation.md -
Generate output — produce thefile (for API/Mobile) or Connect API instructions (for Web).
.EmbeddedServiceConfig-meta.xml -
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:
To obtain thebash
sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>:EMBEDDED_SERVICE_CONFIG_IDbashsf 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
- Publish the deployment via Connect API to make it live:
当操作类型为时使用此路径。
create-
根据类型确定API方法:
部署类型 创建方法 前置条件 API Metadata API部署 渠道必须已存在 移动端 Metadata API部署 渠道必须已存在 网页 Connect API 渠道必须已存在 + 需体验站点 -
对于API/移动端类型 — 读取模板并生成
assets/esd_api_mobile_template.xmlXML,包含:EmbeddedServiceConfig- 设置为
deploymentType或APIMobile - 设置为
deploymentFeatureEmbeddedMessaging - 应用所有默认设置
-
对于网页类型 — 告知用户网页部署需要通过Connect API进行初始创建,因为Network和CustomSite之间存在循环依赖。读取获取Connect API负载及说明。
references/connect_api_creation.md -
生成输出 — 生成文件(适用于API/移动端)或Connect API说明(适用于网页)。
.EmbeddedServiceConfig-meta.xml -
展示输出及后续步骤 — 显示生成的文件并总结配置内容。推荐后续步骤:
- 发布部署:通过Connect API使部署生效:
获取bash
sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>的命令:EMBEDDED_SERVICE_CONFIG_IDbashsf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias> - 生成集成代码片段 — 参见
references/code_snippet.md
- 发布部署:通过Connect API使部署生效:
Phase 2B — Update Existing Deployment (Metadata API)
阶段2B — 更新现有部署(Metadata API)
Use this path when the operation is .
update-
Retrieve the existing deployment — retrieve the currentmetadata from the org before making changes:
EmbeddedServiceConfigbashsf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>Use the retrieved file as the starting structure. If retrieval is not possible, loadas a fallback reference.assets/esd_web_update_template.xml -
Apply messaging channel settings — configurewith:
<embeddedServiceMessagingChannel>- — the channel's
messagingChannelchannelPlatformKey - — Agentforce branding
shouldShowAgentforceTagline - — delivery receipts
shouldShowDeliveryReceipts - — emoji picker
shouldShowEmojiSelection - — read receipts
shouldShowReadReceipts - — typing indicators
shouldShowTypingIndicators - — Enter key behavior
shouldStartNewLineOnEnter - /
isChatInvitationCustomizable— chat invitation settingsisInvitationEnabled
-
Apply pre-chat forms — if the user needs pre-chat data collection, generatewith
<embeddedServiceForms>elements containing<embeddedServiceFormFields>andembeddedServiceFormFieldName.isRequired -
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), readfor the Tooling API steps to update individual properties.
references/branding_and_tooling.md -
Apply invitation (Web only) — if the user wants the widget to proactively invite visitors based on conditions:
- Set to
isInvitationEnabledintrue<embeddedServiceMessagingChannel> - Generate repeatable elements with
<embdMsgChannelInvitationConditions>,sequence,conditionType,operand, and optionallyvaluecustomVariableName - Update the field in
formulato reference the condition sequences (e.g.,<embeddedServiceMessagingChannel>,1 AND 2). The formula must be updated whenever conditions are added or removed to stay in sync with the1 OR 2numberssequence - See for available condition types and operators
references/deployment_settings.md
- Set
-
Apply additional settings:
- /
isTermsAndConditionsEnabled— T&C in pre-chatisTermsAndConditionsRequired - Do NOT update — the site name is auto-generated during creation and must never be modified
site
-
Generate the file — produce thefile at the path the user specifies, or default to
.EmbeddedServiceConfig-meta.xmlin the project's metadata source path.EmbeddedServiceConfig/ -
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:
To obtain thebash
sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>:EMBEDDED_SERVICE_CONFIG_IDbashsf 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
- Publish the deployment via Connect API to make changes live:
当操作类型为时使用此路径。
update-
检索现有部署 — 在进行更改前,从组织中检索当前的元数据:
EmbeddedServiceConfigbashsf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>将检索到的文件作为起始结构。若无法检索,加载作为备用参考。assets/esd_web_update_template.xml -
应用消息渠道设置 — 配置,包含:
<embeddedServiceMessagingChannel>- — 渠道的
messagingChannelchannelPlatformKey - — Agentforce品牌标识
shouldShowAgentforceTagline - — 送达回执
shouldShowDeliveryReceipts - — 表情选择器
shouldShowEmojiSelection - — 已读回执
shouldShowReadReceipts - — 输入状态提示
shouldShowTypingIndicators - — 回车键行为
shouldStartNewLineOnEnter - /
isChatInvitationCustomizable— 聊天邀请设置isInvitationEnabled
-
应用预聊天表单 — 若用户需要预聊天数据收集,生成,包含
<embeddedServiceForms>元素,其中包含<embeddedServiceFormFields>和embeddedServiceFormFieldName。isRequired -
应用品牌自定义(仅网页类型) — 当通过Connect API创建部署时,会自动创建带有默认设置的BrandingSet。若用户想要覆盖特定品牌属性(颜色、字体、尺寸),请阅读了解使用Tooling API更新单个属性的步骤。
references/branding_and_tooling.md -
应用邀请设置(仅网页类型) — 若用户希望小部件根据条件主动邀请访客:
- 在中将
<embeddedServiceMessagingChannel>设置为isInvitationEnabledtrue - 生成可重复的元素,包含
<embdMsgChannelInvitationConditions>、sequence、conditionType、operand,以及可选的valuecustomVariableName - 更新中的
<embeddedServiceMessagingChannel>字段以引用条件序列(例如formula、1 AND 2)。每当添加或删除条件时,必须更新公式以与1 OR 2编号保持同步sequence - 参见了解可用的条件类型和运算符
references/deployment_settings.md
- 在
-
应用其他设置:
- /
isTermsAndConditionsEnabled— 预聊天中的条款与条件isTermsAndConditionsRequired - 请勿更新字段 — 站点名称在创建时自动生成,绝不能修改
site
-
生成文件 — 在用户指定的路径生成文件,或默认保存到项目元数据源路径的
.EmbeddedServiceConfig-meta.xml目录下。EmbeddedServiceConfig/ -
展示输出及后续步骤 — 显示生成的文件并总结配置内容。推荐后续步骤:
- 发布部署:通过Connect API使更改生效:
获取bash
sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>的命令:EMBEDDED_SERVICE_CONFIG_IDbashsf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias> - 生成集成代码片段 — 参见
references/code_snippet.md
- 发布部署:通过Connect API使更改生效:
Phase 3 — Validate
阶段3 — 验证
- Verify against checklist — confirm all items in the Verification Checklist below pass.
- 对照检查清单验证 — 确认以下验证检查清单中的所有项均已通过。
Rules / Constraints
规则 / 约束
| Constraint | Rationale |
|---|---|
| Always retrieve existing deployment before updating | Ensures current settings are preserved and only intended changes are applied |
| Platform rejects other values |
Never update the | Site name is auto-generated at creation and must not be changed |
| Web deployments cannot be created via Metadata API | Circular dependency between Network and CustomSite — use Connect API |
| Deployment fails if channel doesn't exist |
| Web widget must be associated with an Experience Site |
| BrandingSet is auto-created with defaults by Connect API | To override branding properties, use Tooling API — see |
| Pre-chat form fields must reference valid channel custom parameters | ChoiceList fields need the parameter deployed on the channel first |
File extension is | Metadata API uses this specific extension |
Do not hardcode file paths — respect | Customer orgs customize source paths |
| Never include deploy/push commands in generated output | This skill produces artifacts only |
| Publish step (Connect API) required after Web ESD updates | Changes are not live until published |
| 约束 | 理由 |
|---|---|
| 更新前始终检索现有部署 | 确保保留当前设置,仅应用预期更改 |
| 平台会拒绝其他值 |
绝不能更新网页部署的 | 站点名称在创建时自动生成,不得更改 |
| 网页部署无法通过Metadata API创建 | Network和CustomSite之间存在循环依赖 — 请使用Connect API |
| 若渠道不存在,部署会失败 |
网页类型更新需要 | 网页小部件必须关联到体验站点 |
| Connect API会自动创建带有默认设置的BrandingSet | 要覆盖品牌属性,请使用Tooling API — 参见 |
| 预聊天表单字段必须引用有效的渠道自定义参数 | 选择列表字段需要先在渠道上部署参数 |
文件扩展名为 | Metadata API使用此特定扩展名 |
请勿硬编码文件路径 — 遵循 | 客户组织会自定义源路径 |
| 生成的输出中请勿包含部署/推送命令 | 此技能仅生成工件 |
| 网页ESD更新后需要执行发布步骤(Connect API) | 更改必须发布后才会生效 |
Gotchas
常见问题
| Issue | Resolution |
|---|---|
| Web ESD creation fails via Metadata API | Web type requires Connect API for initial creation; use Metadata API only for updates |
| Site name not found | Site must exist before Web ESD update; format is |
| Branding overrides not applied | Use Tooling API to update individual BrandingSet properties after the deployment is created |
| Pre-chat ChoiceList not showing | ChoiceList requires two-step deploy: create ChoiceList first, then assign to form field |
| Changes not appearing in widget | Web ESDs must be published via Connect API after any update |
| Set to |
| reCAPTCHA configuration rejected | reCAPTCHA is |
| Business hours not taking effect | Only updating existing business hours works; creation is managed separately |
| Deploy fails with "required field missing" or "upsert failed null" | All attributes are mandatory: boolean fields in |
| Standard pre-chat field not found | Use |
| 问题 | 解决方法 |
|---|---|
| 通过Metadata API创建网页ESD失败 | 网页类型需要通过Connect API进行初始创建;仅使用Metadata API进行更新 |
| 站点名称未找到 | 更新网页ESD前必须存在站点;格式为 |
| 品牌覆盖设置未生效 | 创建部署后,使用Tooling API更新单个BrandingSet属性 |
| 预聊天选择列表未显示 | 选择列表需要两步部署:先创建选择列表,再分配给表单字段 |
| 更改未在小部件中显示 | 网页ESD在任何更新后都必须通过Connect API发布 |
| 除非明确需要嵌入式流程(而非路由流程),否则设置为 |
| reCAPTCHA配置被拒绝 | reCAPTCHA为 |
| 营业时间未生效 | 仅更新现有营业时间有效;营业时间的创建需单独管理 |
| 部署失败,提示“必填字段缺失”或“upsert失败 null” | 所有属性都是必填的: |
| 标准预聊天字段未找到 | 在 |
Verification Checklist
验证检查清单
Universal Checks
通用检查
- Is one of
deploymentType,API, orMobile?Web - Is populated and unique?
masterLabel - Does reference an existing channel?
messagingChannel - Is set to
deploymentFeature?EmbeddedMessaging - Is set to
isEnabled?true
- 是否为
deploymentType、API或Mobile之一?Web - 是否已填充且唯一?
masterLabel - 是否引用了现有渠道?
messagingChannel - 是否设置为
deploymentFeature?EmbeddedMessaging - 是否设置为
isEnabled?true
Web Type Checks
网页类型检查
- Is populated with the Experience Site name?
site - If branding is configured, does reference an existing BrandingSet?
embeddedServiceBrandingName - Are pre-chat form field names valid (match channel custom parameters)?
- If is
isInvitationEnabled, istruepopulated and consistent with allformulanumbers insequence?<embdMsgChannelInvitationConditions>
- 是否已填充体验站点名称?
site - 若配置了品牌,是否引用了现有BrandingSet?
embeddedServiceBrandingName - 预聊天表单字段名称是否有效(匹配渠道自定义参数)?
- 若设置为
isInvitationEnabled,true是否已填充且与formula中的所有<embdMsgChannelInvitationConditions>编号一致?sequence
API/Mobile Type Checks
API/移动端类型检查
- Is empty (no site needed)?
siteUrl - Is correctly set to
deploymentTypeorAPI?Mobile
- 是否为空(无需站点)?
siteUrl - 是否正确设置为
deploymentType或API?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?
- 是否提醒用户网页部署需通过Connect API发布?
- 是否提醒用户若部署了消息组件,需通过Tooling API激活组件?
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/交付物:
- API/移动端创建:
<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml - 网页创建:Connect API负载及说明(无XML文件)
- 更新操作:
<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml
文件结构遵循中的模板。
assets/Cross-Skill Integration
跨技能集成
| Need | Delegate to |
|---|---|
| Creating the messaging channel | |
| Creating Omni-Channel routing flows | |
| Creating permission sets for agents | |
| 需求 | 委托给 |
|---|---|
| 创建消息渠道 | |
| 创建全渠道路由流程 | |
| 创建代理权限集 | |
Reference File Index
参考文件索引
| File | When to read |
|---|---|
| Before generating API or Mobile type deployments |
| Before generating Web type updates |
| When configuring deployment options beyond defaults |
| When creating Web type deployments (Connect API required) |
| When user asks about branding configuration |
| When user wants the JavaScript embed code snippet for their website |
| Phase 1 — verify org API version meets the passed minimum (67.0) |
| To verify output for API type deployment |
| To verify output for Mobile type deployment |
| To verify output for fully configured Web deployment |
| 文件 | 读取时机 |
|---|---|
| 生成API或移动端类型部署前 |
| 生成网页类型更新前 |
| 配置默认以外的部署选项时 |
| 创建网页类型部署时(需使用Connect API) |
| 用户询问品牌配置时 |
| 用户需要用于网站的JavaScript嵌入代码片段时 |
| 阶段1 — 验证组织API版本是否满足最低要求(67.0) |
| 验证API类型部署的输出时 |
| 验证移动端类型部署的输出时 |
| 验证完全配置的网页部署的输出时 |