Documentation

Configuration

Configuration

All config options and a description of what the options do are displayed below. Defaults are provided for all options which are not marked as 'REQUIRED':

{
  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' | 'gladly';
  callbacks: {
    onChatMinimizeClick: () => void;
    onChatLauncherClick: () => void;
    onChatEndClick: () => void;
    onChatProactiveButtonClick: (value: string) => void;
    analytics: (event) => void;
    newConversationStarted?: () => 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;
    onChatInitialisedError: () => 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;
    enableUnreadNotification: 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;
  }
},
PropertyRequiredDescription
bottrueThe bot name and avatar displayed alongside bot messages. The avatar should be provided as a base64 encoded image.
csattrueCSAT configuration. 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.
versionfalseAllows a specific version of the chat widget to be used. If not provided, the latest stable version is used.
localefalseAllows a specific language to be used for all static text in the widget. See the Lang section for details
crmPlatformnullOnly applies to CRM platforms that have SDKs (Sunco and Gorgias). If provided, the SDK script is injected into the customers page.
callbacksfalseProvides a way to hook into certain events that occur in the widget. See the Callbacks section for details.
crmAgentfalseThe agents name and avatar displayed alongside agent messages. 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".
prechatFormfalsePre chat form configuration. See the Pre Chat Form section below for details.
proactiveButtonsSettingsfalseProactive buttons configuration. 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.
widgetDimensionsfalseOptions to customise the dimensions of the widget dialog. See the Widget Dimensions section.
widgetPositionfalseOptions to customise the position of the widget launcher, dialog and proactive buttons. See the Widget Position section.
gen_aifalseOptions for Generative AI setup

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.

Chat session timeout

When the widget is initialised it makes a call to the Get Account endpoint to get the chat session timeout value set for the org. The widget checks if there is a chat session in progress when it is initialised. If there is a session in progress it checks the last message timestamp against the chat session timeout. If the session timeout is greater than the last message then the widget is reset. The chat_session_timeout property defaults to 24 hours for every org but this can be patched to be longer or shorter depending on the your preference.


What’s Next