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[]
    }
    iconActiveColors: {
      stars: string | string[]
      thumbs: string | string[]
      smiles: string | string[]
    }
  }
  customer: string // REQUIRED
  env: string // REQUIRED
  externalAccountKey: string // REQUIRED
  flowId: string // REQUIRED
  version: string // REQUIRED
  callbacks: {
    onChatMinimizeClick: () => void,
    onChatLauncherClick: () => void,
    onChatEndClick: () => void,
    onChatProactiveButtonClick: () => 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;
  }
  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
    maskCreditCardNumbers: boolean
    enableCrmUserAttachments: boolean
    enableNavigationTracking: boolean
  }
  lang: object
  metadata: object
  prechatForm: {
    isEnabled: boolean
  }
  proactiveButtonsSettings: {
    isEnabled: boolean
    questions: array
    answers: array
  }
  sessionStorageMechanism: {
    mechanism: string,
    domain: string,
  }
  styles: obect
  targetDOMNode: string
  theme: object
  widgetDimensions: object
  widgetPosition: object
}
PropertyRequiredDescription
bottrueDetails about the Bot. The name and avatar are displayed in the UI. The avatar should be provided as a base64 encoded image
csattrueDetails about csat. See the Csat section for details
customertrueName of customer. Must only contain alphanumeric characters
externalAccountKeytrueFlow External Account Id. See the Connect with Flow section for details
flowIdtrueThe id of the flow the widget should connect to
versiontrueChat widget version
callbacksfalseProvides several chat widget events callbacks
crmAgentfalseDetails about the crm agent. This should be populated if handover is enabled.
generalSettingsfalseGeneral settings for the widget. See the General Settings section for details
langfalseTranslations for all static text in the widget. See the lang section for details
metadatafalseEnables 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"
prechatFormfalseConfigure the pre chat form. See the Pre Chat Form section below for details.
proactiveButtonsSettingsfalseConfigure proactive buttons shown at the start of the chat. See the Proactive buttons section below for details
sessionStorageMechanismfalseSpecifies where the widget session id is stored. Defaults to localstorage. See the Session Storage section for details
stylesfalseEnables custom css to be injected in to the widget. See the Styles section for details
targetDOMNodefalseEnables user to specify a custom dom node which the widget will attach itself to (uses document.querySelector under the hood)
themefalseOptions to customise the appeance of the widget UI. See the Theme section below

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;
  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 are emojis, stars, thumbs, smiles.
  • emojis- An array of emojis that are displayed when type is set to emojis. 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 when type is set to emojis.
  • iconActiveColors- Colors to apply to icons when hovered, focused or selected. Follows the same rules as iconColors.
  • 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>
```
CallbackDescription
onChatLauncherClickCalled when the user clicks on the chat launcher
onChatEndClickCalled when the user ends the chat
onChatProactiveButtonClickCalled when the user clicks on a proactive button
analyticsCalled when Flow sends an Analytics event
onChatInitialisedCalled once the chat widget is initialised
onBotMessageCalled when the bot sends a message. The message text is sent as a parameter to the function
onMessageFeedbackButtonClickCalled when the user provides feedback to a bot message. Called with the feedback the user gave
iframeDimensionsCalled when the dimensions of the chat dialog iframe when the chat initialises. Called with an object containing width/height properties
onCarouselSelectionCalled when the user makes a selection in the carousel. See the Carousel section below for more details
onCarouselDisplayCalled when a carousel is displayed. See the carousel section below for more details
onCSATPopoverCloseClickedCalled when the carousel CSAT close button is clicked

General Settings

General settings control the display and configuration of various UI element of the widget:

PropertyDefaultDescription
delayBetweenBotMessages1000The synthetic delay added by the widget if the dg bot sends multiple messages in a row
enableInactiveTabNotificationstrueThis property enables a notification in page title about new messages when the page isn't focused for the user
hasDragAndDropAttachmenttrueEnables drag and drop functionality for file uploads
hasSendButtontrueWhether or not the send message button is enabled
headerIcon''Specifies the header icon for the chat dialog
initializationDelaynullHow long to delay the display of the widget UI (in milliseconds)
isAnimationDisabledfalseThis property will disable animations for chat widget
isChatCloseControlEnabledtrueWhether or not the dialog close control is enabled or not
isChatMinimizeControlEnabledtrueWhether or not the dialog minimize/expand controls are enabled or not
isDialogMaximisedfalseWhether or not to force the dialog to display maximised. This is used primarily for WISMO widgets
maskCreditCardNumberstrueRedact any credit card numbers or Iban numbers that an end user enters in to the widget before they are displayed/transmitted to any server
enableCrmUserAttachmentstrueEnables user attachment uploads when connected to an agent. Currently only applies to Sunco.
enableNavigationTrackingfalseWhen 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.

Language

Language can be customised using the following properties in the lang object. The defaults are shown below:

{
  sendingUserMessageText: 'Sending...',
  attachmentsMenuFile: 'Add File',
  attachmentsMenuPicture: 'Add Picture',
  attachmentsMenuLocation: 'Add Location',
  dragAndDropMessage: 'Drag and drop file here',
  header: '',
  chatInputPlaceholder: 'Type message here',
  prechatFormHeading: 'Chat',
  prechatButtonText: 'Start Chat',
  prechatFormSelectPlaceholderText: 'Select',
  prechatConfirmationMessage: 'Give us few minutes to find your order',
  messageLimitErrorText: 'Oops, that message is too long',
  endChatHeader: 'End Chat',
  endChatQuestion: 'Are you sure you want to end chat?',
  endChatConfirmButton: 'End chat',
  endChatCancelButton: 'Cancel',
  startNewChatButtonText: 'Start New Chat',
  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. ***',
  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 an 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',
  },
  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: 'Thank you for sharing your feedback',
    ratingsText: ['Terrible', 'Bad', 'Okay', 'Good', 'Excellent'],
    csatFeedbackButtonText: 'Submit',
    csatFeedbackTextareaPlaceholder: 'Add any additional comments here.',
  },
  internetConnectionLost: "Your internet connection appears to have been lost. Please check and try again.",
  internetConnectionRestored: "You're back online!",
};

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: [] // 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. i.e. text, number
  name: string // name of the field
  label: string // label for the field
  placeholder: string // placeholder text
  options: [{ name: string, label: string }] // field options
  required: boolean
  metadata: {
    systemField: string,
  }
};

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.

Currently text/email/number inputs are supported as well as select dropdowns. Here is an example prechat config:

 prechatForm: {
      isEnabled: true,
      fields: [
        {
          label: 'name',
          metadata: {
            systemField: 'name'
          },
          placeholder: 'Please enter your name',
          required: true,
          type: 'text'
        },
        {
          label: 'email',
          metadata: {
            systemField: 'email'
          },
          placeholder: 'Please enter your email address',
          required: true,
          type: 'email'
        },
        {
          label: 'type',
          placeholder: 'select...',
          required: true,
          type: 'select',
          options: [{ name: 'buy', label: 'buy'},{ name: 'sell', label: 'sell'}]
        }
      ]
    },

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.

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.
  • 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.

Example carousel with variants:

{
  "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",
      "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" }
  ] 
}

If the trackingId property is defined then when the slide is selected by the end user the widget will do two things:

  1. It will call the onCarouselSelection callback with the following arguments:
<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>
  1. 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.

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 - Text displayed in the form popup, when clicked, the form is closed and flow will resume.
  • 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"  
},

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: {
      '.dsqrkt': {
        color: '#222',
        backgroundColor: '#fff'
      },
    },
    fonts: [{
        fontFamily: 'Avenir Light',
        type: 'woff2',
        url: 'https://chat-assets.digitalgenius.com/avenir-light.woff',
        role: 'primary',
    }],
  }
  • widgetStyles allows for styling of widget elements
  • 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 default
  • icons 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 nameReplaces...
CloseClose icon
WindowMinimizeMinimize chat icon
ImageImage attachment icon
PlusExpand icon
PaperClipUpload attachment icon
AngleRightCarousel arrow next icon
AngleLeftCarousel arrow previous icon
SendSend message arrow icon
ArrowDownDropdown arrow icon
LauncherIcon displayed within the launcher button
LauncherMobileOptional icon displayed within the launcher button on mobile
OpenInNewTabOpen in new tab icon
LoaderLoading icon
FileCircleCheckDrag and Drop icon
StarOutlineStar icon (stars CSAT)
StarStar Filled icon (stars CSAT)
ThumbsUpThumbs up icon (thumbs CSAT)
ThumbsDownThumbs down icon (thumbs CSAT)
FaceYayYay face icon (smiles CSAT)
FaceHappyHappy face icon (smiles CSAT)
FaceMehMeh face icon (smiles CSAT)
FaceDisappointedDisappointed face icon (smiles CSAT)
FaceAngryAngry face icon (smiles CSAT)
DownloadDownload attachment icon
PreviewPreview attachment icon
FeedbackPositiveOptional icon for positive message feedback, falls back to ThumbsUp if not provided
FeedbackNegativeOptional 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: {
    brand: '#303030',
    primary: '#000',
    secondary: '#fff',
    error: '#e71d45',
    welcomeScreenBg: '#fff',
    positiveMessageFeedback: '#11a193',
    negativeMessageFeedback: '#ad020b',
  },
  breakpoints: {
    mobile: '800px'
  }
};

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

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 }
}
  • metadata - the widget will pass any object as defined by the metatdata config:
{
  "lang": "en",
  "someCustomThing": "some custom value"
}

Widget methods

When the widget is initalialised 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>

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();