Advanced customization of your Web Widget Follow

The Web Widget uses a Javascript API to control its appearance and performance. By modifying the API's methods, as well as the zESettings object, you can customize certain aspects of the content, placement, look, and feel of the widget.

This article discusses the the following topics and widget customizations:

For information about adding the Web Widget to your site, see Using Web Widget to embed customer service in your website.

About the Web Widget API

The Web Widget API consists of the following methods:

  • zE.setLocale
  • zE.identify
  • zE.hide
  • zE.show
  • zE.activate
  • zESetHelpCenterSuggestions

Most customizations, however, are handled in a separate widget API object, zESettings. You can modify multiple aspects of the Web Widget in this object.

The customizations described in this article are made by adding the code snippet examples to your web page or Help Center code, before the Web Widget script.

For more technically detailed information about working with the API, see the Web Widget API documentation on the Zendesk Developers website.

Displaying your widget in a different language

The widget is, by default, presented in the end user’s language, according to the language specified in the end-user’s Accept-Language (web) browser header. For example, if the end-user's browser language is set to ‘de’ for German, the widget will appear in German for that user.

The Web Widget includes a subset of the Zendesk supported languages, listed the Web Widget column in Language codes for supported languages. If the end-user's browser language is not supported by the Web Widget, the widget defaults to English. If for some reason the widget is unable to obtain the language from the end-user’s browser, the widget defaults to the language specified in Zendesk Support.

This customization uses the zE.setLocale method, and allows you to force your widget to always appear in a specific language, and override the end-user's browser language setting.

To force your widget to always appear in a specific language
  1. Add the following code after the widget script on your web page or your Help Center:
    <script>
      zE(function() {
        zE.setLocale('languagecode');
      });
    </script>

    Here's an example.

  2. Replace languagecode with the language code for the language you want the widget to appear in.

    You can find the language codes in the table in Language codes for supported languages. The Web Widget includes a subset of the Zendesk supported languages (as noted in the Web Widget column of the table).

    For example, if you want your widget to appear in German, you'd use the language code de.

    <script>
      zE(function() {
        zE.setLocale('de');
      });
    </script>

    When this setLocale code is in added, the widget will always appear in the specified locale regardless of the end-user's browser language.

Disabling ticket attachments

If you have enabled attachments for your tickets, users can attach files to tickets submitted via the Web Widget by default. However, you can disable this option using the zESettings object for ticket attachments.

Example:

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    contactForm: {
      attachments: false
    }
  }
};
</script>

Re-positioning the widget

The default position for the Web Widget is the bottom-right of the browser; when a user clicks on it, it opens by expanding upward.

You can select a location for the browser widget that varies from page to page - placing it on the left or right side of the page, or moving it to the top of the page where it expands downward when clicked. The widget can only be positioned in the top-left, top-right, bottom-left, or bottom-right of the web page.

Note: Position customization is only available on the Desktop version of Zendesk Support. It is not adjustable on the mobile version.

In the following example, the widget is moved to the top-left of the page:

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    position: {
      horizontal: 'left',
      vertical: 'top'     
    }
  }
};
</script>

Offsetting the widget placement

You can use the offset object to move your Web Widget on desktop systems both vertically and horizontally from the initial point of reference used by the position setting.

Note: Offset customization is only available on the Desktop version of Zendesk Support. It is not adjustable on the mobile version.

In the following example, the widget is offset 100px horizontal and 150px vertical from the initial position:

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    offset: { horizontal: '100px', vertical: '150px' }
  }
};
</script>

Setting a theme color for different web pages or sites

You can use the theme color object to create different colors for the Web Widget.

Example: Changing the color (from blue in the Web Widget admin) to green.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    color: {
      theme: '#78a300'    
    }
  }
};
</script>

Changing visible ordering in the widget

You can use the zIndex setting to set a new value and change how the Web Widget appears in comparison to other elements appearing in the same location on your site.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    zIndex: 999999    
  }
};
</script>

Suppressing features on specific web pages

You can enable the Contact Form, Chat, and Help Center from your Web Widget admin page, and then use the suppress attribute to change the offered features on particular pages of your site.

Examples of suppress include having Help Center deflection on some pages, but offering Chat or the Contact Form without deflection on other pages, and using suppress to offer tiered service levels to signed in and identified users.

The following example suppresses both Help Center and Chat:

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    chat: {
      suppress: true
    },
    helpCenter: {
      suppress: true
    }
  }
};
</script>

Customizing widget text

You use the translations object to change some of the default text displayed in various elements of the Web Widget, in addition to controlling the language the text appears in.  Elements are grouped by feature -- for example, Launcher, Help Center, and Contact Form.

You can customize the following widget components:

Component Details

Component: Launcher
Key: chatLabel
Description: Text on the launcher button when Chat is enabled and Help Center is not on
Default: "Chat"

Component: Launcher
Key: label 
Description: Text on the launcher button
Default: "Help" "Support" or "Feedback" as defined on the Web Widget Admin page
Component: helpCenter
Key: title
Description: The title of the Help Center page
Default: "Help"
Component: helpCenter
Key: messageButton
Description: Text on the button in the Help Center form that loads the Contact form (~20 character limit)
Default: "Leave us a message or "Contact us" as defined on the Web Widget Admin page
Component: helpCenter
Key: chatButton
Description: Text on the button shown in the Help Center form that loads the Chat (~20 character limit)
Default: "Live chat"
Component: contactForm
Key: title
Description: Title of the Contact form
Default: "Leave us a message or "Contact us" as defined on the Web Widget Admin page

Adding a subject line to the contact form

The default contact form is designed to promote engagement and offer a streamlined user experience when completing the contact form. While the default contact form does not include a subject line, you may want to add one to enhance the support experience for some customers. With the Subject setting you can set the Widget to include a subject line in the default contact form.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    contactForm: {
      subject: true
    }
  }
};
</script>

Hiding the "View Original Article" button

The "View Original Article” button bridges the article in the Web Widget and the article in the Help Center itself. You can hide this button by using the originalArticleButton object and setting it to false.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      originalArticleButton: false
    }
  }
};
</script>

Limiting search results

With the Help Center filter setting you can set the widget to automatically limit end-user searches to specified categories, sections, or labels.

Example: Searches restricted to the designated section.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        section: '200154474-Announcements'
      }
    }
  }
};
</script>

Example: Searches restricted to the designated category.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        category: '200053794-General'
      }
    }
  }
};
</script>

Example: Searches restricted to results with the designated label.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        label_names: 'orders'
      }
    }
  }
};
</script>

To filter to multiple items in a category, section, or label, specify the IDs as a comma-separated string.

Example: Limiting to two categories.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        category: '200053794-General',
        label_names: 'shipping'
      }
    }
  }
};
</script>

To filter to a combination of category, section and/or label, specify all relevant items and separate with a comma.

Example: Limiting to the general category and the shipping label.

<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      filter: {
        category: '200053794-General',
        label_names: 'shipping'
      }
    }
  }
};
</script>

Hiding the "View more" button

The "View more" button appears in the widget when an end-user performs a Help Center search, and more than three matching articles are found. You can disable this option using the zESettings object for the button.

Example:

<script type="text/javascript">
window.zESettings = {
  webWidget: {
    helpCenter: {
      viewMore: false
    }
  }
};
</script>

Customizing multiple elements in the zESettings object

You can include multiple customizations in the zESettings object.

Items that are specific to the Contact Form, Help Center, and Zendesk Chat are nested under those headings (contactForm, helpCenter and chat) while global items are included separately.

For instance, in the example below, the following customizations are defined:

  • The widget is offset 400px horizontal, and 400px vertical. Offset is a global item, so it has its own entry.
  • The Help Center search component:
    • Does not include the Original Article button.
    • Has the title “Search for help” for English-language users, and “Have your say” for all other languages.
  • The chat component is disabled.
  • The title of the contact form component is “Search for help” for English-language users, and “Have your say” for all other languages.
  • The widget launcher is labeled “Make a request” for English-language users, and “Get help” for all other languages.
<script type="text/JavaScript">
window.zESettings = {
  webWidget: {
    offset: { horizontal: '400px', vertical: '400px' },

    helpCenter: {
      originalArticleButton: false,
      title: {
        'en-US': 'Search for help',
        '*': 'Have your say'
      }
    },

    chat: {
      suppress: true
    },

    contactForm: {
      title: {
        'en-US': 'Search for help',
        '*': 'Have your say'
      }
    },

    launcher: {
      label: {
        'en-US': 'Make a request',
        '*': 'Get help'
      }
    }
  }
};
</script>
Have more questions? Submit a request

Comments

  • 0

    Hi Aimee - Any plans to make it easy to adjust the placeholder text in the helpCenter component? 

  • 0

    how to add default text on description like the (name and email)?thanks

  • 0

    HI @nicole and Pal3 Kuno, customizations for placeholder text and field names are not currently available but are something that we are exploring. If you could, please create a post (or upvote another if there is a suitable match) in the Web Widget Customizations beta forum and let us know a bit more about your use case and how the current text isn't working for you. Then others can add to it and we can better assess the right solution. Thanks! Erica

  • 1

    Are there any plans for further customization to the widget? IE. Adding more fields really. At this point I only see the ability to add two custom fields. Thanks. 

  • 0

    Hi @Ryan: Yes, this is something that we are exploring. I don't have any ETAs yet but stay tuned.

  • 0

    How to prepopulate a description field?

  • 0

    Is there any way to customize the size of the widget. It's a tad to big for our page, and I'd like to change things like padding, and margins 

  • 0

    I have the same question as Lena, it is now 400 pix and that is too wide for the widget on a mobile

  • 0

    Hi,

    I'm trying to change the button texte on the *mobile* widget, but it doesn't work (it always says "Chat"). Here is what I have but after the widget code :

    window.zESettings = {
     launcher: {
      chatlabel: 'Aide'
     }
    };

  • 0

    Hi Lena & Hubert:

    No, I'm afraid that there is no sizing configurations currently available for the Widget. But I'd be eager to learn more about your design needs. The Widget is optimized for mobile devices so should appear well on mobile devices, so I'd be interested in learning more about what you're seeing.

    All the best,
    Erica

  • 0

    Jerome: I've turned your request into a support ticket. 
    Thanks, 
    Erica

  • 0

    Erica - My use case is on desktop. Our page has relevant data in all corners of the page, and often that big help button covers the content. I'd like to be able to either resize the button, but even better provide my own html to render it. 

  • 0

    Is there a way to only show it the first time a user visits the page? Or only show it to users that <x days old?

  • 0

    Hi Lena:
    Take a look at zE.activate/show/hide. You can create your own button or text link and use it to activate the widget. That way the launcher doesn't cover your corners.

  • 0

    Hi Lizzy:
    We don't have those types of triggers build into the Web Widget at this time, but I appreciate the request and feedback of your use case. If you are using chat you may be able to set up specific chat Triggers, however. In addition, you could use the JavaScript APIs in conjunction with custom coding for the Web Widget to create your desired logic.

  • 0

    What is the locale fallback process for custom widget text? For example, user has locale set to Italian, and I have a Web Widget with localizations for contactForm title in English and Spanish. What value will Web Widget display to these users?

  • 0

    Hi Zac:

    It would likely fall back to English but I recommend that if you are creating custom text strings for some langugaes you could just add the '*': 'Preferred_text_for_all_others' as well and it would display the * string if the other specified locales aren't in use.

  • 0

    @Erica - thanks for that. Somehow, I thought the "*" string would override all of the strings for my other locales.

  • 0

    Hi,

    I'm trying to use the `suppress` option on the contactForm, but strangely, this completely hides the widget. Have to pop it manually using zE.show(). Is it intended behaviour or am I doing something wrong?

    Regards!

  • 0

    @Francois: I created a ticket so that we can help you troubleshoot.

  • 0

    Hi,

    How could we add a simple link for customers to download our TeamViewer QuickSupport applet when we are signed in to Chat.

    Thank you,

    SL

  • 0

    Hello, 

    We have a case where our client is managing the widget embed code in Google Tag Manager. Design is dictating that the launcher widget meet certain specs. Is it advisable in this case to simply modify the launcher with a pure CSS approach? I understand the widget is regularly updated, and I don't want to be in a situation where we're continually having to update the style code to accommodate.

    Regards!

  • 0

    Hi Scott,

    There are a few options there that we can look at for embedding that type of functionality based on your needs and workflow.

    Easiest option might be to create a trigger in chat to give the link out when the chat starts, another option might be to create a macros that agents can send out the link when they feel a link is needed.

    Most customers also use the Help Center to add an article with instructions on how to properly install the extension, along with the app as an attachment.

  • 0

    Hi Steve,

    We might need to take a closer look at your needs in order for me to suggest a good workflow here, I've created a ticket for you and will be reaching out shortly.

  • 0

    Hi all: We have added some new custom ticket field related features to the Ticket Forms beta including the ability to add 1, 2 or all visible and editable custom ticket fields to the default custom form, pre-populating ticket fields and displaying the custom field description text. I look forward to hearing how these go for you. 

    Edited by Erica Wass
  • 0

    Is there a way to update the originalArticleButton "href" in help center? 

    I need to read the full article from a different data source (AEM page).

    Help Appreciated!

Please sign in to leave a comment.

Powered by Zendesk