Purpose

This readme provides information regarding the sample provided here and the differences with the ODA Native Client SDK for Web.

Web Chat For Service 24D is based on Oracle Digital Assistant Native Client SDK for Web release 24.10.

Table of Contents

• Sample Files
• Settings
  • Setting Keys
  • Updating the Setting Keys
  • Custom Text Keys
  • Custom Icons
• Methods
• Connection Data
• Pre-launch Form
  • Fields
  • Field Labels
  • Field Validation
  • Dynamic Fields
• Persistence
• File and Location Sharing
• Message Types
  • System Message
  • Post Conversation Message
• Conversation Printing
• Multilingual Support
• Conditional Launch Button
  • Proactive Chat
  • Conditional Chat Link
• Additional Launch Button Settings
• Message Text Splitting
• Bot and Agent Name Customization
• Bot and Agent Client Greeting
• B2C Visitor Service
  • Page Peek and Visitor Browser History
  • Chat Offer Effectiveness
• Authorization
• Multiple Bots
• Off the Record and Sensitive Information
• End Conversation
• Content Security Policy (CSP)
• Upgrading
  • From 23.02 to 23.04
  • From 23.04 to 23.06
  • From 23.06 to 23.08
  • From 23.08 to 23.10
  • From 23.10 to 23.12
  • From 23.12 to 24B
  • From 24B to 24C
  • From 24C to 24D

Sample Files

The files index.html and settings.js are sample files provided to be able to easily start using WCFS.

The function initSdk can receive parameters to customize the connection and the pre-launch form behavior:

• name Name by which the chat widget should be referred, defaults to Bots
• showPreLaunchForm always(default) | never | initial, see Pre-launch Form for more details
• connectionData connectionData setting key values, see Connection Data for more details

Examples

<script src="scripts/wcfs-sdk.js" onload="initSdk()" defer></script>

<script src="scripts/wcfs-sdk.js" onload="initSdk('Bots')" defer></script>

<script src="scripts/wcfs-sdk.js" onload="initSdk('Bots', 'initial')" defer></script>

<script src="scripts/wcfs-sdk.js" onload="initSdk('Bots', 'always', {'subject': 'help', customfields: [{name: 'my_text_customfield', value: 'some value'}]})" defer></script>

<script src="scripts/wcfs-sdk.js" onload="initSdk('Bots', 'never', {'subject': 'help', 'email': 'test@test.com'})" defer></script>

Settings

Setting Keys

The following setting keys are specific to WCFS:

Changing or using the following setting keys are currently not supported by WCFS:

• Network Configuration
  • channelId
  • clientAuthEnabled
  • userId
• Feature Flags
  • enableAttachmentSecurity
  • enableAutocomplete
  • enableAutocompleteClientCache
  • enableCancelResponse
  • enableDefaultClientResponse
  • enableHeadless
  • enableLongPolling
  • enableSpeech
  • enableSpeechAutoSend
  • enableTabsSync
  • linkHandler
  • multiLangChat
  • shareMenuItems (see File and Location Sharing for more details)
  • speechLocale
  • ttsService
  • webViewConfig
• Functionality Configuration
  • defaultGreetingTimeout
  • enableLocalConversationHistory
  • initMessageOptions
  • initUserHiddenMessage
  • messageCacheSizeLimit
  • showPrevConvStatus
  • storageType
  • useCreatedOnTimestamp

Updating the Setting Keys

The following setting keys can be updated after WCFS has been initialized:

connectionData

See Connection Data for more details.

preLaunchFormFields

See Pre-launch Form for more details.

conditionalLaunchButtonDetails

See Conditional Launch Button for more details.

position

Use the updatePosition method the same way you would set the position setting key. Omitted position attributes will not be updated.

Note that the position setting key sets the bottom right point of the widget.

For example, considering that the default position is:

position: {
    top: '',
    bottom: '20px',
    left: '',
    right: '20px'
}

The following will move the widget 80 pixels to the left:

Bots.updatePosition({
    right: '100px'
});

See the ODA Native Client SDK for Web for more details about the position setting key.

Custom Text Keys

The following custom text keys are specific to WCFS:

Custom Icons

WCFS has introduced default values for the following existing icons:

• avatarAgent
• avatarBot
• avatarUser

To clear them just set them as empty strings:

icons: {
    avatarAgent: '',
    avatarBot: '',
    avatarUser: ''
}

Notes:

• To display a custom avatarAgent icon the avatarBot key needs an icon, either the default one or a custom one.
• When avatarAgent has no custom icon set then:
  • When there is an agent name then the icon is a badge with the agent's name initials. This is WCFS's default.
  • When the agent name has been removed then the default avatarAgent icon is shown. For more details see Bot and Agent Name Customization.

The following custom icons are specific to WCFS and come with default values:

• infoMessage icon shown when the system user posts an information message
• warningMessage icon shown when the system user posts a warning message
• errorMessage icon shown when the system user posts an error message
• downloadMessage icon shown when the system user is downloading an attachment
• sensitiveInformationMessage icon shown when the system user posts the sensitiveInformationMessage message
• offTheRecordOffMessage icon shown when the system user posts the offTheRecordOffMessage message
• offTheRecordOnMessage icon shown when the system user posts the offTheRecordOnMessage message
• offTheRecordOff menu icon that indicates that off the record is disabled
• offTheRecordOn menu icon that indicates that off the record is enabled

For more information on how to customize icons go to the ODA Native Client SDK for Web documentation.

Methods

The following methods are specific to WCFS:

The following web-sdk methods are not supported by WCFS:

• cancelTTS
• getAgentDetails
• getSuggestions
• getTTSVoice
• getTTSVoices
• getUnreadMessagesCount
• sendAttachment
• sendMessage
• sendUserTypingStatus
• setAgentDetails
• setAllMessagesAsRead
• setPrimaryChatLanguage
• setSkillVoices
• setSpeechLocale
• setTTSService
• setTTSVoice
• setUserAvatar
• speakTTS
• startVoiceRecording
• stopVoiceRecording
• updateUser

Connection Data

The widget can be opened passing default connection data before starting the conversation without any user interaction. For example for a logged in user pass the email address.

Supported connectionData keys with their mappings:

Notes:

• When serviceRequestNumber is provided with no incidentType it will default to SVC_SERVICE_REQUESTS.
• incidentSeverityCode requires serviceRequestNumber to be set as well in order to work.
• You can also include your own custom fields to set default values. In case of Fusion you need to be at least at version 11.13.23.04.0.
• connectionData is only required if you want to set default values.
• B2C service fields have a maximum length as follows:
  • subject 240 characters.
  • firstName and lastName 80 characters.
  • Other fields 255 characters.

Example with all custom field type use cases:

connectionData: {
    lastName: 'Anonymous',
    queueId: '25',
    productId: '2',
    customFields: [
        { name: 'my_text_customfield', value:'Single line' },
        { name: 'my_textarea_customfield', value: 'Line1\nLine2' },
        { name: 'my_integer_customfield', value: 99 }, // '99' is also valid
        { name: 'my_yesno_customfield', value: '0' }, // '0' = No, '1' = Yes
        { name: 'my_menu_customfield', value: '2' }, // The index of the menu item (1 is the first item)
        { name: 'my_date_customfield', value: '2022-10-24' },
        { name: 'my_datetime_customfield', value: '2020-08-01T20:40:00+05:30' }
    ]
}

Updating the Connection Data

You can update the data with the updateConnectionData method. When it is executed while a connection has already be established it will only take effect on the next connection.

Example:

Bots.updateConnectionData({
    email: 'new.email@test.com',
    customFields: [{ name: 'my_text_customfield', value: 'Hello World!' }]
});

Pre-launch Form

All the connection data attributes can also be entered via a pre-launch form which will pre-fill the fields with their eventual default value set in connectionData.

By default the pre-launch form is secured to prevent users to modify it in the browser, this will avoid them to be able to start a chat session by by-passing its validations.

You can disable this security check with the following setting key:

enablePlfSecurity: false // (default is true)

Fields

Configure the preLaunchFormFields setting to customize the fields to show in the pre-launch form. The name key is the only required one.

• name One of the supported connectionData keys (see table above) or your custom field name.
• required Mark the fields as mandatory: false (default) | true.
• relaunchValue What has to happen to the field value for the next conversation.
  • clear This will set the value to ''.
  • default This will reset the field to its default value, when empty it does the same as clear.
  • keep This will pass the value from the previous conversation.
• options An array of value and text keys that when present will render an input drop-down list instead of an input field.
• customFieldType When the field is a custom field specify its type: text (default) | integer | textArea | date | dateTime | yesNo | menu(*).
• pattern Optional regular expression for fields of type 'text'.

(*) customFieldType "menu" requires options for the drop-down list values.

Example with all custom field type use cases:

preLaunchFormFields: [
    {name: 'subject', required: false, relaunchValue: 'clear'},
    {name: 'firstName', required: true, relaunchValue: 'keep'},
    {name: 'lastName', required: true, relaunchValue: 'keep'},
    {name: 'email', required: true, relaunchValue: 'keep'},
    {name: 'productId', required: true, relaunchValue: 'default',
        options: [
            {value: '1', text: 'Product group 1',
                children: [
                    {value: '11', text: 'Product name 1-1'},
                    {value: '12', text: 'Product name 1-2'}
                ]
            },
            {value: '2', text: 'Product group 2',
                children: [
                    {value: '21', text: 'Product name 2-1'},
                    {value: '22', text: 'Product name 2-2'}
                ]
            }
        ]
    },
    {name: 'my_text_customfield', required: false, relaunchValue: 'keep', customFieldType: 'text'},
    {name: 'my_textarea_customfield', required: false, relaunchValue: 'keep', customFieldType: 'textArea'},
    {name: 'my_integer_customfield', required: false, relaunchValue: 'keep', customFieldType: 'integer'},
    {name: 'my_yesno_customfield', required: false, relaunchValue: 'keep', customFieldType: 'yesNo'},
    {name: 'my_menu_customfield', required: false, relaunchValue: 'keep', customFieldType: 'menu'
        options: [ // menu requires options
            {value: '1', text: 'Menu item 1'},
            {value: '2', text: 'Menu item 2'},
            {value: '3', text: 'Menu item 3'}
            ]
    },
    {name: 'my_date_customfield', required: false, relaunchValue: 'keep', customFieldType: 'date'},
    {name: 'my_datetime_customfield', required: false, relaunchValue: 'keep', customFieldType: 'dateTime'}
]

Field Labels

For the standard field labels see the custom text keys starting with plf in the Settings section for the default values.

For custom field labels add a key in i18n that concatenates the field name with the word Label. As an example for the custom fields above:

i18n: {
    en: {
        my_text_customfieldLabel: 'Text Field',
        my_textarea_customfieldLabel: 'Text Area',
        my_integer_customfieldLabel: 'Integer',
        my_yesno_customfieldLabel: 'Yes / No',
        my_menu_customfieldLabel: 'Menu',
        my_date_customfieldLabel: 'Date',
        my_datetime_customfieldLabel: 'Date Time'
    }
}

Field Validation

You can set the pattern attribute for the standard fields and the custom fields of type text with a regular expression to determine if the value of the field is valid. If the field is not valid you can also add a custom message to i18n by adding a key that is the concatenation of the field name and the word Message. Here is an example for a standard field and a custom field.

preLaunchFormFields: [
    {
        name: 'firstName',
        required: true,
        pattern: '[a-zA-Z]{1,15}'
    },
    {
        name: 'birthDate',
        required: true,
        customFieldType: 'text',
        pattern: '[0-9]{4}-(0[1-9]|1[012])-(0[1-9]|1[0-9]|2[0-9]|3[01])'
    }
],
i18n: {
    en: {
        firstNameMessage: 'No numbers and max 15 characters',
        birthDateLabel: 'Birth Date',
        birthDateMessage: 'Date format: YYYY-MM-DD'
    }
}

When no entry has been added to i18n then the default browser message Please match the required format will be shown.

Dynamic Fields

You can make the visibility of the fields dynamic by adding dependencies. You can either hide or show a field when another one matches a value or a regular expression.

Add a dependency attribute to the field with the following attributes:

• fieldName The name of the field this field depends on.
• action Either show or hide this field.
• values An array of values or regular expressions. When the dependent field matches one of these, the action on this field is triggered.
• enableRegExp When set to true the expected values are regular expressions, the default is false.

When a field is hidden it will restore the value based on its relaunchValue, see Fields for more details.

Here are some examples that demonstrate how it works:

• Show a language field when the country is Other, and when the selected language is Spanish ask if it is Latin Spanish:

preLaunchFormFields: [
    {
        name: 'country',
        required: true,
        customFieldType: 'menu',
        options: [ { value: 'US', text: 'United States' }, { value: 'UK', text: 'United Kingdom'}, { value: 'AU', text: 'Australia'}, { value: 'Other', text: 'Other Country' } ]
    },
    {
        name: 'language',
        required: true,
        customFieldType: 'menu',
        options: [ { value: 'ES', text: 'Spanish' }, { value: 'IT', text: 'Italian' }, { value: 'FR', text: 'French' }, { value: 'DE', text: 'German' } ],
        dependency: {
            fieldName: 'country',
            action: 'show',
            values: ['Other']
        }
    },
    {
        name: 'latin',
        required: true,
        customFieldType: 'yesNo',
        dependency: {
            fieldName: 'language',
            action: 'show',
            values: ['ES']
        }
    }
],
i18n: {
    en: {
        countryLabel: 'Country',
        languageLabel: 'Language',
        latinLabel: 'Latin'
    }
}

• The above example illustrates the show action, the same can be achieved by using the hide action on the language field by changing the dependency attribute as follows:

dependency: {
    fieldName: 'country',
    action: 'hide',
    values: ['US', 'UK', 'AU', '']
}

• This example illustrates the regular expression matching. A ZIP code field is shown when the tracking ID starts with either 123 or 321.

preLaunchFormFields: [
    {
        name: 'trackingId',
        required: true,
        customFieldType: 'text',
        pattern: '[0-9]{10}',
    },
    {
        name: 'zipCode',
        required: true,
        customFieldType: 'text',
        dependency: {
            fieldName: 'trackingId',
            action: 'show',
            values: ['^123[0-9]{7}', '^321[0-9]{7}'],
            enableRegExp: true
        }
    }
],
i18n: {
    en: {
        trackingIdLabel: 'Tracking ID',
        zipCodeLabel: 'ZIP Code',
        trackingIdMessage: 'Enter a 10 digit tracking ID'
    }
}

Header and Footer

You can add a header and / or a footer using the following custom text keys:

• plfHeaderHtml
• plfFooterHtml

By default they are blank so no header and / or footer are added to the pre-launch form field unless they are defined.

Example:

i18n: {
    en: {
        plfHeaderHtml: '<span style="font-size: x-large; font-weight:bold;">Live Chat</span>',
        plfFooterHtml: 'By clicking on Start Chat, you are agreeing to our <a href="https://www.oracle.com/legal/terms.html" target="_blank"> terms of service</a>.'
    }
}

Resetting the Pre-launch Form

You can reset the fields with the resetPreLaunchForm method. This will clear the previous one and update it with the new fields.

As an example, if you would have initiated the widget with 3 fields, firstName, lastName and email and you would want to add a subject field you would have to do:

Bots.resetPreLaunchForm([
    { name: 'subject', required: false, relaunchValue: 'keep' },
    { name: 'firstName', required: true, relaunchValue: 'default' },
    { name: 'lastName', required: true, relaunchValue: 'default' },
    { name: 'email', required: true, relaunchValue: 'default' }
]);
// Optionally set a default value
Bots.updateConnectionData({
    subject: 'help'
});

Start-up Behaviour

Use the following values to customize the showPreLaunchForm setting:

• always This is the default, every time a new conversation is started the form will be shown before connecting and starting the conversation.
• initial The form will only open once, when connecting for the first time. The pre-launch form allows the user to interact before starting the conversation and provide supported profile information like a an email, a product, etc…
• never Connect and start the conversation without any user interaction.

Color Customization

The pre-launch form is using the WEB SDK popup and form and thus uses these associated existing CSS variables:

Persistence

When a connection is established and persistence is enabled then data is stored in session storage that will be reused to re-establish the connection to Chat after navigating away or reloading the page.

When using multiple bots on the same page make sure they have different names, for more details see Multiple Bots.

When you need to know before instantiating the widget if it will be starting a new connection or if it will be restoring a previous one, you can use the isNewSession method providing the bot name, it will return true or false.

Example without a bot name:

let newSession = WCFSSDK.isNewSession(); // defaults to 'wcfs'

Example with a bot name:

let newSession = WCFSSDK.isNewSession('my-chatbot');

When the chat is not persistent and the page is closed, left or reloaded then the connection will be closed. You can decide which of the following events handles it:

• unload
• beforeunload (default, not compatible with showPageLeaveWarning)
• pagehide

Example:

disconnectEvent: 'pagehide'

File and Location Sharing

To manage file and location sharing use these 4 settings:

• enableAttachment to show the share file menu item when clicking the share button
• attachmentSettings set file upload and download settings depending on your service
• attachmentMode when to show the share file menu item
  • agent default value, shows the share file menu item when connected to an agent
  • agentAndBot shows the share file menu item when connected either to an agent or a bot (*)
  • agentAndBotSkill shows the share file menu item when connected either to an agent or a bot with the difference that the skill is controlling when the menu item is shown (*)
• enableLocation to show the share location menu item when clicking the share button

Notes:

• With the values of these settings WCFS will be dynamically setting shareMenuItems to build the share button menu list values.
• (*) When uploading a file to a bot DA As An Agent does not handle the file. Only the metadata is available thru the ${system.message.payload} variable. Consuming the file will require a custom implementation depending on the service.

You can also decide if the agent can send files to WCFS, this is enabled by default:

• enableAgentAttachment

Maximum File Size

B2C Service

The maximum file size is not customizable in WCFS. The default value for Oracle hosted mailboxes is 20 MB with a maximum of 120 MB. For more information see Answer Id 208.

Fusion Service

When WCFS is used anonymously the maximum file size will depend on the browser's resources to process large blobs as the file is uploaded as a converted base64 string. While as when the user is authenticated the limit will depend on the cloud resources WCFS is connected to such as disk storage, memory, etc.

The default WCFS maximum upload size is set 200 MB, to customize it use attachmentSettings setting key.

Example, set the maximum size to 1 GB:

attachmentSettings: {
   maxFileSizeMb : 1024
}

File Types Restriction

To avoid server side validation when uploading invalid file types, make sure that WCFS is configured with those that the server will accept. You can also configure WCFS with a subset of them.

B2C Service

The B2C default files types for WCFS 24B and higher are:

• png jpg txt gif pdf docx bmp doc csv xlsx xls jpeg odt odm ods odp odf msg eml rtf ppt pptx htm html zip wav mov mp4 mp3

If you are on CX version 23A+ or higher and if you have changed the default file types you will have to do the same in WCFS using the attachmentSettings setting key. For more information see Answer ID 12603.

Example:

attachmentSettings: {
    supportedFileTypes: 'jpg png gif mp3 mp4' // Modified VALID_FILE_EXTENSIONS or subset
}

Prior CX version 23A+ the file types are static and you will have to configure WCFS to use the old default ones for the client validation to be in sync with the server:

attachmentSettings: {
    supportedFileTypes: 'bmp doc docx gif jpeg jpg pdf png txt xls xlsx'
}

Fusion Service

By default the Fusion service is not setting any default file types, the following file types are black listed on the client side:

• exe bat jsp jspx

To set the list of supported file types use the attachmentSettings setting key:

attachmentSettings: {
    supportedFileTypes: 'bmp gif jpeg jpg png' // Only pictures
}

Download Behavior

When WCFS is notified that the agent has shared a file it will retrieve the download link. By default WCFS will fetch the file into a blob and use its address for the anchor tag. Clicking the download link is only copying the file from memory to disk so it will be available after the session is closed.

For the B2C service there is no choice as the download link requires extra headers and can't be consumed without a fetch.

For the Fusion service the link can also be used as a get, meaning that WCFS can offer the alternative to directly put the download link into the anchor and only download the file when the user clicks on it. The drawback is that when the session is closed the download link can't be consumed anymore. To change WCFS to this behavior add this setting to the attachmentSettings setting:

attachmentSettings: {
    standardDownload: false // (default is true)
}

Attachment Mode agentAndBotSkill

When attachmentMode is set to agentAndBotSkill and WCFS is connected to a bot then the file menu item will be shown and removed when the skill sends a request to do so using the ODA osvc channel extension.

Set the channel custom property enableFileSharing to one of these values:

• true show the share file menu item
• false remove the share file menu item
• once show the share file menu item and remove it just after receiving the response

Simple examples that illustrate how enableFileSharing works:

• true / false use case that gives control to show and remove the share file menu item at will.

  # show the share file menu item
  show_share:
    component: "System.CommonResponse"
    properties:
      processUserMessage: false
      keepTurn: false
      metadata:
        responseItems:
        - type: "text"
          text: "Upload is now enabled."
          channelCustomProperties:
          - channel: "osvc"
            properties:
              enableFileSharing: "true"
    transitions:
      return: "done"

  # remove the share file menu item
  remove_share:
    component: "System.CommonResponse"
    properties:
      processUserMessage: false
      keepTurn: false
      metadata:
        responseItems:
        - type: "text"
          text: "Upload is now disabled."
          channelCustomProperties:
          - channel: "osvc"
            properties:
              enableFileSharing: "false"
    transitions:
      return: "done"

• once use case that shows the share file menu item and removes it after receiving the response.

  # Request the user to upload a file
  share_once:
    component: "System.CommonResponse"
    properties:
      processUserMessage: true
      keepTurn: false
      metadata:
        responseItems:
        - type: "text"
          text: "Upload your file now !!!"
          channelCustomProperties:
          - channel: "osvc"
            properties:
              enableFileSharing: "once"
    transitions:
      next: "uploaded"

  # Notify the user the file has been received
  uploaded:
    component: "System.Output"
    properties:
      text: "Thanks, got your file ${system.message.payload.userFName} !!!"
    transitions:
      return: "done"

Message Types

System Message

There are circumstances when the user is not ending the conversation:

• The agent concludes it
• A timeout occurs
• Cannot recover from a network error
• ...

When one of the above events happens a system message with the reason is shown followed by another customizable one with one or two customizable buttons (depending if embedded mode is enabled):

• Message
  • Custom text key: systemPostConversationMessage
• Start a new conversation
  • Setting Key: showSystemMessageMinimizeButton (default true)
  • Custom text key: systemPostConversationStartButtonLabel
• Minimize the widget (not supported in embedded mode)
  • Setting Key: showSystemMessageMinimizeButton (default true)
  • Custom text key: systemPostConversationCloseButtonLabel

When both buttons are disabled and the value of the message custom text key is empty then nothing is shown, in other words it is disabling the system message.

Post Conversation Message

When the user ends the conversation you might want to interrupt closing the widget to show a special message, most probably to offer a survey. Same for the agent, you might want to show something else than the default system message.

When you enable enablePostConversationMessage then the post conversation message is shown when either the agent or the user ends the conversation.

Because the most common usage of this feature will be for surveys the default values of the custom text keys postConversationMessage and postConversationMessageLinkButtonLabel are set for this purpose as an example.

Below this post conversation message the same buttons as the system message to minimize the widget and to start a new conversation are shown depending on theirs settings (showSystemMessageMinimizeButton and showSystemMessageMinimizeButton), see System Message.

There is also an optional button that can be added which allows to print the conversation, see Conversation Printing.

There are 3 types of post conversation messages:

Type message

When the conversation is ended the message associated to the text key postConversationMessage is shown.

Example:

enablePostConversationMessage: true,
postConversationMessageOptions: {
    type: 'message'
}

Type link

Same as message with a button with the text from postConversationMessageLinkButtonLabel, it will open the custom URL.

Example:

enablePostConversationMessage: true,
postConversationMessageOptions: {
    type: 'link',
    url: 'http://mysurvey.com/'
}

Type iframe

Same as message but render an iframe with a custom URL. The iframeLocation setting allows to position it either in the message bubble or below the conversation.

Example:

enablePostConversationMessage: true,
postConversationMessageOptions: {
    type: 'iframe',
    iframeLocation: 'below', // bubble (default) | below
    url: 'http://mysurvey.com/',
    iframeStyles: [
        {name: 'min-height', value: '300px'}, // use min-height iso height
        {name: 'borderWidth', value: '0px'}
    ],
    enablePrintButton: true // Also show the print conversation button
}

B2C Survey Integration

B2C surveys links need the engagement ID in it, see Answer ID 11787 for more details.

You can use the URL Customization feature to achieve it, as an example:

postConversationMessageOptions: {
    type: 'link', // or iframe
    url: 'http://acme.custhelp.com/ci/documents/detail/5/11/6/223/7/{ENGAGEMENT_ID}/12/245cfe1718889dd43ee26d6654e354af8331c668)',
    urlParameters: [
        {fieldName: 'engagementId', substitutionString: '{ENGAGEMENT_ID}'}
    ]
}

URL Customization

You can customize the URL with substitution strings to add parameters that can be replaced by field values.

The following keys are supported:

• Connection Data keys (depending on your service, see Connection Data)
• Connection Data custom fields
• System keys:
  • engagementId
  • agentId - Fusion service only (*)
  • timestamp

(*) When the user has been transferred to different agents, agentID will then contain the last agent of the conversation.

For example:

enablePostConversationMessage: true,
postConversationMessageOptions: {
    type: 'link',
    url: 'http://myhost.com?pid={pid}&cf={cf}&aid={aid}&eid={eid}&ts={ts}',
    urlParameters: [
        {fieldName: 'productId', substitutionString: '{pid}'}, 
        {fieldName: 'customField', substitutionString: '{cf}'}, 
        {fieldName: 'agentId', substitutionString: '{aid}'}, 
        {fieldName: 'engagementId', substitutionString: '{eid}'},
        {fieldName: 'timestamp', substitutionString: '{ts}'}]
},
connectionData: {
    productId: '55555',
    customFields: [
        { name: 'customField', value: 'custom value' }
    ]
},

Would produce this URL:

http://myhost.com?pid=55555&cf=custom%20value&aid=300100098008382&eid=36996&ts=2024-09-18T08%3A29%3A24.295Z

Conversation Printing

To enable the print button, you need to enable enablePostConversationMessage (See Post Conversation Message) and add to postConversationMessageOptions the enablePrintButton setting Key. The custom text key of the button is postConversationPrintButtonLabel.

Example:

enablePostConversationMessage: true,
postConversationMessageOptions: {
    type: 'message',
    enablePrintButton: true // (default false)
}

The method invoked by enablePrintButton to print the conversation can also be used by calling printConversation.

Example:

Bots.printConversation();

Styles have been added as a @media print rule to improve the readability of the printed version of the conversation.

These are the default styles that can be tweaked and passed as a string using the printStyles setting key.

    svg * {
        display: none;
    }
    input {
        border: 0px;
    }
    textarea {
        border: 0px;
    }
    select {
        border: 0px;
    }
    .wcfs-split-text {
        display: unset!important;
    }
    .wcfs-split-button {
        display: none!important;
    }
    .CSS_PREFIX-icon-wrapper {
        display: none;
    }
    .CSS_PREFIX-message-block {
        padding-top: 12px;
    }
    .CSS_PREFIX-screen-reader-only {
        font-weight: bold;
    }
    .CSS_PREFIX-timestamp-header {
        font-weight: bold;
        padding-top: 12px;
        text-align: center;
    }
    .CSS_PREFIX-relative-timestamp {
        font-weight: bold;
        padding-top: 12px;
        text-align: center;
    }
    .CSS_PREFIX-icon {
        display: none!important;
    }
    .CSS_PREFIX-hr {
        font-weight: bold;
        padding-top: 12px;
        text-align: center;
    }
    .CSS_PREFIX-flex {
        display: block;
    }
    .CSS_PREFIX-none {
        display: block;
    }
    .CSS_PREFIX-listbox {
        display: none;
    }
    .CSS_PREFIX-button-cell {
        display: none;
    }
    .CSS_PREFIX-next {
        display: none;
    }
    .CSS_PREFIX-previous {
        display: none;
    }
    .CSS_PREFIX-attachment-controls {
        display: none;
    }
    .CSS_PREFIX-table-message-heading {
        font-weight: bold;
    }
    .CSS_PREFIX-form-message-key {
        font-weight: bold;
        display: initial;
        margin-right: 8px;
        vertical-align: top;
    }
    [dir="rtl"] .CSS_PREFIX-form-message-key {
        margin-left: 8px;
    }
    .CSS_PREFIX-form-message-value {
        display: initial;
    }
    .CSS_PREFIX-message {
        margin-top: 6px;
    }

The string CSS_PREFIX will be replaced with the value of the name setting which is used as CSS prefix.

Multilingual Support

B2C

The locale setting will only determine the WCFS UI language. The language for the live agent and the skill locale variable (profile.locale) are set by the interface (vhost).

Example:

URI: 'site-es-es.widget.host.com',
locale: 'es-ES'

Fusion

Starting WCFS 23.04 & Fusion 23C the locale setting will set the WCFS UI, the live agent language and the skill locale variable (profile.locale).

Example:

locale: 'es-ES'

ODA Skill Languages

For a skill that supports more than one language with resource bundles you need to set the languageTag. If not it will default to its Primary Language.

Example:

setLanguage:
    component: "System.SetVariable"
    properties:
        variable: "profile.languageTag"
        value: "${profile.locale}"
    transitions:
        next: "..."  

multiLangChat Setting

WCFS does not support dynamicaly changing the language during the conversation, so the Oracle Digital Assistant Native Client SDK for Web setting multiLangChat is NOT supported.

Conditional Launch Button

When conditionalLaunchButton is enabled and combined with conditionalLaunchButtonDetails a call is done to Chat when the widget is loaded to retrieve availability information that will determine if the launch button is shown or not.

The setting conditionalLaunchButton can have 4 values:

• off: The launch button is always shown.
• officeHours: The launch button is not shown out of office hours or during holidays (only for B2C service).
• liveAgent: The launch button is shown when there is at least one available agent session.
• custom: Customise your own condition combining any of agent session availability, queue size and queue wait time.

Queue Parameters

You can fine tune the call by setting these parameters:

• queueId a comma separated string of queue IDs (cannot be combined with productId or categoryId)
• productId a product ID (only for service B2C and cannot be combined with queueId)
• categoryId a category ID (cannot be combined with queueId)

Example:

conditionalLaunchButton: 'liveAgent',
conditionalLaunchButtonDetails: {
    queueId: '23, 56'
}

Availability Conditions

You can fine tune the availability condition with the following parameters by setting conditionalLaunchButtonDetails to custom and set one or more of these parameters:

• minAgentSessions: Minimum number of available agent sessions.
• maxQueueSize: Maximum number of end users that can be added to a queue.
• maxWaitSeconds: Maximum wait time in queue in seconds.

For example, if you would want to show the button only when the wait time is less than a minute and there are less than 5 end users in the queue:

conditionalLaunchButton: 'custom',
conditionalLaunchButtonDetails: {
    maxQueueSize: '5',
    maxWaitSeconds: '60'
}

Notes:

• Combining minAgentSessions with maxQueueSize or maxWaitSeconds does not make much sense.
• Setting conditionalLaunchButton to liveAgent is just a shortcut, these 2 are the same:

conditionalLaunchButton: 'liveAgent',
conditionalLaunchButtonDetails: {
    categoryId: '23'
}

conditionalLaunchButton: 'custom',
conditionalLaunchButtonDetails: {
    minAgentSessions: '1'
    categoryId: '23'
}

Polling

When enabled, WCFS will continue evaluating the condition that determines if to show the launch button or not. WCFS will then poll every 12 seconds for the first 5 minutes. Thereafter, WCFS will poll once a minute for the next 55 minutes and will stop after 1 hour.

Example:

conditionalLaunchButtonDetails: {
    enablePolling: true
}

Updating the conditionalLaunchButtonDetails

You can update the condition details with the updateConditionalLaunchButtonDetails method any time.

Example:

Bots.updateConditionalLaunchButtonDetails({
    enablePolling: true,
    queueId: '98'
});

Note that it also allows you to stop and start the polling.

Examples

• Only on load check for available agents providing category 45:

conditionalLaunchButton: 'liveAgent',
conditionalLaunchButtonDetails: {
    categoryId: '45'
}

• For queue 33 only show the launch button when end users would not have to wait for more than 5 minutes:

conditionalLaunchButton: 'custom',
conditionalLaunchButtonDetails: {
    enablePolling: true,
    queueId: '33',
    maxWaitSeconds: '300'
}

Proactive Chat

Proactive Chat is an extension of the Conditional Launch Button feature, instead of showing the launch button it will display a dialog with a chat invitation.

First configure the agent availability condition and polling settings as described in the Conditional Launch Button section above.

Use the enableProactiveChat setting key to enable proactive chat:

conditionalLaunchButton: 'liveAgent',
enableProactiveChat: true

It is not mandatory to set conditions. If you only enable proactive chat then the dialog will be immediately shown when loading the widget.

Dialog Customization

This is a schema of the dialog with the custom text keys, and the class and style attributes:

<dialog class="dialogClasses" style="dialogStyles">
    <div class="dialogTitleClasses" style="dialogTitleStyles">pacDialogTitleHtml</div>
    <div class="dialogTextClasses" style="dialogTextStyles">pacDialogTextHtml</div>
    <div class="dialogButtonsClasses" style="dialogButtonsStyles">
        <button class="dialogNoButtonClasses" style="dialogNoButtonStyles">pacNoButtonLabel</button>
        <button class="dialogYesButtonClasses" style="dialogYesButtonStyles">pacYesButtonLabel</button>
    </div>
</dialog>

Custom Text Keys

The dialog can be customized with the following custom text keys as shown in the above dialog schema:

• pacDialogTitleHtml
• pacDialogTextHtml
• pacNoButtonLabel
• pacYesButtonLabel

Styling

You can apply classes and / or styles to the dialog with the proactiveChatDialogCss setting key using the following attributes as shown in the above dialog schema:

• dialogClasses
• dialogStyles
• dialogTitleClasses
• dialogTitleStyles
• dialogTextClasses
• dialogTextStyles
• dialogButtonsClasses
• dialogButtonsStyles
• dialogNoButtonClasses
• dialogNoButtonStyles
• dialogYesButtonClasses
• dialogYesButtonStyles

Classes

A string containing one ore multiples classes can be passed to the classes attributes:

proactiveChatDialogCss: {
    dialogClasses: 'dialog-class base-class'
}

Styles

An array of name–value pairs can be passed to the styles attribute:

proactiveChatDialogCss: {
    dialogStyles: [
        {name: 'padding', value: '0px'},
        {name: 'border-color', value: 'darkgray'}
    ]
}

Page Launch Alternative

As an alternative instead of opening the hidden chat widget, you can launch a page based upon the URL defined in the proactiveChatUrl setting key.

proactiveChatUrl: {
    url: 'https://myURL',
    windowFeaturesParameter: [ // An array of name–value pairs for the window.open features parameter
        {name: 'height', value: '620'},
        {name: 'width', value: '380'}
    ]
}

Conditional Chat Link

Conditional Chat Link is also an extension of the Conditional Launch Button feature, instead of showing the launch button it will show a link in your web page.

First configure the agent availability condition and polling settings as described in the Conditional Launch Button section above.

Use the enableConditionalChatLink and conditionalChatLinkElementId setting keys and update your web page to configure the conditional chat link:

conditionalLaunchButton: 'liveAgent',
enableConditionalChatLink: true,
conditionalChatLinkElementId: 'wcfs-ccl'

<h5>Contact Us</h5>
<ul>
    <li><a>US Sales: +1.800.633.0738</a></li>
    <li><a>Global Contacts</a></li>
    <li><a>Subscribe to emails</a></li>
    <li id="wcfs-ccl"></li>
</ul>

Custom Text Keys

The link text and aria label can be changed using the following custom text keys:

• cclLinkAriaLabel
• cclLinkText

Styling

You can apply classes and / or styles to the link with the conditionalChatLinkCss setting key:

conditionalChatLinkCss: {
    styles: [
        {name: 'color', value: 'red'},
        {name: 'background-color', value: 'black'},
    ],
    classes: 'ccl-class'
},

Additional Launch Button Settings

Custom Text

By default the launch button will only show an icon, see Custom Icons for more details. You can add some text either to its right or left by enabling the setting enableText, the translation string key is launchButtonText.

Example:

launchButtonSettings: {
    enableText: true, // default is false
    textPosition: 'start' // end (default) | start
}

Styling

You can style the button by providing a valid array of style key pairs.

Example:

launchButtonSettings: {
    styles: [
        {name: 'color', value: 'white'},
        {name: 'height', value: '75px'},
        {name: 'width', value: '200px'},
        {name: 'font-size', value: 'large'},
        {name: 'border-radius', value: '25px'}
    ]
}

Message Text Splitting

When the full answer intent is too long you can configure WCFS to only show part of the message with a button that will toggle the visibility of the rest of the message. Set splitText to one of these values with a tag or position in splitTextSettings:

• tag: The text will split using a tag that is added to the skill text and defined in splitTextSettings, for example:

splitText:
  component: "System.Output"
  properties:
    text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.{split} Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
  transitions:
    return: "done"

splitText: 'tag',
splitTextSettings: {
    tag: '{split}'
}

• hardPosition: The text will split at the position defined in splitTextSettings, for example:

splitText: 'hardPosition',
splitTextSettings: {
    position: 100
}

• softPosition: For languages that use a space as delimiter between words, avoid word truncation by splitting the text at the first space before the position defined in splitTextSettings, for example:

splitText: 'softPosition',
splitTextSettings: {
    position: 100
}

• off: No text splitting (default)

Notes

• splitTextSettings has no default values, so if splitText is enabled without any settings no text splitting will occur.
• Only the tag option supports HTML text splitting, but make sure you have correct HTML before and after the tag. softPosition & hardPosition options will not split the text when HTML is detected.
• When a tag is provided in splitTextSettings but splitText is not set to tag, then the tag will still be removed. This will allow having tags in the text and be able to disable splitText or use it with hardPosition or softPosition. For example:

splitText: 'softPosition',
splitTextSettings: {
    tag: '{split}',
    position: 100
}

Bot and Agent Name Customization

You can customize the name of the bot and the name of the agent in the conversation. Use the following setting keys:

• botNameMode
• agentNameMode

Set them to one of these values:

• noName The name is not shown (default value for botNameMode)
• fullName The name received from the chat server is shown (default value for agentNameMode)
• firstName First 'word' of the name received from the chat server is shown
• lastName Last 'word' of the name received from the chat server is shown
• defaultName The value from a custom text key is shown:
  • For the bot: bot
  • For the agent: agent (See ODA Native Client SDK for Web for more details)

These settings will also affect the substitution strings of the Bot and Agent Client Greeting.

For example to use the client custom text key for the bot and the first name for the agent:

botNameMode: 'defaultName',
agentNameMode: 'firstName'

Bot and Agent Client Greeting

By default the greeting displayed by WCFS when connecting is the one received from Chat. You can overwrite it with a client one defined as a custom text key.

• Bot

  • Setting key: enableClientGreetingBot
  • Custom text key: clientGreetingBot

• Agent

  • Setting key: enableClientGreetingAgent
  • Custom text key: clientGreetingAgent
  • The custom greeting is only used in the client, the transcript and agent console use the server one

Notes:

• When the custom text key is set to an empty string then no greeting is show.
• The substitution string of the name in the custom text key is the one set by its corresponding Bot and Agent Name Customization.

B2C Visitor Service

Page Peek and Visitor Browser History

Page Peek and Visitor Browser History are available when using Engagement Engine to invoke WCFS and no settings are required for these features.

Chat Offer Effectiveness

When invoking WCFS using Engagement Engine with Proactive Chat or Conditional Chat Link enabled, the Visitor Service events offer and accept are recorded in the visitor_sessions and roi_conversion_offer_stats tables. No settings are required for this feature.

Authorization

For Fusion we allow you to add a JWT to the settings that will be used to start a chat for an authenticated user:

authorization: {
    type: "bearer",
    token: "insert JWT here"
}

The JWT can be retrieved from the Fusion token relay service.

Multiple Bots

You can setup more than one bot on the same page but they need to have different names. The default value of the name setting key is wcfs. To change it:

name: 'my-second-bot'

As a reminder the description of the name setting key form the ODA Native Client SDK for Web Documentation.

The name for the instance. Provides a namespace to the instance and is used as prefix for the CSS class names and element IDs.

WCFS uses it to manage persistent conversations.

Off the Record and Sensitive Information

Off the Record

You can give the user the ability to send off the record messages to the agent by adding a button in the header to toggle it on or off. To enable the feature set the enableOffTheRecord to true:

enableOffTheRecord: true

Note that off the record messages is not designed to work with ODA skills, ODA will still store the messages.

Sensitive Information

You can enable WCFS to examine the messages for sensitive information such as credit card and social security number patterns.

When sensitive information is detected the message can be:

• sent off the record
• sent partially or full masked
• sent off the record and masked (partially or full)

There are patterns built-in into WCFS but you can also use your own regular expressions. The built-in pattern setting values are:

• creditCard
• socialSecurity

Off the Record

To enable sensitive information detection to send the messages off the record set the offTheRecordPatterns setting key. For example enable it for both credit card, social security numbers and your own pattern:

offTheRecordPatterns: [ 'creditCard', 'socialSecurity', '[0-9]{4}[a-z]{2}' ]

Note that the message is not only sent off the record, the message is also not stored in the browser's storage which is mainly used for persistent chats.

Masking

To enable sensitive information detection to send the detected values masked set the maskingPatterns setting key.

You can also customize the masking using the following setting keys:

• maskingCharacter The character masking the sensitive information string, the default is '#'
• maskingMode
  • full Fully replace the matched pattern (default)
  • partial Partially replace the matched pattern showing only the last 4 characters

For example enable it to match both credit card patterns and your own pattern and overwrite the default options:

maskingPatterns: [ 'creditCard', '[0-9]{4}[a-z]{2}' ],
maskingCharacter: '*', // default is '#'
maskingMode: 'partial', // default is 'full'

subject Connection Data

When maskingPatterns is set then any sensitive information detected in the subject will also be masked.

Mind when offTheRecordPatterns is set, the subject cannot be sent off the record when it contains sensitive information. To avoid the sensitive information to be recorded, it will be sent masked.

End Conversation

Enabling the enableEndConversation setting key adds a close button which is only effective when there is an active session, see the ODA Native Client SDK for Web for more details.

WCFS has added a new setting key enableEndConversationButtonToClose to extend the functionality of this button to allow it to close the widget when:

• The pre-launch form is shown
• The session has ended with a System Message
• The session has ended with a Post Conversation Message

Example:

enableEndConversationButtonToClose: true

For the button the label a new custom text key endConversationAndClose has also been added to reflect that it is not only to end the conversation but to close the widget.

Note that this setting is not supported in embedded mode.

By default when the widget is closed the converation is also cleared, meaning that when the widget is opened again the new conversation will start with an empty transcript. You can change this behavior by using the clearConversationOnClose setting key:

clearConversationOnClose: false

Note that in embedded mode this will also work but when the conversation is ended.

Content Security Policy (CSP)

Content Security Policy (CSP) is an added layer of security that helps detecting and mitigating certain types of attack, including Cross-Site Scripting (XSS) and data injection attacks. WCFS supports the use of CSP.

Styling

If your CSP has a restrictive style-src, style-src-attr or style-src-elem then WCFS styling will not work out of the box. To get WCFS working you need to disableInlineCSS:

disableInlineCSS: true

This will prevent WCFS from doing any disallowed styling. To get styling back, you will need to add the CSS file to your webpage yourself:

<link rel="stylesheet" href="./styles/styles.css">

Notes:

• You need to take care that the CSS file can actually be loaded by using for example a nonce or by allowing the CSS URL in your CSP rules.
• Our example application contains an icon logo that contains inline CSS. You should replace or remove this logo.

Scripting

If your CSP has a restrictive script-src, script-src-attr or script-src-elem then our example will not work as-is. The wcfs-sdk.js is loaded with a script tag that has an onload. We recommend removing the onload and add the initSdk to the settings.js:

initSdk('Bots');

Other Restrictions

If you have a restrictive connect-src you need to make sure the chat widget can connect to the configured URL, as well to the chat server. Make sure you wildcard the chat server correctly so that your chat continues working after upgrades.

Take care you review other restrictions as well. For example if users can receive images over chat then the img-src might need to be updated, or if users can receive videos or pdf files then object-src or frame-src might need to be updated.

Upgrading

From 23.02 to 23.04

Location Sharing

Previously to enable the location sharing the setting enableAttachment had to be enabled. In WCFS 23.04 this will enable file sharing so the new parameter enableLocation should be used instead.

Custom Fields

The way custom fields are specified and how default values are set have changed in 23.04. This example shows how to change the connectionData:

23.02

connectionData: {
    firstName: 'anonymous',
    lastName: 'anonymous',
    email: 'anonymous@test.com',
    custom_field_test: 'test',
    custom_field_dummy: 'dummy'
}

23.04

connectionData: {
    firstName: 'anonymous',
    lastName: 'anonymous',
    email: 'anonymous@test.com',
    customFields: [
        { name: 'custom_field_test', value: 'test'},
        { name: 'custom_field_dummy', value: 'dummy'}
    ]
}

From 23.04 to 23.06

Fusion Service Version

The serviceVersion setting used for Fusion is not required anymore and has been removed.

End Session Messages

The custom text key sessionReconnectButtonLabel has been removed.

The end session messages had a button to start a new conversation that has been removed. A follow-up message is now shown with 2 buttons, one to start a new conversation and another one to close the widget. Their respective new custom text keys are:

• systemPostConversationMessage
• systemPostConversationStartButtonLabel
• systemPostConversationCloseButtonLabel

Off the Record Messages

• offTheRecordOffButtonLabel
• offTheRecordOffMessage
• offTheRecordOnButtonLabel
• offTheRecordOnMessage
• sensitiveInformationMessage

From 23.06 to 23.08

New custom text keys

• holidayMessage
• noAgentsMessage
• outOfHoursMessage
• launchButtonText
• splitTextLessButtonLabel
• splitTextMoreButtonLabel

From 23.08 to 23.10

launchButtonSettings

The margins of the text of the launchButtonSettings have been removed.

From 23.10 to 23.12

New custom text keys

• networkWarningMessage
• agentAbsentMessage
• system
• postConversationPrintButtonLabel

Deprecated custom text key

• sessionEndedByAgentAbsentMessage which has been replaced by agentAbsentMessage but used in a different way

From 23.12 to 24B

B2C Upload File Types

Prior CX version 23A+ you will have to configure WCFS to use the old default file types:

fileUploadSettings: {
    supportedFileTypes: 'bmp doc docx gif jpeg jpg pdf png txt xls xlsx'
}

See File Types Restriction for more details.

Custom icons

Default values have been introduced for the following icons, to disable them just clear them as follows:

icons: {
    avatarBot: '',
    avatarUser: '',
    informationMessage: '',
    warningMessage: '',
    errorMessage: '',
    downloadMessage: '' // New icon in 24B
}

See Custom Icons for more details.

New custom text keys

• agentAttachmentDownloading
• agentAttachmentDownloadFailed

Changed custom text keys

• agentAttachmentDownloading has substitution strings for the file name and the file size.

From 24B to 24C

New custom text keys

• pacDialogTitleHtml
• pacDialogTextHtml
• pacNoButtonLabel
• pacYesButtonLabel
• sessionEndedByQueueTimeoutMessage
• endConversationAndClose
• bot
• sensitiveInformationMaskingMessage
• sensitiveInformationOffTheRecordMessage
• sensitiveInformationRemovedMessage
• plfFooterHtml
• plfHeaderHtml

Changed custom text keys

• sensitiveInformationMessage

New custom icon keys

• sensitiveInformationMessage
• offTheRecordOffMessage
• offTheRecordOnMessage

Changed default settings

• name from oda-chat to wcfs
• disconnectEvent from unload to beforeunload

Changed isNewSession method

The isNewSession method has a new optional parameter, for more details see Persistence.

Note that the session object in the browser's session storage has also changed.

Changed offTheRecordPatterns setting values

• From CREDIT_CARD to creditCard
• From SOCIAL_SECURITY_NUMBER to socialSecurity

From 24C to 24D

New custom text keys

• cclLinkAriaLabel
• cclLinkText

B2C Survey Integration

The previous hardcoded substitution of {ENGAGEMENT_ID} has been removed and now requires using the new urlParameters key. See B2C Survey Integration and URL Customization for more details.