Configuration

Below is a full overview of all configuration options available to the chat widget. Many properties are completely optional but provide a way to customise widgets as per customer preferences.

🚧
Server-side vs client side configuration
Please always apply any custom configuration in the server-side config where applicable. This can be done via the Widget Builder "advanced" tab. Doing so allows DigitalGenius to adjust the config if neccessary, rather than relying on customer devs to update the page/window config. Some properties however must be defined client side, such as widgetId, env and any callbacks;

type DgChatConfig = {
  widgetId: string;
  customer: string;
  env: string;
  version: string;
  name?: string;
  locale: string;
  maintenanceMode: {
    isEnabled: boolean;
    message: string;
  };
  easterEggs?: {
    prechatHasSnow?: boolean;
  };
  crmSDKPlatform?: 'sunco' | 'gorgias' | 'gladly' | 'microsoft' | 'zopim';
  bot: {
    name: string;
    avatar: string;
  };
  crmAgent?: {
    name: string;
    avatar: string;
    agentNameRegex?: string;
  };
  sessionStorageMechanism: {
    mechanism: 'localstorage' | 'cookie';
    domain?: string | null;
  };
  images?: {
    returnsPortalLoading?: string;
  };
  targetDOMNode?: string;
  prechatForm: {
    isEnabled: boolean;
    welcomeMessage?: string;
    suffixMessage?: string;
    brandLogo?: string;
    fields: PrechatFormField[];
  };
  csat: {
    isEnabled: boolean;
    customerInitiatedCSATEnabled: boolean;
    type: 'stars' | 'emojis' | 'smiles' | 'thumbs' | 'thermometer';
    emojis?: string[];
    commentsCharacterLimit?: number;
    iconColors: {
      smiles: string | string[];
      stars: string | string[];
      thumbs: string | string[];
      thermometer: string[];
      emojis: undefined;
    };
    iconActiveColors: {
      smiles: string | string[];
      stars: string | string[];
      thumbs: string | string[];
      thermometer: string[];
      emojis: undefined;
    };
  };
  nps?: {
    isEnabled: boolean;
  };
  proactiveButtonsSettings?: {
    isEnabled?: boolean;
    questions: string[];
    answers: string[];
  };
  generalSettings: {
    headerIcon: string;
    hasSendButton: boolean;
    hasDragAndDropAttachment: boolean;
    isDialogMaximised: boolean;
    isChatCloseControlEnabled: boolean;
    isChatMinimizeControlEnabled: boolean;
    maskCreditCardNumbers: boolean;
    isAnimationDisabled: boolean;
    enableInactiveTabNotifications: boolean;
    hasDGPoweredBy: boolean;
    enableDGPoweredByLink: boolean;
    delayBetweenBotMessages: number;
    enableCrmUserAttachments: boolean;
    enableNavigationTracking?: boolean;
    showDownloadAttachmentsButton: boolean;
    disableAnimations?: boolean;
    persistSession?: boolean;
    isEmbeddedMode?: boolean;
    maxUserMessageLength?: number;
    sendMessageOnEnterKey: boolean;
    messageAnimationDuration: number;
    isChatLauncherEnabled?: boolean;
    isWidgetDisabled?: boolean;
    csatCloseButtonDisabled?: boolean;
    enableUnreadNotification?: boolean;
    enableBackToBottomButton?: boolean;
    closeChatAfterAgentInitiatedCsat?: boolean;
    enableHeaderBlur?: boolean;
    externalLaunchElement?: string;
    launcherVariant?: 'chatBubbles' | 'smile' | 'star' | 'starSpin';
    openLinksInNewTab: boolean;
    enableAIThinkingIndicator?: boolean;
    enableTranscriptDownload?: boolean;
  };
  styles: {
    icons?: Record<string, string | { src: string; size: number }>;
    widgetStyles: Record<string, CSSProperties>;
    launcherStyles: Record<string, CSSProperties>;
    fonts: {
      fontFamily: string;
      type: string;
      url: string;
      role: string;
    }[];
  };
  lang: Record<string, string | Record<string, string>>;
  theme: Theme;
  metadata?: Record<string, unknown>;
  callbacks: {
    onChatMinimizeClick?: () => void;
    onChatLauncherClick?: () => void;
    onChatInitialisedError?: () => void;
    onChatEndClick?: () => void;
    onChatProactiveButtonClick?: (value: string) => void;
    onMessageFeedbackButtonClick: (feedback: { id: string, score: 0 | 1 | null }) => void;
    onChatInitialised?: () => void;
    iframeDimensions?: (dimension: {
      [key: string]: { height: number; width: number };
    }) => void;
    onCarouselDisplay?: (carouselPayload: CarouselContent) => void;
    onCSATPopoverCloseClicked?: () => void;
    onChatConversationStarted?: (sessionId: string) => void;
    onCSATPopoverSubmitClicked?: () => void;
    onWidgetEmbedded?: () => void;
    analytics?: (event: unknown) => void;
    newConversationStarted?: () => void;
    onBotMessage?: (messageObj: ChatWidgetMessage) => void;
    onCarouselSelection?: (
      trackingId: string | number | null,
      selectionData: CarouselSlide | CarouselSlide[],
      carouselType: string | null,
      carouselPayload: CarouselContent,
    ) => void;
  } & Record<string, (data: unknown) => void>;
  widgetDimensions: {
    desktop: {
      dialog: { width: string; height: string };
      launcher: { width: string; height: string };
    };
    mobile: {
      dialog: { width: string; height: string };
      launcher: { width: string; height: string };
    };
  };
  widgetPosition: {
    desktop: {
      launcher: {
        top?: string;
        right?: string;
        bottom?: string;
        left?: string;
      };
      proactive: {
        top?: string;
        right?: string;
        bottom?: string;
        left?: string;
      };
      dialog: { top?: string; right?: string; bottom?: string; left?: string };
    };
    mobile: {
      launcher: {
        top?: string;
        right?: string;
        bottom?: string;
        left?: string;
      };
      proactive: {
        top?: string;
        right?: string;
        bottom?: string;
        left?: string;
      };
      dialog: { top?: string; right?: string; bottom?: string; left?: string };
    };
  };
  urlToLocaleMap: Record<string, string>;
  gen_ai: {
    summarize_handover_transcript: boolean;
  }
};

Property	Required	Description
`version`	false	Allows a specific version of the chat widget to be used. If not provided, the latest stable version is used.
`flowId`	true	The ID of the flow the widget should connect to.
`widgetId`	true	Unique identifier for the chat widget instance.
`customer`	true	Name of the customer. Must contain only alphanumeric characters.
`env`	true	Environment the widget should connect to (`us` or `eu`).
`version`	false	Allows a specific version of the chat widget to be used. If not provided, the latest stable version is used.
`name`	true	Unique name of the widget.
`locale`	true	Locale used for all static text. Can be overridden via `urlToLocaleMap`.
`maintenanceMode`	true	Enables maintenance mode and displays a custom message when enabled.
`easterEggs`	false	Feature-flagged UI easter eggs (e.g. snow in pre-chat).
`crmSDKPlatform`	false	CRM SDK integration platform. Injects the relevant SDK when provided (`sunco`, `gorgias`, `gladly`, `microsoft`, `zopim`).
`bot`	true	Bot display configuration including `name` and `avatar`.
`crmAgent`	false	Agent display configuration for handover scenarios. Includes optional `agentNameRegex` for formatting agent names.
`sessionStorageMechanism`	true	Defines where the widget session ID is stored (`localstorage` or `cookie`).
`images`	false	Custom image assets used by the widget (e.g. loading states).
`targetDOMNode`	false	CSS selector for a custom DOM node the widget should attach to.
`prechatForm`	true	Pre-chat form configuration, including fields and welcome messaging.
`csat`	true	CSAT configuration. Defines rating type, colors, comments limits, and behavior.
`nps`	false	Enables Net Promoter Score functionality.
`proactiveButtonsSettings`	false	Configuration for proactive question/answer buttons.
`generalSettings`	true	Core widget behavior and UI settings (animations, controls, limits, indicators, etc.).
`styles`	true	Custom styling configuration including widget styles, launcher styles, icons, and fonts.
`lang`	true	Translation strings for all static widget copy.
`theme`	true	Theme configuration controlling the visual appearance of the widget.
`metadata`	false	Arbitrary key-value data sent to the flow as input with ID `metadata`.
`callbacks`	true	Event hooks for widget lifecycle, user actions, analytics, and message handling.
`widgetDimensions`	true	Controls widget dialog and launcher dimensions for desktop and mobile.
`widgetPosition`	true	Controls launcher, dialog, and proactive button positioning for desktop and mobile.
`gen_ai`	false	Options for Generative AI setup
`urlToLocaleMap`	true	Maps URL patterns to locales for automatic locale detection.

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.

Updated 7 days ago

What’s Next

Message Types