Configuration
Configuration
There are many configuration options available allowing you to configure many different aspects of a widget:
- Pre Chat form fields
- Proactive buttons
- CRM configuration
- Configuring the DG Bot name
- Configuring avatars of the DG Bot and CRM agent
- Control the display of various UI elements
- Control language
- Changing the widget theme
- Advanced styling using custom css
Config is stored on DigitalGenius servers and retrieved using the widgetId
property as defined on the window.DG_CHAT_WIDGET_CONFIG
object (see the Integrating Genius Chat Widget section for details). It is possible to override any of the config coming from the server by defining config on the window.DG_CHAT_WIDGET_CONFIG
object. For example if I define the following config:
window.DG_CHAT_WIDGET_CONFIG: {
env: 'eu',
widgetId: '22df40c4-110f-4b6f-aa2b-aeaffd6d1179',
generalSettings: {
isAnimationDisabled: true
}
}
then the isAnimationDisabled
property will override any value that has been set for that property in the server config.
A full list of all available config options is listed below:
{
bot: {
avatar: string; // REQUIRED
name: string; // REQUIRED
}
csat: { // REQUIRED
isEnabled: boolean; // REQUIRED
type: string;
emojis: string[];
iconColors: {
stars: string | string[];
thumbs: string | string[];
smiles: string | string[];
thermometer: string[];
}
iconActiveColors: {
stars: string | string[];
thumbs: string | string[];
smiles: string | string[];
thermometer: string[];
}
}
customer: string; // REQUIRED
env: string; // REQUIRED
externalAccountKey: string; // REQUIRED
flowId: string; // REQUIRED
version: string;
locale: string;
crmSDKPlatform: 'sunco' | 'gorgias';
callbacks: {
onChatMinimizeClick: () => void;
onChatLauncherClick: () => void;
onChatEndClick: () => void;
onChatProactiveButtonClick: (value: string) => void;
analytics: (event) => void;
onChatInitialised: () => void;
onBotMessage: (messageObj) => void;
onMessageFeedbackButtonClick: (feedback: { id: string, score: 0 | 1 | null}) => void;
iframeDimensions: (dimensionsObj) => void,
onCarouselSelection: (trackingId, slideData, carouselType, carouselPayload) => void;
onCarouselDisplay: (carouselPayload) => void;
onCSATPopoverCloseClicked: () => void;
onChatConversationStarted: (sessionId) => void;
onCSATPopoverSubmitClicked: () => void;
}
crmAgent: {
avatar: string;
name: string;
}
generalSettings: {
delayBetweenBotMessages: number;
messageAnimationDuration: number;
enableInactiveTabNotifications: boolean;
hasDragAndDropAttachment: boolean;
hasSendButton: boolean;
headerIcon: string;
initializationDelay: number;
isAnimationDisabled: boolean;
isChatCloseControlEnabled: boolean;
isChatMinimizeControlEnabled: boolean;
isDialogMaximised: boolean;
isChatLauncherEnabled: boolean;
maskCreditCardNumbers: boolean;
enableCrmUserAttachments: boolean;
enableNavigationTracking: boolean;
showDownloadAttachmentsButton: boolean;
enableDGPoweredByLink: boolean;
persistSession: boolean;
}
lang: object;
metadata: object;
prechatForm: {
isEnabled: boolean;
welcomeMessage: string;
suffixMessage: string;
fields: PrechatFormField[]
}
proactiveButtonsSettings: {
isEnabled: boolean;
questions: array;
answers: array;
}
sessionStorageMechanism: {
mechanism: string;
domain: string;
}
styles: object;
targetDOMNode: string;
theme: object;
widgetDimensions: object;
widgetPosition: object;
gen_ai: {
summarize_handover_transcript: boolean;
}
}
Property | Required | Description |
---|---|---|
bot | true | The bot name and avatar displayed alongside bot messages. The avatar should be provided as a base64 encoded image. |
csat | true | CSAT configuration. See the CSAT section for details. |
customer | true | Name of customer. Must only contain alphanumeric characters. |
externalAccountKey | true | Flow External Account ID. See the Connect with Flow section for details. |
flowId | true | The ID of the flow the widget should connect to. |
version | false | Allows a specific version of the chat widget to be used. If not provided, the latest stable version is used. |
locale | false | Allows a specific language to be used for all static text in the widget. See the Lang section for details |
crmPlatform | null | Only applies to CRM platforms that have SDKs (Sunco and Gorgias). If provided, the SDK script is injected into the customers page. |
callbacks | false | Provides a way to hook into certain events that occur in the widget. See the Callbacks section for details. |
crmAgent | false | The agents name and avatar displayed alongside agent messages. This should be populated if handover is enabled. |
generalSettings | false | General settings for the widget. See the General Settings section for details. |
lang | false | Translations for all static text in the widget. See the lang section for details. |
metadata | false | Enables widget to send custom data to flow. When the flow is executed, the metadata is sent to the flow as a flow input with an id of "metadata". |
prechatForm | false | Pre chat form configuration. See the Pre Chat Form section below for details. |
proactiveButtonsSettings | false | Proactive buttons configuration. See the Proactive buttons section below for details. |
sessionStorageMechanism | false | Specifies where the widget session id is stored. Defaults to localstorage. See the Session Storage section for details |
styles | false | Enables custom css to be injected in to the widget. See the Styles section for details |
targetDOMNode | false | Enables user to specify a custom dom node which the widget will attach itself to (uses document.querySelector under the hood) |
theme | false | Options to customise the appeance of the widget UI. See the Theme section. |
widgetDimensions | false | Options to customise the dimensions of the widget dialog. See the Widget Dimensions section. |
widgetPosition | false | Options to customise the position of the widget launcher, dialog and proactive buttons. See the Widget Position section. |
CSAT
Configure csat functionality for the widget. Csat will only be requested once during a chat widget session. If the user provides feedback when flow requests it or if an agent leaves the chat then the widget will not request csat when the end user ends the chat:
```typescript
csat: {
isEnabled: boolean;
type: string;
commentsCharacterLimit: number;
emojis: string[];
iconColors: {
stars: string | string[];
thumbs: string | string[];
smiles: string | string[];
}
iconActiveColors: {
stars: string | string[];
thumbs: string | string[];
smiles: string | string[];
}
}
```
isEnabled
- Whether or not csat is enabled for the widget.type
- The type of csat ui to display. Allowed types areemojis
,stars
,thumbs
,smiles
.commentsCharacterLimit
- Limits the number of characters allowed in the CSAT comments input. Defaults to 320.emojis
- An array of emojis that are displayed whentype
is set toemojis
. Default: ['π‘', 'π', 'πΆ', 'π', 'π€©'].iconColors
- Colors to apply to icons, if a string is provided, the color will apply to all icons. If an array is provided, the first colour in the array will apply to the first icon and so forth. Does not apply whentype
is set toemojis
.iconActiveColors
- Colors to apply to icons when hovered, focused or selected. Follows the same rules asiconColors
.flowId
- The flow to execute when csat is provided.
Callbacks
Callbacks enable a you to register listeners which get called when various events occur in the chat widget. Any callbacks must be defined in the config that exists in the your page because it is not possible to store functions in the server side config:
```javascript
<script>
window.DG_CHAT_WIDGET_CONFIG = {
widgetId: 'WIDGET_ID',
env: 'dev.us|eu|us',
callbacks: {
onChatMinimizeClick: () => {
console.log('user minimized chat');
}
}
}
</script>
```
Callback | Description |
---|---|
onChatMinimizeClick | Called when the user clicks on the chat minimize button |
onChatLauncherClick | Called when the user clicks on the chat launcher |
onChatEndClick | Called when the user ends the chat |
onChatProactiveButtonClick | Called when the user clicks on a proactive button |
analytics | Called when Flow sends an Analytics event |
onChatInitialised | Called once the chat dialog is displayed |
onBotMessage | Called when the bot sends a message. The message text is sent as a parameter to the function |
onMessageFeedbackButtonClick | Called when the user provides feedback to a bot message. Called with the feedback the user gave |
iframeDimensions | Called when the dimensions of the chat dialog iframe when the chat initialises. Called with an object containing width/height properties |
onCarouselSelection | Called when the user makes a selection in the carousel. See the Carousel section below for more details |
onCarouselDisplay | Called when a carousel is displayed. See the carousel section below for more details |
onCSATPopoverCloseClicked | Called when the CSAT close button is clicked |
onChatConversationStarted | Called when the conversation is started. The session id of the chat is passed to the callback |
onCSATPopoverSubmitClicked | Called when the user clicks on the submit button in the csat feedback popover |
onWidgetEmbedded | Called when the widget is embedded and the launchWidget method is available |
General Settings
General settings control the display and configuration of various UI element of the widget:
Property | Default | Description |
---|---|---|
delayBetweenBotMessages | 1000 | The synthetic delay added by the widget if the dg bot sends multiple messages in a row |
messageAnimationDuration | 300 | The duration of the animation on messages entering the widget |
enableInactiveTabNotifications | true | This property enables a notification in page title about new messages when the page isn't focused for the user |
hasDragAndDropAttachment | true | Enables drag and drop functionality for file uploads |
hasSendButton | true | Whether or not the send message button is enabled |
headerIcon | '' | Specifies the header icon for the chat dialog |
initializationDelay | null | How long to delay the display of the widget UI (in milliseconds) |
isAnimationDisabled | false | Disabled widget mount/unmount animations |
isChatCloseControlEnabled | true | Whether or not the dialog close control is enabled or not |
isChatMinimizeControlEnabled | true | Whether or not the dialog minimize/expand controls are enabled or not |
isDialogMaximised | false | Whether the widget should be maximised on page load |
isChatLauncherEnabled | true | Whether the chat launcher is enabled. If set to false, the widget must be manually launched. |
maskCreditCardNumbers | true | Redact any credit card numbers or Iban numbers that an end user enters in to the widget before they are displayed/transmitted to any server |
showDownloadAttachmentsButton | true | Whether or not to show the download button for attachments |
enableCrmUserAttachments | true | Enables the user to upload attachments at any point after handing over to an agent. Only applies to Sunco and Gorgias. |
enableNavigationTracking | true | When enabled, a system event will be added to the conversation page whenever the user navigates to a new page. This may not work out of the box for some single page applications - see documentation for the trackNavigation method if this is the case. |
enableDGPoweredByLink | true | Whether 'Powered by DigitalGenius' is linked to the DG website. |
persistSession | true | Whether the session should be persisted between page reloads / multiple tabs. Disabling this is useful for WISMO widgets. |
isEmbeddedMode | false | When true, the widget is maximised by default. When the user closes the chat, the conversation is ended but the widget remains open and the pre chat form is displayed. |
maxUserMessageLength | 250 | The maximum number of characters a user can send in a message. |
Language
The widget has support for localisation via the locale
config. You can provide a locale string, for example, en-GB
, where the first two lowercase letters define the languages code (ISO 639-1 format) and the second two capitalized letters define the country code (ISO 3166-1 alpha-2 standard). This enables the widget to provide different translations for the same language across different regions.
The frontend team manage the default translation files. If you want another locale to be added please request this in the #talk-to-frontend
channel. You will need to provide translations for all the properties in the object below.
If no locale is provided in the config the widget will default to using en-GB
.
Currently supported locales are:
- en-GB // British English
- en-US // American English
- nl-NL // Dutch
- de-DE // German
- es-ES // Spanish
- fr-FR // French
- js-JP // Japanese
{
sendingUserMessageText: 'Sending...',
dragAndDropMessage: 'Drag and drop file here',
header: '',
chatInputPlaceholder: 'Type message here',
prechatButtonText: 'Start Chat',
prechatFormSelectPlaceholderText: 'Select',
messageLimitErrorText: 'Oops, that message is too long',
endChatHeader: 'End Chat',
endChatQuestion: 'Are you sure you want to end chat?',
endChatConfirmButton: 'End chat',
endChatCancelButton: 'Cancel',
carouselSelectionButtonText: 'Select',
idleTimeoutPrefixMessage: 'Are you still there? Please send a message within',
idleTimeoutSuffixMessage: 'or this chat will time out',
returnToMainMenu: 'Return to main menu',
messageFeedbackText: 'Was this helpful?',
userClosedChatMessageToAgent: '*** USER CLOSED CHAT. ***',
listPopupSubmitButtonText: 'Confirm',
agent: {
agentEndedChat: 'Agent left the chat',
agentDisconnected: 'The agent disconnected',
agentJoined: 'An agent joined the chat',
namedAgentEndedChat: 'left the chat',
namedAgentDisconnected: 'disconnected',
namedAgentJoined: 'joined the chat',
agentTransferredChat: 'You are being transferred to another agent',
queueMessageWithPosition: 'You are in a queue. Your position is',
queueMessage: 'You are in a queue.',
agentJoining: 'An agent is joining',
couldNotConnect: 'Could not connect to any agents',
connectingToAnAgent: 'Connecting you with an agent',
reconnectingToAnAgent: 'Attempting to reconnect to an agent',
couldNotUploadFile: 'There was a problem uploading your file. Please try again.',
disconnectedReconnecting: 'You were disconnected. Connecting you to another agent',
automatedAgentMessage: 'An agent will assist you shortly',
chatEndedDueToInactivity: 'Chat ended due to inactivity',
chatConnectionLost: 'Chat ended due to loss of connection',
},
flow: {
defaultErrorMessage: 'We were unable to handle your request. Please try again',
},
server: {
defaultErrorHeading: 'Oops! An error occurred!',
errorMessageLine1: 'Try restarting the chat below.', // supports markdown
errorMessageLine2: 'If the issue persists, please contact our support team.', // supports markdown
restartButtonText: 'Restart',
},
fileUploadErrors: {
virus: {
title: 'Oops!',
descr: 'This file may contain a virus or other malware and can\'t be uploaded. Try another file.',
},
tooLarge: {
title: 'Too Big!',
descr: 'Files that are more than 16MB cannot be uploaded. Try another file.',
},
generic: {
title: 'Oops!',
descr: 'There was a problem uploading this file. Try another file.',
},
},
newMessageNotifyText: 'New Message',
csatLang: {
ai: {
csatNotice: null,
csatTitle: 'Please rate this chat',
},
agent: {
csatNotice: 'Agent has ended the chat.',
csatTitle: 'Please rate this conversation',
},
customer: {
csatNotice: null,
csatTitle: 'Please rate this chat before you go',
},
csatFeedbackTitle: { // Pass a string if dynamic text is not required.
1: 'Thanks for your feedback, we\'re sorry we couldn\'t help here',
2: 'Thanks for your feedback, we\'re sorry we couldn\'t help here',
3: 'Thanks for your feedback!',
4: 'Thank you and have a lovely day!',
5: 'Thank you and have a lovely day!',
},
ratingsText: ['Terrible', 'Bad', 'Okay', 'Good', 'Excellent'],
csatFeedbackButtonText: 'Submit',
csatFeedbackTextareaPlaceholder: { // Pass a string if dynamic text is not required.
1: 'Please feel free to leave any additional comments or feedback to help us improve.',
2: 'Please feel free to leave any additional comments or feedback to help us improve.',
3: 'We appreciate your comments and suggestions.',
4: 'Please feel free to leave any additional comments or feedback about what we did well.',
5: 'Please feel free to leave any additional comments or feedback about what we did well.',
},
csatCommentsCancelButtonText: 'No Thanks',
},
internetConnectionLost: "Your internet connection appears to have been lost. Please check and try again.",
internetConnectionRestored: "You're back online!",
iframeTitles: {
proactive: 'DigitalGenius Chat Proactive App',
proactiveScript: 'DigitalGenius Chat Proactive Script',
launcher: 'DigitalGenius Chat Launcher App',
launcherScript: 'DigitalGenius Chat Launcher Script',
widget: 'DigitalGenius Chat App',
widgetScript: 'DigitalGenius Chat Script',
attachmentsPreview: 'DigitalGenius Attachments App',
},
accessibilityLabels: { // Not visible in the UI, but important for users using screen readers
launcher: 'Open chat widget',
minimiseWidget: 'Minimise chat widget',
closeWidget: 'Close chat widget',
alertMessage: 'Alert message with type',
inputSubmit: 'Submit',
downloadImage: 'Download image',
carousel: 'Product carousel',
carouselPrevious: 'Go to previous item',
carouselNext: 'Go to next item',
chatForm: 'Enter a message',
chatFormSubmit: 'Send message',
chatFormUpload: 'Upload a file',
CSATTextarea: 'Enter a comment',
close: 'Close',
previewImage: 'Open image preview',
messageFeedbackPositive: 'Mark message as helpful',
messageFeedbackNegative: 'Mark message as unhelpful',
messageFeedbackReset: 'Feedback provided. Select again to reset your feedback',
},
}
Pre Chat Form
The widget supports displaying a pre chat form. This can be configured like so:
prechatForm: {
isEnabled: boolean;
welcomeMessage: string;
suffixMessage: string;
fields: PrechatFormField[]; // Array of PrechatFormField
}
The welcomeMessage
property can be populated with a string containing HTML markup which will be rendered above the prechat form.
The suffixMessage
property can be populated with a string containing HTML markup which will be rendered below the prechat form.
IMPORTANT
If your widget does not have a prechat form but does handover to a helpdesk then it is necessary for you to obtain the end users name and email address via the chat before handing the user over to the helpdesk (i.e. before sending the Agent Handover chat activity). Once you have the users name/email those values must be updated on the conversation object before handover. A member of the Solution Engineer team will be able to advise how to do this.
PrechatFormField = {
type: string // Type of html element to output. text | email | select
name: string // Mame of the field
label: string, // Label for the field
placeholder: string // Optional placeholder text
options: [{ name: 'option1', label: 'Option 1' }] // Select input options (type must be 'select')
validation: {
required: {
value: boolean // Makes the field required
message: string // Error message when field is empty
},
pattern: {
value: string // Custom RegEx pattern to validate the field
message: string // Error message when value does not match the RegEx pattern
},
maxLength: {
value: number // Maximum characters allowed
message: string // Error message when value exceeds max length
}
},
metadata: {
systemField: string // See below
}
};
The metadata.systemField
property can be assigned a value of either name
or email
. This identifies these particular prechat fields as ones which should be used when passing user details to a helpdesk.
In order to validate email addresses, a pattern
is required, see the example below for a common email validation regex pattern.
Currently text, email, number and select inputs are supported. Here is an example prechat config:
prechatForm: {
isEnabled: true,
welcomeMessage: '<h2>Hi, I\'m the DG bot!</h2><p>How can I help?</p>'
suffixMessage: 'Just to let you know, by talking with us today, you are accepting our <a>Privacy Policy</a>.',
fields: [
{
type: 'text',
name: 'name',
label: 'Enter name',
placeholder: 'Please enter your name',
validation: {
required: { value: true, message: 'Name is required' },
maxLength: { value: 30, message: 'Name is too long' },
},
metadata: { systemField: 'name' },
},
{
type: 'email',
name: 'email',
label: 'Enter email',
placeholder: 'Please enter your email address',
validation: {
required: { value: true, message: 'Email is required' },
pattern: {
value: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$',
message: 'Please enter a valid email',
}
},
metadata: { systemField: 'email' },
},
{
type: 'select',
name: 'options',
label: 'Select an option',
placeholder: 'Select...',
options: [{ name: 'buy', label: 'Buy'},{ name: 'sell', label: 'Sell'}],
validation: {
required: { value: true, message: 'An option must be selected' },
}
}
]
}
Proactive buttons
The widget supports displaying proactive buttons at the start of the chat. These can be configured like so:
proactiveButtonsSettings: {
isEnabled: boolean,
questions: array,
answers: array,
},
}
questions
are displayed using the themes brand
colour and answers
are displayed using themes secondary
colour. If the prechat form is enabled, when clicking on the proactive button the flow won't be executed and the widget dialog will just be shown, displaying the prechat form. In this mode proactive buttons are intended to be used purely as a visual cue to encourage the user to interact with the widget.
Styles
The bot appearance can be further configured using the styles object. There are a number of different properties that can be specified in the styles object to affect the widget's display:
styles: {
icons: {
Close: '<Some svg code here>',
WindowMinimize: {
src: '<Some svg code here>',
size: 18
}
},
widgetStyles: {
'.dg-chat-header': {
color: '#222',
backgroundColor: '#fff'
},
},
fonts: [{
fontFamily: 'Avenir Roman',
type: 'woff2',
url: 'https://chat-assets.digitalgenius.com/avenir-roman.woff',
role: 'primary',
}],
}
widgetStyles
allows for styling of widget elements. All elements in the widget have human readable classnames and can be customised using the syntax above.fonts
allows a custom font to be specified. The role property allows the primary font to be stipulated. This font will be used by every element in the widget by defaulticons
allows for custom svg to be used for icons throughout the widget, overriding default icons. Either pass svg as a string or use an object type as shown above to specify custom size
Supported icons
The icons
object currently supports the following values, overriding the default icons used throughout the widget.
Value name | Replaces... |
---|---|
Close | Close icon |
WindowMinimize | Minimize chat icon |
Image | Image attachment icon |
Upload | Chat input upload icon |
PaperClip | Upload attachment icon |
AngleRight | Carousel arrow next icon |
AngleLeft | Carousel arrow previous icon |
Send | Send message arrow icon |
ArrowDown | Dropdown arrow icon |
Launcher | Icon displayed within the launcher button |
OpenInNewTab | Open in new tab icon |
Loader | Loading icon |
FileCircleCheck | Drag and Drop icon |
StarOutline | Star icon (stars CSAT) |
Star | Star Filled icon (stars CSAT) |
ThumbsUp | Thumbs up icon (thumbs CSAT) |
ThumbsDown | Thumbs down icon (thumbs CSAT) |
FaceYay | Yay face icon (smiles CSAT) |
FaceHappy | Happy face icon (smiles CSAT) |
FaceMeh | Meh face icon (smiles CSAT) |
FaceDisappointed | Disappointed face icon (smiles CSAT) |
FaceAngry | Angry face icon (smiles CSAT) |
Download | Download attachment icon |
Preview | Preview attachment icon |
FeedbackPositive | Optional icon for positive message feedback, falls back to ThumbsUp if not provided |
FeedbackNegative | Optional icon for negative message feedback, falls back to ThumbsDown if not provided |
Styling widget containers
The Widget also outputs id's on the elements in which the chat is injected in your page. This allows you to manipulate how the chat is placed in your webpage. The following classes allow these containers to be targeted:
#dg-chat-container
- the outer container for the chat application
#dg-chat-widget
- the container for the chat dialog
#dg-chat-widget-launcher
- the container for the chat launcher
#dg-chat-widget-proactive
- the container for the chat proactive buttons
In order to apply styles to these containers you need to include a stylesheet in their page which targets these selectors.
Widget Dimensions
The customer can specify the dimensions of the chat widget dialog by specifying the following config:
widgetDimensions: {
desktop: {
dialog: { width: '375px', height: '650px' },
},
mobile: {
dialog: { width: '100%', height: '100%' },
},
}
Widget position
The customer can specify the position of the chat widget launcher, dialog and proactive buttons for desktop and mobile devices by specifying the following config - any of top, right, bottom, left properties can be specified:
widgetPosition: {
desktop: {
launcher: { bottom: '10px', right: '10px' },
proactive: { bottom: '90px', right: '20px' },
dialog: { bottom: '20px', right: '20px' },
},
mobile: {
launcher: { bottom: '10px', right: '10px' },
proactive: { bottom: '90px', right: '20px' },
dialog: {
top: '0px', right: '0px', bottom: '0px', left: '0px',
},
},
},
Theme
Basic colours in the widget can be stipulated using the theme
object. A custom mobile breakpoint can also be defined, which determines when the widget is fullscreen and when the LauncherMobile
icon is displayed (if provided).
{
colors: { // Deprecated
brand: '#303030', // Deprecated
primary: '#000', // Deprecated
secondary: '#fff', // Deprecated
error: '#e71d45', // Deprecated
welcomeScreenBg: '#fff', // Deprecated
positiveMessageFeedback: '#11a193', // Deprecated
negativeMessageFeedback: '#ad020b', // Deprecated
},
general: {
brandColour: '#303030', // Launcher, widget header, buttons etc
brandHoverColour: '#383838', // Hover colour of brand buttons
brandSecondaryColour: '#fff', // Colour of text / icons in branded areas
chatBackgroundColour: '#fff', // Chat widget background colour
errorColour: '#e71d45', // Error text, error banner etc
},
chatInput: {
borderColour: '#858585', // Chat input border colour
borderHoverColour: '#000', // Chat input border hover colour
sendButtonIconColour: '#262626', // Send message icon colour
messageLimitTextColour: '#4d4d4d', // Character limit text colour
uploadButtonIconColour: '#7F7F7F', // Upload attachment icon colour
uploadButtonIconHoverColour: '#7F7F7F', // Upload attachment icon hover colour
},
messages: {
userBubbleColour: '#000', // User message bubble colour
userTextColour: '#fff', // User message text colour
botBubbleColour: '#e2e2e2', // Bot message bubble colour
botTextColour: '#000000d9', // Bot message text colour
},
quickReplies: {
borderColour: '#000', // Quick reply border colour
backgroundColour: '#fff', // Quick reply background colour
backgroundHoverColour: '#f5f5f5', // Quick reply background hover colour
backgroundActiveColour: '#eaeaea', // Quick reply active background colour
textColour: '#000028', // Quick reply text colour
textHoverColour: '#000028', // Quick reply text hover colour
},
carousel: {
slideBorderColour: '#e2e2e2', // Slide border colour
arrowsColour: '#000', // Navigation arrows icon colour
arrowsCircleColour: '#fff', // Carousel navigation arrows background colour
displayArrowsOnMobile: false, // Whether to show navigation arrows on mobile
descriptionTextColour: '#2c2c2c', // Description text colour
priceBorderColour: '#5b697d', // Price border colour
priceTextColour: '#29313d', // Price text colour
variantNameTextColour: '#5c5c5c', // Variant name text colour
},
messageFeedback: {
containerBackgroundColour: '#f0f0f0', // Container background colour
iconsColour: '#4d4d4d', // Icons colour when unselected
iconsHoverColour: '#191919', // Icons hover colour when unselected
iconsBackgroundHoverColour: '#e0e0e0', // Icons background hover colour when unselected
positiveFeedbackColour: '#11a193', // Positive feedback icon and border colour
negativeFeedbackColour: '#ad020b', // Negative feedback icon and border colour
},
listPopup: {
backgroundHoverColour: '#f9f9f9', // List item background hover colour
borderColour: '#eeeeee', // List item border colour
descriptionTextColour: '#6d6d6d', // Description text colour
},
avatar: {
textColour: '#fff', // Text colour of avatar text (when no image is provided)
backgroundColour: '#303030' // Avatar background colour (when no image is provided) - falls back to brand
},
typingIndicator: {
dotsColour: '#2a2a2a', // Base dots colour, the animation affects the opacity of this
},
endChatPopup: {
cancelButtonBackgroundColour: 'none', // Cancel button background colour
cancelButtonTextColour: '#000', // Cancel button text colour
},
prechatForm: {
variant: 'solid', // Alters the prechat form background style: solid | gradient | diagonal | horizontal
backgroundColour: '#303030', // (optional) Prechat form background colour - falls back to brandColour
welcomeMessageTextColour: '#fff', // Welcome message text colour
inputTextColour: '#2B2B2B', // Input text colour
inputBackgroundColour: '#F3F3F3', // Input background colour
suffixTextColour: '#2B2B2B', // Suffix text colour
iconsColour: '#fff' // Header icons colour
},
proactiveButtons: {
closeIconColour: '#000', // Close icon colour
shadowHoverColour: '#333333', // Button hover shadow colour
questionBubbleColour: '#303030', // Question bubble colour
questionTextColour: '#fff', // Question text colour
answerBubbleColour: '#fff', // Answer bubble colour
answerBorderColour: '#000', // Answer border colour
answerTextColour: '#000', // Answer text colour
},
breakpoints: {
mobile: '800px', // The point at which the widget becomes full screen
},
}
Overriding config
It is possible to override the config created on the server by defining properties on the window.DG_CHAT_WIDGET_CONFIG
object. For example: If the server config defines a prechatForm
block but there is also a prechatForm
block defined in window.DG_CHAT_WIDGET_CONFIG
then the latter will take precedence. Also some config options such as callbacks
and metadata
might not make sense to be included as part of the server config because they will often include dynamic values which only exist once the widget is being executed in the browser or snippets of JavaScript which are not valid JSON.
Flow Inputs
The widget executes the flow with the following inputs:
prechatFormValues
- if the chat is configured with a prechat form this object will contain all of the values submitted:
{ "name": "James", "orderNumber": "abc123"}
pageProperties
- the widget will send data about the page in which the widget is executing:
{
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/116.0.0.0 Safari/537.3",
"url": "https://some-website.com/orders",
"title": "Webpage title",
"screenResolution": { "width": 1920, "height": 1055 },
"locale": "en-GB"
}
metadata
- the widget will pass any object as defined by themetatdata
config:
{
"lang": "en",
"someCustomThing": "some custom value"
}
Widget methods
When the widget is initialised it adds a methods
object to the global dgchat
object. They can be accessed on the global object like so window.dgchat.methods.methodName()
This allows you to to programmatically perform actions on the widget. The following actions are supported by the methods
api:
SendMessage
The sendMessage
method allows the you to programmatically send a message on the user behalf:
<script>
const element = document.querySelector('.some element');
element.addEventListener("click", () => {
window.dgchat.methods.sendMessage('Some custom message');
}, false);
</script>
sendSystemMessage
The sendSystemMessage
method allows a system message to be programatically added to the conversation:
window.dgchat.methods.sendSystemMessage('Some system message');
A system message should only be added after a conversation has been initiated.
launchWidget
The launchWidget
method allows the you to programmatically launch the widget.
<script>
window.dgchat.methods.launchWidget();
</script>
initProactiveButtons
The initProactiveButtons
method allows the you to programmatically trigger the proactive buttons to display. The payload must be as follows:
<script>
window.dgchat.methods.initProactiveButtons({
questions: ['list', 'of', 'questions'],
answers: ['list', 'of', 'answers'],
});
</script>
debug
The debug
method enables raw websocket data to be logged to the console. This command can be run from the console directly:
window.dgchat.methods.debug();
Carousel
The widget provides a few ways to enable you to track which carousel an end user has been shown and what slide they have selected.
slideOrientation - Used to set the height of the image based on it's orientation e.g. for landscape images, use horizontal. Possible values are horizontal, vertical, square or none.
carouselType - (optional) An arbitrary property.
payload - An array of objects, each object represents a slide in the carousel:
- id - The unique id of the product.
- trackingId - (optional) Used for analytics purposes.
- image - An image of the product. This is not required if variants are provided.
- title - The title/name of the product, supports markdown.
- description - A short description of the product, supports markdown.
- price - (optional) Displays the product price in a 'pill' on top of the image. This is overriden by the selected variant price. Supports markdown.
- externalLink - (optional) Opens the provided link in a new tab when the product is selected.
- buttonText - (optional) The text displayed in the 'Buy' button.
- secondaryButton - (optional) An object containing properties for displaying a second button
text
- The text of the secondary buttoncallbackName
- The name of a custom callback defined incallbacks
, called when the secondary button is selected.externalLink
- (optional) Opens the provided link in a new tab when the product is selected.disabled
- (optional) Whether the secondary button is disabled.
- variants - When provided, each product/slide will display thumbnails for each variant. When a variant is selected, it's data takes precedence over top level data e.g. the variants externalLink, trackingId and price will be used when a product is selected.
The secondaryButton
provides a way to add custom functionality when the button is selected. A custom callback can be defined in callbacks
, when callbackName
matches the name of your custom callback, it is called with the slide data.
Example carousel:
{
"type": "carousel",
"slideOrientation": "horizontal",
"carouselType": "product-carousel",
"payload": [
{
"id": 1,
"trackingId": "apple",
"image": "https://picsum.photos/200/300",
"title": "Apple",
"description": "Apple slide",
"externalLink": "http://google.com",
"buttonText": "custom button text",
"price": "Β£10",
"secondaryButton": {
"text": "Add to cart",
"callbackName": "onAddToCart",
"disabled": false,
},
"variants": [
{ "id": 8, "name": "Red apple", "image": "", "price": "Β£1", "externalLink": "http://google.com", "trackingId": "a"},
{ "id": 9, "name": "Green apple", "image": "", "price": "Β£2", "externalLink": "http://google.com", "trackingId": "b" },
]
}
]
}
The widget provides a few ways to enable the customer to track which carousel an end user has been shown and what slide they have selected.
When the Carousel is displayed the widget will call the onCarouselDisplay callback:
<script>
window.DG_CHAT_WIDGET_CONFIG = {
widgetId: 'f0c07546-af4c-4963-9e23-3e9343eaf13b',
env: 'dev.us',
version: '2.1.0',
callbacks: {
onCarouselDisplay: (carouselPayload) => {
console.log(carouselPayload);
}
}
}
</script>
Optionally, if the Carousel payload includes a carouselType
property then the onCarouselDisplay
callback will be called with that property:
{
"type": "carousel",
"carouselType": "product-carousel",
"slideOrientation": "horizontal",
"payload": [
{ "id": 1, "image": "https://picsum.photos/200/300", "title": "Apple", "description": "Apple slide", "externalLink": "http://google.com", "buttonText": "custom button text", "trackingId": "apple" }
]
}
The carousel payload can also optionally include a trackingId
property for each slide:
{
"type": "carousel",
"slideOrientation": "horizontal",
"payload": [
{ "id": 1, "trackingId": "apple", "image": "https://picsum.photos/200/300", "title": "Apple", "description": "Apple slide", "externalLink": "http://google.com", "buttonText": "custom button text" }
]
}
When a slide is selected by the end user, up to 3 actions are performed:
- It will call the
onCarouselSelection
callback (if provided) with thetrackingId
,slideData
,carouselType
andcarouselPayload
. ThetrackingId
parameter will returnundefined
if not provided.
<script>
window.DG_CHAT_WIDGET_CONFIG = {
widgetId: 'f0c07546-af4c-4963-9e23-3e9343eaf13b',
env: 'dev.us',
version: '2.1.0',
callbacks: {
onCarouselSelection: (trackingId, slideData, carouselType, carouselPayload) => {
console.log(trackingId, slideData, carouselType, carouselPayload);
}
}
}
</script>
- The widget will also add an event to notify the flow server of the selected slide. In some cases the flow server will record this selection in Dashboard Analytics.
- Another event is added to return the users selection as a message displayed in the widget.
Forms
Forms should be utilised when information needs to be collected from the user. The below example is a simple form that asks the user for an order ID.
{
"type": "form",
"payload": {
"closeFormMessage": "Ask about something else",
"closeButtonEnabled": true,
"fields": [{
"name": "ordernumber",
"label": "Order Number",
"type": "text",
"placeholder": "r123456789",
"validation": {
"required": {
"value": true,
"message": "required"
},
"pattern": {
"value": "^r[0-9]{9}$",
"message": "Please provide a valid order number"
},
"maxLength": {
"value": 10,
"message": "The order number is too long"
}
}
}]
}
}
Do not pass "hideChatInput": true for forms, it results in the chat input being hidden after submitting a form and refreshing the page. The chat input is hidden automatically when a form is visible.
Properties
- closeFormMessage - When provided, displays text in the form popup which closes the form when clicked and resumes flow.
- closeButtonEnabled - When true, an 'X' icon is displayed in the form popup, which closes the form when clicked and resumes flow.
- fields - An array of fields to display in the form.
- name - The name of the field, used as the key of the property of the submitted form data.
- label - The field input label.
- type - The type of the input e.g. text | textarea | number.
- placeholder - The input placeholder text.
- validation - Enables validation constraints to be applied to the field. Ensure any validation has a useful message to inform the user why the input is invalid. See the Validation section below.
Validation
The widget aligns with the existing HTML standards for form validation. Fields can be validated using the following constraints:
Required:
A Boolean which, if true, indicates that the input must have a value before the form can be submitted.
"required": {
"value": true,
"message": "required"
},
MaxLength:
The maximum length of the value to accept for this input.
"maxLength": {
"value": 10,
"message": "The order number is too long"
},
minLength
The minimum length of the value to accept for this input.
"minLength": {
"value": 5,
"message": "The order number is too short"
},
max
The maximum numerical value to accept for this input.
"minLength": {
"max": 10,
"message": "This number is too big"
},
min
The minimum numerical value to accept for this input.
"minLength": {
"max": 1,
"message": "This number is too small"
},
pattern
Validate the field using a regular expression. The regex string must be a valid JSON string. Check that your regex is a valid JSON string by validating it using a JSON validator.
"pattern": {
"value": "^r[0-9]{9}$",
"message": "Please provide a valid order number"
},
Lists
Display a list of items in a popup, for example a list of reasons for return:
{
"type": "list",
"payload": {
"title": "Reason for return",
"description": "GIVENCHY Black Box Chain Minidress IT 38",
"closeButtonEnabled": true,
"closeMessage": "Ask something else",
"multiSelectEnabled": true,
"options": [
{
"id": "Does not fit properly",
"text": "Does not fit properly"
},
{
"id": "Order more than one size",
"text": "Order more than one size"
},
]
},
"prefixMessage": "Select an option"
}
Properties
payload
title
- (optional) The title of the list.description
- (optional) A description of list.closeButtonEnabled
- (optional) When true, an 'X' icon is displayed in the popup, which closes the popup when clicked and resumes flow.closeMessage
- (optional) If provided, displays text in the form popup, which closes the popup when clicked and resumes flow.multiSelectEnabled
- (optional) When true, multiple list items can be selected.options
- An array of options.id
- The unique id of the option.text
- The text/label of the list item.
When multiSelectEnabled
is true
, list items have an associated checkbox and a 'Confirm' button is displayed. When at least one item is selected, the Confirm button is enabled and will post an array of the selected options to flow when clicked.
The text of the 'Confirm' button can be updated via lang.listPopupSubmitButtonText
.
Generative AI Setup
"gen_ai": {
"summarize_handover_transcript": true
},
summarize_handover_transcript
instructs the Flow Engine to include an ai generated summary of the chat transcript which is sent to the helpdesk agent when we handover from DigitalGenius bot to the helpdesk.
Updated 8 days ago