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.
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 (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 (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 the UI customizations in the embed code configuration.
Use the Helpshift updateUiConfig
API to update configuration.
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 |
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). |
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.
The UI customization configuration must be added to the helpshiftConfig object, as explained below.
// 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" } } };
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), QuickSearch 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.
// This example code sets the global color window.helpshiftConfig = { uiConfig: { global: { color: "#444" } } };
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.
// This example code sets the global color window.helpshiftConfig = { uiConfig: { global: { fontFamily: "Lucida Grande, sans-serif" } } };
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. |
Name | Default (if not configured) | Configurable UI Elements |
---|---|---|
Primary background color | Global Primary Color | Widget header background colorLauncher background color![]() |
Primary text color | White (#fff) | Widget header text colorLauncher icon color![]() |
Secondary background color | Dark red (#e65050) | Notification background color![]() |
Secondary text color | White (#fff) | Notification count color![]() |
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. |
Name | Default (if not configured) | Configurable UI Elements |
---|---|---|
Primary background color | Grey (light, #f8f9f9) | Chat widget background color![]() ![]() ![]() ![]() ![]() |
Primary text color | Black (dark, #383f44) | CSAT survey question![]() ![]() ![]() ![]() |
Secondary text color | Black (base, #576066) | FAQ answer![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
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)![]() ![]() |
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. |
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![]() |
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. |
Name | Default (if not configured) | Configurable UI Elements |
---|---|---|
Primary background color | Grey (light, #e8e9eB) | Support message bubble background color![]() ![]() ![]() ![]() |
Border color | No border | Support message bubble border color![]() ![]() ![]() ![]() |
Primary text color | Black (base, #576066) | Support message bubble text color![]() ![]() ![]() ![]() |
Accent color | Global Primary Color | Color of links in support message bubble![]() |
Name | Key to be used in Code | Used to Configure |
---|---|---|
Primary background color | form.primaryBgColor |
The background colors of -Input boxesAdd attachment sectionCSAT feedback box, QuickSearch Bot, and out of business hours screen bottom barSend message input areaQuickSearch BotAgent 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, QuickSearch Bot and out of business hours screen bottom barSend 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 / outlineSend message input area border color (active state)Icons in send message input area (active state)QuickSearch Bot linksAgent attachment icon / links |
Error color | form.errorColor |
The color of errors appearing within form elements and the border color from within an error state. |
Name | Default (if not configured) | Configurable UI Elements |
---|---|---|
Primary background color | White (#fff) | Input boxes background color![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Border color | Grey (base, #d4d7d9) | Input boxes border color (inactive state)![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Primary text color | Black (base, #576066) | Text color in Input boxes![]() ![]() ![]() ![]() ![]() ![]() |
Accent color | Global Primary Color | Input boxes border (active state)![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
Error color | Red (dark, #e65050) | Error text and icon color in send message input area![]() ![]() ![]() ![]() |
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. |
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) |
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>
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.
// 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" } });
window.helpshiftConfig: { uiConfig: { } }