Embedded Service 26B

Embedded Service is an Oracle Digital Customer Service product to embed automated or live chat into any website, including your DCS Portal.

Table of Contents

• Usage
• Architecture
• Outer API
• Inner API
• Survey
• Theming
• Chat Launch Form
• Upgrade

Usage

Complete the following steps to deploy Embedded Service (ES):

1. Begin with the Required setup for Embedded Service.
2. Customize and publish your own Embedded Service application from the "Embedded Service 26B" reference implementation template in Oracle Visual Builder (VB).
3. Use the DCS Rules Engine to load Embedded Service on any web page.

Architecture

Embedded Service has a layered architecture with a presence in both the host page where it is embedded and the iframe containing the ES Visual Builder application. From the top-down, these layers include:

1. Rules Engine
   • The Rules Engine is the recommended library for loading and interacting with the Embedded Service SDK.
   • Otherwise a custom script on the host page can use the ES Outer API directly.
2. Embedded Service SDK
   • The ES SDK has two parts which coordinate the communication between the host page and the Visual Builder application.
   • The Host part of the SDK exposes an Outer API to the Rules Engine (or custom script) to drive Embedded Service from the host page.
   • The Embedded part exposes an Inner API to the ES application in Visual Builder.
3. Embedded Service Application
   • Unlike the layers above, the ES application is owned by the customer and created, customized and deployed in Visual Builder.
   • While some of the integrations with the Inner API provided in the reference implementation are required for Embedded Service to function end-to-end, the customer is otherwise free to customize the application to their heart's content.

Outer API

The Outer API is a JavaScript API exposed by the Embedded Service SDK on the host page.

• Properties
• Outer Methods
• Outer Events

Properties

Many Embedded Service features are configured by properties, which are summarized in the table below. ES properties can be used per the following rules:

• All properties can be set in the outer load method.
• Most properties can be set in the inner load method. The few exceptions have a "No" in the "Inner" column of the table below.
• Some properties can also be updated (after ES has loaded) with the outer update method. These are marked by a "Yes" in the "Update" column. Whereas "Mixed" means that some sub-properties are updatable while others are not.
• Note that there is no inner update method at this time.

When customizing properties, it generally make sense to first set them in the inner load method, which will set custom defaults for all instances of your ES application. For many properties this is enough. For those that require further customization based on page context, you can additionally change them at runtime via the outer load and update methods. In the Rules Engine, these are available in the loadES and updateES actions, respectively. See the Property Lifecycle section for more details on how ES properties can be set and changed.

Property Lifecycle

When customizing ES properties, it's important to understand their lifecycle from load through potentially multiple updates.

When first loading Embedded Service, any properties you specify in the outer load (or RE loadES action) and inner load methods are merged with the default properties defined within the ES SDK. When the same property is set in both methods, the outer property takes precedence. When not set at all, the Embedded service defaults are used. This combined set of custom and default properties become the initial current properties used by Embedded Service.

When updating properties with the outer update method (or RE updateES action), the properties you pass are merged with the current properties rather than the defaults. I.e. updates are incremental and sparse. This means that an update will not override properties already customized unless explicitly specified in the update itself.

This can lead to unexpected behavior with nested properties such as context and styles. E.g. If a load or previous update sets one context property and a subsequent update sets a second context property, the current properties now have both context properties set. If the intention is to remove the initial property in the latest update, it must be explicitly set with an empty value.

With styles, the same rule applies. If you customize a subset of style properties, then the current properties include a merged set of defaults and your customizations. When updating, you are merging into this set of already merged styles. E.g. if you want to switch between multiple custom maximized views at runtime, it is best to use custom views rather than continuing to update the one set of styles under the standard maximized view. Otherwise, you can end up with an unexpected mix of properties from multiple updates.

Note that this sparse merging behavior is consistent across all properties.

Chat

The chat property is an object with the following defaults:

{
  chat: {
    autoStart: 'noVisibleFields',
    linksMode: 'dynamicLinks',
    polling: 'off',
    pollingDetails: {
      minAgentSessions: 1
    }
  }
}

Of the following sub-properties, autoStart and linksMode are updatable but the others are not.

autoStart

The autoStart property controls if and how Embedded Service starts a chat automatically. The following values are supported:

• noVisibleFields (default): Auto start when there are no visible fields defined in the Chat Launch Form. The data from any hidden fields will be passed behind the scenes when the chat is initialized.
• noEmptyRequiredFields: Expands the noVisibleFields behavior to also auto start the chat if all required visible fields have a value already specified. Form field values can be preset by any of the following:
  • A default value in the Field Properties
  • Via the context property
  • And end-user supplied value from a previous chat for fields in the FORM_FIELDS_TO_PERSIST application constant

linksMode

The linksMode setting configures how to handle chat links and ODA URL actions in ES. Valid options include:

• dynamicLinks: The default chat link behavior in Embedded Service, including: open links and URL actions in new tabs and handle Fusion dynamic links.
• linkHandler: Use the ODA Web SDK settings under wcfs.linkHandler and wcfs.webViewConfig to control the behavior of chat links and URL actions. Note that Fusion dynamic links are not supported when set to linkHandler.

Polling

Polling can be configured to show and hide Embedded Service based on agent availability, which can be useful when chat is handled by live agents. Two properties work together to configure this feature: polling and pollingDetails. The polling property can be on or off (default).

pollingDetails is an object with the following sub-properties:

• categoryId (number): The id of the category mapped by routing rules to the queue to poll.
• maxQueueSize (number): The maximum number of users in a queue before it's considered full and unavailable for new chats.
• maxWaitSeconds (number): The maximum wait time allowed in the queue, in seconds.
• minAgentSessions (number): The minimum number of available agent sessions.
• queueId (number): The id of a specific queue to poll.

Rules:

• You may specify categoryId, queueId, or neither (to poll the default queue). If both are set, queueId takes precedence.
• You can either set minAgentSessions, or set maxQueueSize and/or maxWaitSeconds. If minAgentSessions is set, maxQueueSize and maxWaitSeconds are ignored. If none are set, minAgentSessions defaults to 1.

When polling is on, the default behavior is to keep ES hidden until agents are available. When an agent first becomes available, ES is displayed (or not) based on its view property:

• minimized (default): Show the ES launch button
• maximized (or any custom view): Show the expanded ES widget
• hidden: Keep ES hidden indefinitely. In this case, RE or a script on the host page should listen for the agentAvailability outer event and show and hide ES according to additional criteria.

In the application code, see the application AgentAvailabilityHandler action chain, which listens for the inner agentAvailability event and implements the default implementation.

Context

Use the context property to customize field values of the Chat Launch Form in the ES application. There is a one-to-one mapping between context properties and form field names, and even custom fields can be set. E.g.

{
  "context": {
    "Email": "first.last@example.com",
    "FirstName": "First",
    "LastName": "Last",
    "Product": {
      "productGroupId": 123,
      "inventoryItemId": 456
    },
    "ServiceRequestNumber": "789",
    "my_custom_field": "foo"
  }
}

If the target form field is:

• Visible: the corresponding context property will set the initial value which the end user can then change.
• Hidden: the value will be set and passed behind the scenes without the end user seeing it.
• Not present: it will be ignored.

In general, the context property can change the value of any field of the Chat Launch Form. However, when an end user is logged in, the user fields of Email, FirstName and LastName are auto-set to the authenticated user and may no longer be set by context.

CSS

CSS related properties include:

• cssVariableNamespaces: Inherit themeing by propagating CSS variables from the specified namespaces (i.e. with the specified prefixes) from the host page. Defaults include:
  • --oj-: By default any Oracle JET CSS variables (from the --oj- namespace) will propagate and style ES and the underlying JET components used by ES accordingly.
  • --custom-: The --custom- namespace is an example of how any other CSS variables can also be used for styling. See the Embedded Service reference implementation in Visual Builder for examples of how such --custom- variables can be used in app styling, including in the inner styles property.

If this type of inheritance is not required, simply set cssVariableNamespaces to an empty array and the application will look as configured by the default CSS variable values in app.css. See Theming for more.

Drag

Drag related properties include:

• launchButtonAxis: Define the drag behavior of the ES launchButton, with one of the following values:
  • none (default): The launchButton is not draggable
  • horizonal: The launchButton is draggable along the horizonal axis
  • vertical: The launchButton is draggable along the vertical axis
  • both: The launchButton is freely draggable in any direction

Icons

Icons used on the host page include:

• launch: Optional icon on the minimized launch button. Specify an inline SVG or a URL to a valid image for a custom icon or an empty string for no icon (default).

The icons used within the ES VB app are defined in application code.

Strings

All end-user-facing, translatable strings used in Embedded Service should be defined in the app bundles (app-strings.json files) under the locale directories in webApps/es/resources/strings/app/nls.

In the reference implementation, default strings are organized by prefix to group them by usage. While not a full list, a few prefixes worth highlighting include:

• common_: Common strings used in the VB application code
• chatLaunch_: Strings passed to the oj-dcs-chat-launch component
• host_: Strings used by elements on the host page
• wcfs_: Strings passed to WCFS. While the reference implementation provides an example WCFS string, note that any WCFS Custom Text string may be customized by adding it to the app bundle with a wcfs_ prefix. See the Custom Text section of the latest WCFS Docs for the full list.

You're free to modify existing strings and add your own. However, if you support more than one locale, you're responsible for translating any new or updated strings. Any strings not defined in the current locale will fall back to the English strings in the root directory.

If you don't need different strings for different instances of Embedded Service, updating the app bundles in your VB application code should suffice. If you do need different strings per instance based on runtime context, any string (or subset of strings) in the app bundle can be set via the strings property. This applies to both default strings and your custom strings; simply use the same keys defined in the app bundle. Note that the strings property can only customize strings for the active locale (see the locale property).

Variables

The Embedded Service reference implementation uses Visual Builder application variables for various configuration and state management. In some cases, it may be useful to set one or more these configuration-type variables at runtime based on the context of the page or ES instance. The ES application maintains an allow list of supported variables in the APPLICATION_VARIABLES_ALLOW_LIST application constant, which is an array of variable names that can be set at runtime with the variables property.

To set an application variable at runtime, you can:

1. Add the variable name to the APPLICATION_VARIABLES_ALLOW_LIST array
2. Pass the custom variable value as an outer property via the top-level variables property.

The default ES reference implementation initializes the specified application variables with the provided values as ES loads. The following example sets the survey id and chatLaunchFormFields variables dynamically from the host page in the ES load outer method:

es.load({
  ...other outer properties,
  variables: {
    chatLaunchFormFields: [...updated fields]
    surveyIdBot: 123,
    surveyIdLiveAgent: 456
  }
});

See the Survey and Chat Launch Form sections for more details on their respective features.

Views

Views are different modes in which Embedded Service can appear (or not appear). The standard views include:

• hidden: the invisible view of ES before it first appears or when it's explicitly hidden.
• minimized: the collapsed view of ES where the launch button is visible and the widget is hidden.
• maximized: the expanded view of ES where the widget is visible and the launch button is generally hidden.
• mobile: the maximized view of ES at a mobile screen size, which is currently fixed at < 600px.

In addition to the out-of-the-box views above, one or more custom views can be added by adding a custom key to the styles property and setting any style properties specific to the view. Custom views have the following restrictions:

1. Their names must begin with a custom prefix (e.g. customAI)
2. They can only be maximized views, which means they must set widgetHide: false in their properties. Custom hidden and minimized views are not supported.

Keep in mind that if you only need one maximized view, you can simply customize the styles properties of the standard maximized view. I.e. Custom views are only necessary when you want to switch between two or more maximized views.

Standard and custom views alike can be set initially with the view property on load and then changed by one of the following:

• An update to the same view property (e.g. es.update({ view: 'maximized' }))
• Invoking the setView method (e.g. es.setView('maximized'))
• The user as they interact with the widget. By default, clicking the launch button will set the view to maximized while clicking the minimize button in the widget header will set the view to minimized.

Here's an example of a customAI view that takes up most of the screen:

{
  styles: {
    ...,
    customAI: {
      launchButtonHide: true,
      widgetBorderRadius: '10px 10px 0 0',
      widgetBottom: '0',
      widgetHeight: '90%',
      widgetHide: false,
      widgetMaxWidth: '90%',
      widgetRight: 'calc(50% - var(--es-widget-width)/2)',
      widgetWidth: '90%'
    }
  }
}

Styles

Style Properties

The styles properties configure the look and feel of the Embedded Service elements on the host page, including:

• The launch button, which is visible when ES is minimized.
• The widget, which is visible when ES is maximized. However, note that the element on the host page is merely a frame around the content from the ES application and is thus mostly limited to size, position and border properties. The application content within the frame is styled within the application code.
• The skeleton, a subtle element which simulates the app contents and is visible only briefly during view change animations.

The properties are grouped and defined separately for each ES view in order to support different values for the same property as well as animations between views.

In general, most style properties are common to all views. Rather than duplicating these in each and every view, define them once in the common view instead. Though the common view is not a real view but rather a baseline (or abstract view) from which all other views inherit. Then only the differences from common need to be specified in the view specific styles.

The following table lists all supported styles properties. Note that by default the properties used by the skeleton for animations match the corresponding CSS properties defined in the ES application for a seamless experience.

Default Styles

In general, the default values of the majority of these style properties are suitable for most ES applications. Here are the full defaults for reference, though when customizing styles keep in mind that you only need to specify the differences from these defaults. See Property Lifecycle and the examples below.

{
  "styles": {
    "common": {
      "bodyBgColor": "rgb(249,249,249)",
      "brandBgColor": "rgb(90,118,158)",
      "brandTextColor": "#fff",
      "fontFamily": "-apple-system, BlinkMacSystemFont, \"Segoe UI\", \"Helvetica Neue\", Arial, sans-serif",
      "fontSize": "1em",
      "headerBgColor": "",
      "headerHeight": "48px",
      "launchButtonAnimationDelay": 500,
      "launchButtonBgColor": "",
      "launchButtonBorderRadius": "4px",
      "launchButtonBottom": "10px",
      "launchButtonFontSize": "1rem",
      "launchButtonFontWeight": "400",
      "launchButtonHeight": "auto",
      "launchButtonHide": true,
      "launchButtonIconHeight": "24px",
      "launchButtonIconWidth": "24px",
      "launchButtonOpacity": "0",
      "launchButtonPadding": "8px 14px",
      "launchButtonRight": "10px",
      "launchButtonTextColor": "",
      "launchButtonTransform": "none",
      "launchButtonTransition": "opacity 400ms ease-in-out",
      "launchButtonWidth": "auto",
      "widgetAnimationDelay": 500,
      "widgetBorder": "1px solid #999",
      "widgetBorderRadius": "10px",
      "widgetBottom": "10px",
      "widgetHeight": "0px",
      "widgetHide": true,
      "widgetMaxWidth": "",
      "widgetOpacity": "1",
      "widgetRight": "10px",
      "widgetTransition": "all 400ms ease-in-out",
      "widgetWidth": "0px",
      "zIndex": "10000"
    },
    "hidden": {
      "launchButtonHide": true,
      "widgetBorder": "none",
      "widgetHide": true,
      "widgetOpacity": "0"
    },
    "maximized": {
      "launchButtonHide": true,
      "widgetHeight": "720px",
      "widgetHide": false,
      "widgetWidth": "480px"
    },
    "minimized": {
      "launchButtonHide": false,
      "launchButtonOpacity": "1",
      "widgetBorder": "none",
      "widgetHide": true,
      "widgetOpacity": "0"
    },
    "mobile": {
      "launchButtonHide": true,
      "widgetBorder": "none",
      "widgetBorderRadius": "0",
      "widgetBottom": "0",
      "widgetHeight": "100%",
      "widgetHide": false,
      "widgetRight": "0",
      "widgetWidth": "100%"
    }
  }
}

Style Examples

The following sections show examples of styling Embedded Service in different ways. If you'd like to switch between multiple of these at runtime, be sure to use custom views rather than just a plain update. See Property Lifecycle for more.

Example: Large Centered

The following example centers and expands the maximized view to cover most of the page.

{
  "styles": {
    "maximized": {
      "widgetBorderRadius": "10px 10px 0 0",
      "widgetBottom": "0",
      "widgetHeight": "90%",
      "widgetMaxWidth": "90%",
      "widgetRight": "calc(50% - var(--es-widget-width)/2)",
      "widgetWidth": "90%"
    }
  }
}

Note the use of --es-widget-width in the widgetRight property, which is a reference to the runtime CSS variable set internally by ES from the widgetWidth property. Each style property is written to a CSS variable following this pattern and can thus be used by other style properties if necessary.

Example: Right Tab and Drawer

The following example customizes the minimized view to a right tab and the maximized view to a right drawer, both of which slide in from the right.

{
  "styles": {
    "common": {
      "launchButtonBorderRadius": "10px 10px 0 0",
      "launchButtonBottom": "25%",
      "launchButtonHeight": "36px",
      "launchButtonOpacity": "1",
      "launchButtonRight": "-36px",
      "launchButtonTransform": "translateX(28px) rotate(-90deg)",
      "launchButtonTransition": "right 400ms ease-in-out",
      "launchButtonWidth": "90px",
      "widgetBorderRadius": "0px",
      "widgetBottom": "0px",
      "widgetHeight": "100%",
      "widgetOpacity": "1",
      "widgetRight": "0px",
      "widgetTransition": "width 400ms ease-in-out"
    },
    "hidden": {
      "widgetOpacity": "1"
    },
    "minimized": {
      "launchButtonRight": "0px",
      "widgetHeight": "100%",
      "widgetOpacity": "1"
    },
    "maximized": {
      "widgetHeight": "100%"
    }
  }
}

Example: Bottom Tab

The following example shows a bottom tab and widget that slide up from the bottom.

{
  "styles": {
    "common": {
      "launchButtonBorderRadius": "10px 10px 0 0",
      "launchButtonBottom": "-32px",
      "launchButtonHeight": "32px",
      "launchButtonPadding": "6px 10px",
      "launchButtonRight": "30px",
      "launchButtonTransition": "bottom 400ms ease-in-out",
      "widgetBorderRadius": "10px 10px 0 0",
      "widgetBottom": "0px",
      "widgetTransition": "all 400ms ease-in-out"
    },
    "minimized": {
      "launchButtonBottom": "0px"
    }
  }
}

WCFS

To implement its chat feature, Embedded Service currently uses Web Chat for Service (WCFS) and supports many WCFS settings in its wcfs property. However, please note that future versions of ES may migrate to a different chat client and thus it is discouraged to use these WCFS settings directly in ES as they may not be available in the future. If you are willing to take that risk, use the instructions below to see which WCFS settings are available in ES today.

Just as Embedded Service wraps WCFS, WCFS wraps the ODA WebSDK, which in turn has its own settings. Each layer supports many but not all of the settings of the layer below. Thus the WCFS settings supported in ES are the settings listed in both the WCFS and ODA WebSDK docs minus those listed in both of the unsupported lists.

The ES reference implementation does set a few wcfs settings by default in the inner load method, and these must remain intact for the corresponding features to work. But the wcfs property can also be extended to add other supported WCFS and WebSDK settings as desired.

Unsupported WCFS Settings

The following WCFS settings are not supported in Embedded Service:

• authorization
• badgePosition
• chatBubbleIconHeight
• chatBubbleIconWidth
• clearConversationOnClose
• conditionalChatLinkCss
• conditionalChatLinkElementId
• conditionalLaunchButton
• conditionalLaunchButtonDetails
• connectionData
• customHeaderElementId
• disableInlineCSS
• disconnectEvent
• embedded
• embeddedVideo
• embedBottomScrollId
• embedBottomStickyId
• embedTopScrollId
• embedTopStickyId
• enableAgentSneakPreview
• enableAudioAlerts
• enableClearMessage
• enableConditionalChatLink
• endConversationAndClose
• enableDefaultClientResponse
• enableDraggableButton
• enableDraggableWidget
• enableEndConversation
• enableEndConversationButtonToClose
• enableHeaderActionCollapse
• enableOffTheRecord
• enableProactiveChat
• enableResizableWidget
• events
• height
• i18n
• launchButtonSettings
• limitPlfManipulation
• name
• openChatOnLoad
• persistenceOpenWidget
• position
• preLaunchFormCss
• preLaunchFormFields
• preLaunchFormMode
• proactiveChatDialogCss
• proactiveChatUrl
• service
• showConnectionStatus
• showPageLeaveWarning
• showPreLaunchForm
• showSystemMessageMinimizeButton
• showWidgetTimeout
• showWidgetTimeoutInactivity
• targetElement
• URI
• width

While some colors are supported, the following are not:

• colors
  • headerBackground
  • headerButtonBackgroundHover
  • headerButtonFill
  • headerButtonFillHover
  • headerText
  • launchIconBackground
  • ratingStar
  • ratingStarFill

While some hotkeys are supported, the following are not:

• hotkeys
  • close
  • collapse
  • launch

While some icons are supported, the following are not:

• icons
  • audioAlertsOff
  • audioAlertsOn
  • clearHistory
  • collapse
  • launch
  • logo
  • offTheRecordOff
  • offTheRecordOn
  • ttsOff
  • ttsOn

Outer Methods

The ES SDK exposes the following methods to the host page. As noted in the table, some methods have corresponding Rules Engine (RE) actions, while others do not. In either case, all methods can be called directly on the es object added to window. E.g. window.es.minimize() or just es.minimize().

Outer Events

For use in the Rules Engine, see Embedded Service events in the RE docs.

For direct use of the ES SDK, use the es.on and es.off methods to subscribe and unsubscribe custom event handlers. E.g.

// Attach multiple handlers to the same event
const handler1 = () => console.log(`Handler 1`);
const handler2 = () => console.log(`Handler 2`);
es.on('load', handler1);
es.on('load', handler2);

// Unsubscribe one handler at a time
es.off('load', handler1);
es.off('load', handler2);

// Unsubscribe all handlers for a specific event
es.off('load');

// Unsubscribe all handlers across all events
es.off();

Event Types

Embedded Service fires the following public events to the host page.

• agentAvailability
• agentJoin
• chatConnect
• chatDisconnect
• linkAction
• load

agentAvailability

When Polling is enabled, the agentAvailability event fires every 12 seconds with the following payload in the event detail:

{
  available: boolean,
}

agentJoin

Fires when an agent joins the chat with the following payload in the event detail:

{
  name?: string,
  role?: string,
  type: AgentType,
}

• name: Name of the agent
• role: Role of the agent as sent from the Chat server. Generally LEAD for the primary agent or CONFEREE for a non-primary agent in a conference.
• type: Either liveAgent for live agents or bot for automated agents

chatConnect

Fires when a chat is first connected.

chatDisconnect

Fires when a chat is disconnected.

Outer linkAction

When the linksMode property is set to its default value of dynamicLinks, ES will process Fusion Dynamic Links (and other links) in agent chat messages and fire linkAction events when they are clicked. By default, ES will handle these events by firing an inner linkAction event to the ES application, which will open the link in a new tab. However, when subscribing to this outer linkAction event, a custom handler can invoke event.preventDefault() to prevent this default behavior and instead customize what happens when such links are clicked. E.g.

const handler = (event) => {
  event.preventDefault();
  console.log(`linkAction event fired with payload: `, event.detail);
};
es.on('linkAction', handler);

As an example, the DCS Portal reference implementation defines a custom ES linkAction handler to navigate article and SR links to their respective pages within the same tab rather than opening a duplicate Portal in another tab as ES would do by default.

The linkAction event includes the following payload in the event detail:

{
  objectId: string,
  objectType: ObjectType,
  value: string
}

• objectId: The id of the object, which could be anything from an SR number to an article id to a URL depending on the objectType.
• objectType: The type of object link, including:
  • ARTICLE_LINK
  • KNOWLEDGE_ARTICLE
  • KNOWLEDGE_LINK
  • MAILTO
  • SERVICE_REQUEST_CRM
  • SERVICE_REQUEST_HCM
  • URL
• value: The link text

Outer load

Fires when Embedded Service completes loading after a call to the es.load method.

Inner API

The Inner API is a JavaScript API exposed by Embedded Service to the ES Visual Builder application.

• Inner Properties
• Inner Methods
• Inner Events

Inner Properties

All inner properties (i.e. properties that can be passed to the inner load method) are documented in the Properties section above. In the ES reference implementation, see the call to es.load in the application LoadHandler action chain.

Inner Methods

The embedded part of the ES SDK includes the oj-dcs-es resource component, which exposes methods to the Embedded Service application. In various actions chains, you'll see this library injected as oj-dcs/es/es into a local es object from which the inner methods are called. See the table below for some example methods, though the list is not exhaustive.

See the reference implemention code for the full method signatures and default implementation details. Search for es.<MethodName> (e.g. es.initialize) to find where a method is called.

initialize

The initialize method is called at the beginning of the application lifecycle and passes various options required to set up Embedded Service. It takes a single object parameter with the following customizable properties:

All other properties passed in the reference implementation are required for setting up ES and are not customizable. While most are simply VB libraries and variables used internally by the ES SDK, the following may benefit from further explanation:

• wcfsBrowserFetch
  • The native browser fetch required by WCFS to make chat requests, which the reference implementation copies before the VB runtime loads and patches it.
  • Removing or changing this implementation may result in expected chat behavior.

Inner Events

The following inner events are raised by the ES SDK and should be handled by the application code.

• agentAvailability
• chatState
• disconnect
• linkAction
• load
• update
• viewChanged

Inner agentAvailability

Same as the outer agentAvailability event, except fired into the VB application for the default Polling behavior.

chatState

Fires when the internal chat client needs to communicate a change of chat state to the application. Includes the following payload in the event detail:

{
  chatState: ChatState
}

• chatState: The state of the chat, with one of the values defined in the ChatState type in the application code.

disconnect

Fires when the outer disconnect method is called.

Inner linkAction

Fires when an end user clicks a link in an agent message and a custom handler does not prevent the default behavior.

See the outer linkAction event for more.

Inner load

Fires when the load outer method is called and includes the following payload in the event detail:

{
  props: OuterProperties
}

• props: The properties passed to the load method

update

Fires when the update outer method is invoked and includes the following payload in the event detail:

{
  old: MergedProperties,
  props: MergedProperties,
  updated: OuterProperties
}

• old: The merged properties before the update.
• props: The updated merged properties after merging the updated properties with the old properties.
• updated: The specific properties passed to the update method.

viewChanged

Fires anytime the ES view changes with the following payload in the event detail:

{
  view: EsView | string
}

• view: The name of the updated view, either standard or custom

Survey

The ES reference implementation is preconfigured to offer an optional survey after a chat. Though at the moment surveys are only available for authenticated users. The following application variables control the default behavior:

Since surveyIdLiveAgent and surveyIdBot are both empty by default, no survey will appear out of the box. To have a survey appear for chats with live agents but not bots (or vice versa), set one variable and leave the other empty.

The survey loads in the background when the surveyMinimumTurns threshold is met based on the type of agent connected at that time. If a chat is later transferred from a bot to a live agent (or vice versa), the survey offered might not match the type of agent when the chat was disconnected.

See Variables to set any of these survey application variables at runtime.

Theming

Theming is the process of changing the look and feel of Embedded Service. In general, this is done to match the host page, whether that's the DCS Portal or any other website using ES.

The following layers all work together to theme ES:

1. The JET Theme
   • The JET theme and CSS variables set the baseline of all ES styling, including the default look and feel of the underlying JET components used throughout the app (e.g. oj-button, oj-dialog, etc).
2. Application CSS variables
   • These are the CSS variables defined at the top of app.css, which include ES application overrides of JET variables as well as ES specific custom variables.
   • Note that these are defaults, which may be overridden if one or more of these variables are inherited from the host page (see item 4).
3. Application Styling
   • These are all the CSS rules in app.css, which apply the styling for ES specific elements.
   • By default, these use a combination of CSS variables and hardcoded values.
4. Applicable Properties
   • css: Configure which CSS variables are inherited from the host page to optionally override the defaults in item 2.
   • styles: Style the ES elements on the host page.

Chat Launch Form

The chat launch form can be configured to pass information via fields when initiating a chat. Fields can be standard or custom, visible or hidden, preloaded with default values and even updated with new values at runtime via the outer context property. Visible fields appear in the pre chat form for an end user to set while hidden fields are passed behind the scenes. If no visible fields are configured, the chat will start automatically without user input and pass any hidden fields specified.

In the reference implemenation, the chat launch form fields are configured in the chatLaunchFormFields application variable, which is an array of field objects. By default it has the following configuration, where all fields are required. Note that the FirstName, LastName and Email fields will be automatically hidden and set based on the authenticated user (from VB's $application.user object) when a user is logged in.

[
  {
    "enabled": "enabled",
    "name": "FirstName",
    "required": true
  },
  {
    "enabled": "enabled",
    "name": "LastName",
    "required": true
  },
  {
    "enabled": "enabled",
    "name": "Email",
    "required": true
  },
  {
    "enabled": "enabled",
    "name": "Title",
    "required": true
  }
]

See Field Dependencies for an example chatLaunchFormFields configuration with custom fields.

Field Properties

Different fields support a subset of the properties in the table below, where the Scope column is one the following values and indicates which fields support it:

• all: Supported in all fields: visible, hidden, standard and custom
• visible: All visible fields, standard and custom
• custom: All custom fields, visible and hidden
• choiceList: Only visible custom fields of type choiceList
• text: Standard or custom fields of type text
• longText: Standard or custom fields of type longText

Standard Fields

The following standard fields are supported.

Notes

• While some fields may only make sense as hidden fields, ES is agnostic and allows any field to be visible or hidden.
• If used as a visible field, the Field Type column indicates the type of input field rendered in the form. See Field Types.
• The Value Type column indicates the type to use for the value property

Field Types

For custom fields, the type property can be any of the following field types, which match Fusion custom field types. To preload a custom field with a default value, specify a value property in the format of the Default Value Format column.

See Field Dependencies for an example chatLaunchFormFields configuration with custom fields.

Field Dependencies

Fields can be configured to show and hide based on the value of another field using the optional dependency property. Here is an example value of chatLaunchFormFields where the custom_flavor field will only appear when Ice cream is selected in the custom_dessert field.

[
  {
    "enabled": "enabled",
    "label": "What is your favorite dessert?",
    "listOfValues": [
      {
        "label": "Ice cream",
        "value": "1"
      },
      {
        "label": "Brownies",
        "value": "2"
      }
    ],
    "name": "custom_dessert",
    "type": "choiceList"
  },
  {
    "dependency": {
      "action": "show",
      "fieldName": "custom_dessert",
      "values": ["1"]
    },
    "enabled": "enabled",
    "name": "custom_flavor",
    "label": "What is your favorite ice cream flavor?",
    "type": "text"
  }
]

The dependency property is an object with the following fields:

Upgrade

25D to 26B

Until version 25D, Embedded Service was a pre-packaged application configured primarily by external properties. As of 26A, the formerly internal ES Visual Builder application is now offered as a template (or reference implementation), allowing for more flexibility and code level customization. In this transition, many of the properties supported in versions 25D and earlier were removed. As some were added back in 26B, it is recommended to skip 26A and migrate directly from 25D (or earlier) to 26B.

See below for a list of 25D properties and their level of support in 26B.