Design

Introduction

If you'd like to apply additional customizations, such as setting the global primary color, font-family, or colors of individual UI elements, you can use helpshiftConfig at the time of initialization.

Customizing the Web Chat UI via the helpshiftConfig object will override the Helpshift Dashboard configuration.

Customize the UI via Embed Code

You can use the embed code configuration to customize the UI. This is helpful for when you want the Web Chat widget to completely match the look and feel of your website.

Identify a Set

Identify a Set (a Set is a collection of UI elements) you'd like to customize. You don't have to configure all the Sets - you can decide which Sets to configure.

You can use the Global Primary Color and Global Font-family Keys to configure multiple UI elements across Sets.

Identify Keys

Identify Keys (each Set is comprised of Keys that configure certain UI elements in the Set) you'd like to configure. You don't have to configure all the Keys for a given Set - you can decide which Keys to configure.

Implement

Implement the UI customizations in the embed code configuration.

Use the Helpshift updateUiConfig API to update configuration.

Sets

Helpshift Web Chat provides 6 Sets of UI elements.

Set Configurable UI Elements
Widget Frame Set Widget header, launcher and unread message notification badge
Chat Widget Set Main chat widget
User Bubble Set Messages sent by the end user
Support Bubble Set Messages sent by the Agent or bots
Form Set UI elements where users provide input (text, uploading attachments, buttons and more)
CSAT Set CSAT survey

Keys

Global Keys

Global Keys apply to multiple UI elements across Sets.

Name Key to be used in Code Used to Configure
Global primary color global.color Widget header color, launcher color and much more using a single key. Use this when you have a single color that you'd like to use to customize the Web Chat Appearance to match your brand.
Global font-family global.fontFamily Font-family of all the text that appears on Web Chat (which includes text appearing in all the Sets mentioned above).

Keys available in Sets

In addition to the Global Keys, one or more of the following Keys are available per Set, which can be used to configure UI elements within a Set.

Name Key to be used in Code Used to Configure
Primary background color primaryBgColor The background color of primary UI elements in the Set.
Secondary background color secondaryBgColor The background color of secondary UI elements in the Set.
Primary text color primaryTextColor The color of primary text in the Set.
Secondary text color secondaryTextColor The color of secondary text in the Set.
Accent color accentColor The color of elements that should distinctly stand out in the Set.
Border color borderColor The color of borders in the Set.
Error color errorColor The color of errors shown in the Set.

When you configure Keys for a given Set, Helpshift automatically applies the values to relevant UI elements in the Set. This ensures that you are able to completely customize the appearance of Web Chat to match your brand, with minimal effort! Additionally, as we roll out new UI elements, we'll make informed design choices to ensure the Web Chat Appearance always complies with your brand's look and feel, with minimal investment from your end.

Keys available in a Set take priority over Global Keys. If you've configured a Key for a given Set, the UI elements in that Set will use values from the Key in that Set instead of using values from the Global Key.

Implementation Details

The UI customization configuration must be added to the helpshiftConfig object, as explained below.

Example Embed Code

// This example code sets the global color and the primary background
// color and the primary text color of the widget frame set. Other
// sets and keys can be set in a similar way.
var PLATFORM_ID = "foo",
    DOMAIN = "bar";

window.helpshiftConfig = {
  platformId: PLATFORM_ID,
  domain: DOMAIN,
  uiConfig: {
    global: {
      color: "#444"
    },
    widgetFrame: {
      primaryBgColor: "#2973c7",
      primaryTextColor: "#ffe"
    }
  }
};

Global Primary Color

The global primary color is a single color used to set the look and feel of Web Chat. Even if you'd like to use multiple colors, you can use the Primary Color as a handy way to configure multiple Sets simultaneously and configure individual Sets separately. The primary color will apply to the following UI elements if they are not configured using a Key from their respective Set.

Set
UI Element(s)
Notes
Widget Frame Set Widget header background, Launcher background If the 'Primary background color' is specified for the Widget Frame Set, it will override the 'Global primary Color'.
Chat Widget Set Links in FAQ answer If the 'Accent color' is specified for the Chat Widget Set, it will override the 'Global primary Color'.
User Bubble Set Attachment icon, Attachment name If the 'Accent color' is specified for the User Bubble Set, it will override the 'Global primary Color'.
Support Bubble Set Links If the 'Accent color' is specified for the Support Bubble Set, it will override the 'Global primary Color'.
Form Set Input box border (active state), Button background and outline, Send message input area border color (active state), Icons in send message input area (active state), Answer Bot links and Agent attachment icon and links If the 'Accent color' is specified for the Form Set, it will override the 'Global primary Color'.

The Global primary color can also be configured from within the Helpshift Dashboard. Using code to configure the global primary color will override the value set in the Helpshift Dashboard.

Example Code

// This example code sets the global color
window.helpshiftConfig = { 
  uiConfig: {
    global: {
      color: "#444"
    }
  }
};

Global Font-Family

The global font-family applies to all text appearing in the Web Chat widget, which includes the text appearing in all of the Sets mentioned above.

The global font-family supports only system fonts. A system font is a font that's available in a user's system (computer) by default, i.e. the font doesn't need to be installed or downloaded by an external Agent.

You can find more information about the font-family here.

Example Code

// This example code sets the global color
window.helpshiftConfig = { 
  uiConfig: {
    global: {
      fontFamily: "Lucida Grande, sans-serif"
    }
  }
};

Widget Frame Set (for the widget header and launcher)

Summary

Name Key to be used in Code Used to Configure
Primary background color widgetFrame.primaryBgColor The background color of primary UI elements, such as the widget header and launcher.
Primary text color widgetFrame.primaryTextColor The color of primary UI elements, such as the widget header text and launcher icon.
Secondary background color widgetFrame.secondaryBgColor The background color of secondary UI elements, such as the notification badge.
Secondary text color widgetFrame.secondaryTextColor The text color of secondary UI elements, such as the notification count.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color Global Primary Color Widget header background color
Launcher background color
Primary text color White (#fff) Widget header text color
Launcher icon color
Secondary background color Dark red (#e65050) Notification background color
Secondary text color White (#fff) Notification count color

Chat Widget Set

Summary

Name Key to be used in Code Used to Configure
Primary background color chatWidget.primaryBgColor The background color of the main Web Chat widget.
Primary text color chatWidget.primaryTextColor The color of form labels, FAQ questions, the CSAT question, and the CSAT confirmation.
Secondary text color chatWidget.secondaryTextColor The color of FAQ answers, Agent nicknames, timestamps, and text shown during out of business hours.
Accent color chatWidget.accentColor The color of links in FAQ answer.
Error color chatWidget.errorColor The color of errors that appear on the Web Chat widget.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color Grey (light, #f8f9f9) Chat widget background color


FAQ screen background color


CSAT survey background color


Out of business hours screens background color
Primary text color Black (dark, #383f44) CSAT survey question


Form label


CSAT confirmation text


FAQ Question
Secondary text color Black (base, #576066) FAQ answer


Out of business hours screens text color


timestamp color (a light version)


'Powered by Helpshift' (a light version)


Agent nickname
Accent color Global Primary Color Links in FAQ answer
Error color Red (dark, #e65050) Error text and icon color below the form elements (input boxes and attachment)


Error text and icon color below the user bubbles

User Bubble Set

Summary

Name Key to be used in Code Used to Configure
Primary background color userBubble.primaryBgColor The background color of the user bubble
Border color userBubble.borderColor The border color of the user bubble.
Primary text color userBubble.primaryTextColor The color of text in the user bubble.
Accent color userBubble.accentColor The color of the attachment icon and the attachment name in the user bubble.
Error color userBubble.errorColor The color of the user bubble border in an error state.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color White (#fff) User message bubble background color
Border color Grey (light, #e8e9eB) User message bubble border color
Primary text color Black (base, #576066) User message bubble text color
Accent color Global Primary Color User message bubble attachment icon and attachment name color
Error color Red (dark, #e65050) Border error color for user bubbles

Support Bubble Set

Summary

Name Key to be used in Code Used to Configure
Primary background color supportBubble.primaryBgColor The background color of the bubble when a message is sent by an Agent, bots, and for the typing indicator.
Border color supportBubble.borderColor The border color of the bubble when a message is sent by an Agent, bots, and for the typing indicator.
Primary text color supportBubble.primaryTextColor The color of the text in the bubble when a message is sent by an Agent, bots, and for the typing indicator.
Accent color supportBubble.accentColor The color of links in the support message bubble.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color Grey (light, #e8e9eB) Support message bubble background color


Typing indicator bubble background color


Answer bot bubble background color


Agent attachment bubble background color
Border color No border Support message bubble border color


Typing indicator bubble border color


Answer bot bubble border color


Agent attachment bubble border color
Primary text color Black (base, #576066) Support message bubble text color


Typing indicator dots color


Answer bot bubble text color


Agent attachment bubble text color
Accent color Global Primary Color Color of links in support message bubble

Form Set

Summary

Name Key to be used in Code Used to Configure
Primary background color form.primaryBgColor The background colors of -
Input boxes
Add attachment section
CSAT feedback box, Answer bot, and out of business hours screen bottom bar
Send message input area
Answer bot
Agent attachments and button text color
Border color form.borderColor The border colors of -
Input boxes (inactive state), add attachment section (inactive state), CSAT feedback box, Answer bot and out of business hours screen bottom bar
Send message input area (inactive state)
Primary text color form.primaryTextColor The colors of text in -
Input boxes (placeholder text, provided by end user)
Add attachment section (placeholder text, attachment name, attachment icon, close icon)
Send message input area (labels, placeholder text, provided by end-user)
Inactive state of send icon in the send message input area
Accent color form.accentColor The colors of -
Input box border (active state)
Button background / outline
Send message input area border color (active state)
Icons in send message input area (active state)
Answer bot links
Agent attachment icon / links
Error color form.errorColor The color of errors appearing within form elements and the border color from within an error state.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color White (#fff) Input boxes background color


Add Attachment background color


Send message input area background color


Scripted reply / Answer bot 'Yes / No' button bottom bar background color


CSAT survey screen bottom bar background color
Out of business hours bottom bar background color


CSAT survey feedback box background color


Answer bot background color


Agent attachments background color


Button text color
Border color Grey (base, #d4d7d9) Input boxes border color (inactive state)


Add Attachment border color


Attachment added border color


Send message input area border (inactive state)


Scripted reply / Answer bot 'Yes / No' button bottom section container border color


CSAT survey screen bottom bar border color
Out of business hours bottom bar border color


CSAT survey feedback box border color
Primary text color Black (base, #576066) Text color in Input boxes



Attachment section -
The attachment file name color is the same as the primary text color
The placeholder text color, attachment icon color, file size color and the 'x' icon color are based on opacity variants of the primary text color



Text and icon color in Send message input area
The label color for the Get info bot and the Input text color are the same as the primary text color
The placeholder color and inactive state of send icon are opacity variants of the primary text color

Accent color Global Primary Color Input boxes border (active state)



Send message input area border (active state)


Send icon color active state in send message input area


Attachment icon color in send message input area


Yes/No button outline and text


Submit button background color


Answer bot link color


Agent attachments icon and file name color
Error color Red (dark, #e65050) Error text and icon color in send message input area


Input box border color in error state
Error icon color in input boxes


Add attachment section border color in error state

CSAT Set

Summary

Name Key to be used in Code Used to Configure
Primary background color csat.primaryBgColor The background color of CSAT stars when they are not selected.
Accent color csat.accentColor The background color of CSAT stars when they are selected.

Details

Name Default (if not configured) Configurable UI Elements
Primary background color Black (x-light, #b6c3cc) CSAT stars (unselected state)
Accent color Yellow (dark, #f2b230) CSAT stars (selected state)

A Complete Example

Here's a code example that sets values to all the Keys of all the Sets. Setting all the values is optional. You may set the values for one or more Keys of one or more Sets.

// The basic embed code should be copied from the Admin Dashboard.
// In this code example, we have added the `uiConfig` property to
// the global helpshiftConfig object. Everything else is same as
// what you get with the embed code.
<script>
  (function () {
    var PLATFORM_ID = "foo",
    DOMAIN = "bar";

    window.helpshiftConfig = {
      platformId: PLATFORM_ID,
      domain: DOMAIN,
      // Start – UI customization
      uiConfig: {
        global: {
          color: "#2973c7",
          fontFamily: "Lucida Grande"
        },
        widgetFrame: {
          primaryBgColor: "#2973c7",
          primaryTextColor: "#fcfcfc",
          secondaryBgColor: "#666666",
          secondaryTextColor: "#fcfcfc"
        },
        chatWidget: {
          primaryBgColor: "#ffffff",
          primaryTextColor: "#333333",
          secondaryTextColor: "#666666",
          accentColor: "#2973c7",
          errorColor: "#ff0091"
        },
        userBubble: {
          primaryBgColor: "#d2d2d2",
          borderColor: "#d1d1d1",
          primaryTextColor: "#7d7d7d",
          accentColor: "#2973c7",
          errorColor: "#ff0091"
        },
        supportBubble: {
          primaryBgColor: "#666666",
          borderColor: "#777777",
          primaryTextColor: "#fcfcfc",
          accentColor: "#bbb111"
        },
        form: {
          primaryBgColor: "#fcfcfc",
          borderColor: "#d1d1d1",
          primaryTextColor: "#7d7d7d",
          accentColor: "#7d7d7d",
          errorColor: "#ff0091"
        },
        csat: {
          primaryBgColor: "#d2d2d2",
          accentColor: "#666666"
        }
      }
      // End – UI customization
    };
  }) ();

  !function(t,e){if("function"!=typeof window.Helpshift){var n=function(){n.q.push(arguments)};n.q=[],window.Helpshift=n;var i,a=t.getElementsByTagName("script")[0];if(t.getElementById(e))return;i=t.createElement("script"),i.async=!0,i.id=e,i.src="https://webchat.helpshift.com/webChat.js";var o=function(){window.Helpshift("init")};window.attachEvent?i.attachEvent("onload",o):i.addEventListener("load",o,!1),a.parentNode.insertBefore(i,a)}else window.Helpshift("update")}(document,"hs-chat");
</script>

Update UI Configuration

When to use

Since the customizations are added in the embed code configuration, they get applied when the page with the customization reloads. If you'd like to update the configuration without a page reload, use the updateUiConfig API.

If you use an SPA and would like to Update Web Chat configuration, you should use the updateUiConfig API.

Example Code

// Call the updateUiConfig API to update the UI configuration.
// You may pass the entire set of Sets and Keys with this API.
Helpshift ("updateUiConfig", {
  global: {
    color: "#333333"
  },
  chatWidget: {
    accentColor: "#2973c7"
  }
});

Allowed Values

Colors

  • All colors values should be valid color hex code.
  • The UI would still work without applying the invalid value and would use the default value for it.
  • If an invalid value is used, you'll see an error in the browser's developer console referencing the Key with the invalid value.

Font-family

  • Only system fonts are supported. A system font is a font that's available in an end user's system/device by default, i.e. the font doesn't need to be installed/downloaded by an external agent. These are also known as web-safe fonts.
  • The UI would still work without applying the invalid value and would use the default font family.
  • If an invalid value is used, you'll see an error in the browser's developer console referencing the Key with the invalid value.

Other Notes

  • Setting an empty uiConfig in the helpshiftConfig object would set all the UI elements to use the default configuration values.

    window.helpshiftConfig: {
      uiConfig: {
      }
    }