mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-11 02:14:21 +08:00
194 lines
9.5 KiB
Markdown
194 lines
9.5 KiB
Markdown
# Embedded Messaging Deployment Settings Reference
|
|
|
|
Complete reference for all configurable settings on an `EmbeddedServiceConfig` metadata type.
|
|
|
|
---
|
|
|
|
## Deployment Types
|
|
|
|
| Type | Value | Use Case | Creation Method |
|
|
|------|-------|----------|-----------------|
|
|
| API | `API` | Headless integrations, no UI widget | Metadata API or Connect API |
|
|
| Mobile | `Mobile` | Native mobile app messaging | Metadata API or Connect API |
|
|
| Web | `Web` | Browser-based chat widget | Connect API (create), Metadata API (update) |
|
|
|
|
---
|
|
|
|
## Top-Level Fields
|
|
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `masterLabel` | String | Yes | — | Deployment display name |
|
|
| `deploymentType` | Enum | Yes | — | `API`, `Mobile`, or `Web` |
|
|
| `deploymentFeature` | String | Yes | `EmbeddedMessaging` | Always `EmbeddedMessaging` |
|
|
| `clientVersion` | Enum | Yes | - | only applicable to Web deployment type. `WebV1`, `WebV2` |
|
|
| `areGuestUsersAllowed` | Boolean | Yes | `false` | Allow unauthenticated guest access |
|
|
| `isEnabled` | Boolean | Yes | `true` | Whether deployment is active |
|
|
| `shouldHideAuthDialog` | Boolean | Yes | `false` | Hide auth dialog from users |
|
|
| `site` | String | Web only | — | Experience Site name (format: `ESW_<name>_<timestamp>`) |
|
|
| `branding` | String | Web only | — | Reference to a `BrandingSet` name (Web deployments only) |
|
|
| `isTermsAndConditionsEnabled` | Boolean | No | `false` | Show T&C acceptance in pre-chat |
|
|
| `isTermsAndConditionsRequired` | Boolean | No | `false` | Require T&C acceptance before chatting |
|
|
|
|
---
|
|
|
|
## Embedded Service Messaging Channel (`<embeddedServiceMessagingChannel>`)
|
|
|
|
Links the deployment to a messaging channel and configures widget behavior. All boolean fields below are **required** in the XML.
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `messagingChannel` | String | — | **Required.** Channel `channelPlatformKey` |
|
|
| `businessHours` | String | — | BusinessHours `businessHoursName` |
|
|
| `displayNameFormat` | String | — | Display name if pre-chat is enabled |
|
|
| `formula` | String | — | Condition logic expression referencing `sequence` numbers from `<embdMsgChannelInvitationConditions>` (e.g., `1 AND 2`, `1 OR 2 OR 3`). Required when `isInvitationEnabled` is `true`. Must be updated whenever conditions are added or removed |
|
|
| `isChatInvitationCustomizable` | Boolean | `false` | **Required.** Allow customizing chat invitation. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `isEnabled` | Boolean | `true` | **Required.** Whether messaging is enabled on this deployment |
|
|
| `isInvitationEnabled` | Boolean | `false` | **Required.** Enable proactive chat invitations. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `isSendInvtAllowedAfterAccept` | Boolean | `false` | **Required.** Allow invitations after previous one accepted. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `isSendInvtAllowedAfterReject` | Boolean | `false` | **Required.** Allow invitations after previous one rejected. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldShowAgentforceTagline` | Boolean | `false` | **Required.** Show Agentforce branding tagline. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldShowDeliveryReceipts` | Boolean | `false` | **Required.** Show message delivery receipts. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldShowEmojiSelection` | Boolean | `false` | **Required.** Enable emoji picker. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldShowReadReceipts` | Boolean | `false` | **Required.** Show read receipts. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldShowTypingIndicators` | Boolean | `false` | **Required.** Show typing indicators. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
| `shouldStartNewLineOnEnter` | Boolean | `false` | **Required.** Enter key creates new line instead of sending. Can only be `true` for Web deployments; must be `false` for API/Mobile |
|
|
|
|
---
|
|
|
|
## Pre-Chat Forms (`<embeddedServiceForms>`)
|
|
|
|
Collects information from users before conversation starts. Applicable to all deployment types.
|
|
|
|
### Form Structure
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `displayContext` | Enum | Yes | `Conversation` or `Session` |
|
|
| `isActive` | Boolean | Yes | Whether the form is active |
|
|
| `embeddedServiceFormFields` | Repeatable | Yes | Individual form fields (see below) |
|
|
|
|
### Form Field Structure (`<embeddedServiceFormFields>`)
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `displayOrder` | Integer | Yes | 0-based display position |
|
|
| `formField` | String | Yes | Parameter name — use `_` prefix for standard fields (e.g., `_FirstName`), exact `name` for custom fields |
|
|
| `formFieldType` | Enum | Yes | `Text`, `Email`, `Phone`, `Number` |
|
|
| `isHidden` | Boolean | Yes | Whether field is hidden from user (still collected) |
|
|
| `isRequired` | Boolean | Yes | Whether field must be filled |
|
|
| `messagingChannelParameterType` | Enum | Yes | `Standard` or `Custom` |
|
|
|
|
### Example
|
|
|
|
```xml
|
|
<embeddedServiceForms>
|
|
<displayContext>Conversation</displayContext>
|
|
<embeddedServiceFormFields>
|
|
<displayOrder>0</displayOrder>
|
|
<formField>_FirstName</formField>
|
|
<formFieldType>Text</formFieldType>
|
|
<isHidden>false</isHidden>
|
|
<isRequired>true</isRequired>
|
|
<messagingChannelParameterType>Standard</messagingChannelParameterType>
|
|
</embeddedServiceFormFields>
|
|
<embeddedServiceFormFields>
|
|
<displayOrder>1</displayOrder>
|
|
<formField>_Email</formField>
|
|
<formFieldType>Email</formFieldType>
|
|
<isHidden>false</isHidden>
|
|
<isRequired>true</isRequired>
|
|
<messagingChannelParameterType>Standard</messagingChannelParameterType>
|
|
</embeddedServiceFormFields>
|
|
<embeddedServiceFormFields>
|
|
<displayOrder>2</displayOrder>
|
|
<formField>CompanyName</formField>
|
|
<formFieldType>Text</formFieldType>
|
|
<isHidden>false</isHidden>
|
|
<isRequired>false</isRequired>
|
|
<messagingChannelParameterType>Custom</messagingChannelParameterType>
|
|
</embeddedServiceFormFields>
|
|
<isActive>true</isActive>
|
|
</embeddedServiceForms>
|
|
```
|
|
|
|
### Standard Pre-Chat Fields
|
|
|
|
Standard fields use a `_` prefix in the `formField` value:
|
|
|
|
| `formField` Value | Maps to `parameterType` | Typical Usage |
|
|
|-------------------|------------------------|---------------|
|
|
| `_FirstName` | `FirstName` | User identification |
|
|
| `_LastName` | `LastName` | User identification |
|
|
| `_Email` | `Email` | Follow-up and case creation |
|
|
| `_Subject` | `Subject` | Routing context |
|
|
|
|
### Custom Pre-Chat Fields
|
|
|
|
Custom fields use the exact `name` value from the channel's `customParameters` (no prefix). Custom fields must first be configured as `customParameters` on the messaging channel (via `service-digital-engagement-channel-configure`) before they can be referenced in the ESD form.
|
|
|
|
### ChoiceList (Dropdown) Fields
|
|
|
|
ChoiceList fields require a two-step deployment:
|
|
1. Create the `ChoiceList` metadata record
|
|
2. Assign it to the form field in the ESD
|
|
|
|
The ChoiceList field must reference a custom parameter `name` on the messaging channel.
|
|
|
|
---
|
|
|
|
## Branding
|
|
|
|
Referenced as a top-level `<branding>` field with the BrandingSet name.
|
|
|
|
```xml
|
|
<branding>My_BrandingSet</branding>
|
|
```
|
|
|
|
**Important**: A BrandingSet with defaults is auto-created by the Connect API when the deployment is created. To override specific properties (colors, fonts, dimensions), use the Tooling API — see `references/branding_and_tooling.md`.
|
|
|
|
---
|
|
|
|
### Invitation Condition Rules (`<embdMsgChannelInvitationConditions>`)
|
|
|
|
Available since API v58.0. Repeatable. Configures conditions under which the messaging widget proactively invites a visitor to chat. Applicable to Web deployments only.
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `sequence` | Integer | Yes | Position in `conditionLogic` expression (1-based) |
|
|
| `conditionType` | Enum | Yes | The type of condition to evaluate (e.g., `SecondsOnPage`, `SecondsOnSite`, `NumberOfPageViews`, `UrlMatch`, `CustomVariable`) |
|
|
| `operand` | Enum | Yes | Comparison operator (`Equals`, `NotEqual`, `Contains`, `NotContain`, `GreaterThan`, `LessThan`, `LessOrEqual`, `GreaterOrEqual`, `StartWith`) |
|
|
| `customVariableName` | String | No | Custom variable name (when `conditionType` references a CustomVariable) |
|
|
| `value` | String | Yes | The value to compare against |
|
|
|
|
### Example
|
|
|
|
```xml
|
|
<embdMsgChannelInvitationConditions>
|
|
<sequence>1</sequence>
|
|
<conditionType>UrlMatch</conditionType>
|
|
<operand>Contains</operand>
|
|
<value>/support</value>
|
|
</embdMsgChannelInvitationConditions>
|
|
<embdMsgChannelInvitationConditions>
|
|
<sequence>2</sequence>
|
|
<conditionType>SecondsOnPage</conditionType>
|
|
<operand>GreaterThan</operand>
|
|
<value>30</value>
|
|
</embdMsgChannelInvitationConditions>
|
|
```
|
|
|
|
---
|
|
|
|
## API Method Summary
|
|
|
|
| Operation | Metadata API | Tooling API | Connect API |
|
|
|-----------|-------------|-------------|-------------|
|
|
| Create any ESD (Web) | No | No | Yes |
|
|
| Create any ESD (API/Mobile) | Yes | No | Yes |
|
|
| Update ESD (top-level + channel settings) | Yes | Yes | No |
|
|
| Update ESD (forms/labels) | Yes | No | No |
|
|
| Create BrandingSet | No (auto-created by Connect API) | No | Yes |
|
|
| Update BrandingSet properties | No | Yes | No |
|
|
| Publish ESD | No | No | Yes |
|