DocumentationAPI Reference

Web Widget API v1

This page documents legacy zE methods. Zendesk introduced a new command syntax for greater flexibility. If you're still using these legacy methods, consider migrating to the command syntax.

The Web Widget API v1 consists of the following methods:

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

You can use the zE.identify, zE.hide, zE.show, and zE.activate methods before and after page load. For example, you can use them in click event handlers.

zE.setLocale

zE.setLocale(locale)

The method takes a locale string as an argument. For a list of supported locales and associated codes, see https://support.zendesk.com/api/v2/locales/public.json.

By default, the Web Widget is displayed to the end user in a language that matches the browser header of their web browser. If you want to force the Widget to be displayed in a specific language on your website, you can use zE.setLocale() to specify the language.

The following example displays the widget in German:

<script type="text/javascript">  zE(function() {    zE.setLocale('de');  });</script>

Note: This code should be placed immediately after the Web Widget code snippet.

Set Locale Example

zE.identify

zE.identify(userObj)

The method takes a JavaScript object with a name and email.

If you have access to your end user's name and email on the webpage (for example, if your user is signed in), you can use zE.identify() to pass the details of that user to your Zendesk Support account. This ensures your user data is in sync.

The Widget uses the information in the zE.identify() call to pre-populate the contact or pre-chat chat form. This saves the user from typing in the information. This is especially useful for end users using your website on a mobile device (screenshot below).

<script type="text/javascript">  zE(function() {    zE.identify({      name: 'John Citizen',      email: '[email protected]',    });  });</script>

The Widget contact form pre-populated using the data in zE.identify():

Identify Example

zE.hide

zE.hide()

The method completely hides all parts of the Widget from the page. You can invoke it before or after page load.

Before page load

<script type="text/javascript">  zE(function() {    zE.hide();  });</script>

After page load

<button onclick="zE.hide();">Hide Web Widget</button>

zE.show

zE.show()

The method displays the Widget on the host page in its starting 'button' state.

For example, when someone logs into your website, you could call zE.show() to conditionally render the widget for authenticated users only:

<script type="text/javascript">  if (loggedIn) {    zE(function() {      zE.show();    });  }</script>

Note: The widget will be displayed by default on page load when the Web Widget code snippet is present. You do not need to call zE.show() to display the widget unless zE.hide() is used.

zE.activate

zE.activate(options)

The method activates and opens the Widget in its starting state. The starting state will depend on how you configured the Widget on the Widget admin page.

For example, when someone clicks a 'Contact' button of your website, you could call zE.activate() to pop open the widget:

Parameters

options object - hideOnClose: If true, hides the widget after the user closes it, false by default

Default

<button onclick="zE.activate();">Contact Us</button>

With Options

<button onclick="zE.activate({hideOnClose: true});">Contact Us</button>

Note: Calling zE.activate() will also display the widget if it is hidden, you do not need to call zE.show() to use zE.activate().

zE.setHelpCenterSuggestions

zE.setHelpCenterSuggestions(options)

The method enhances the contextual help provided by the Web Widget.

Options

  • zE.setHelpCenterSuggestions({ url: true }) - In single-page apps, sets the query parameters in the URL as search terms without requiring the end user to refresh the page. This function should be called each time you want to set the suggestions. For example, navigating on a single-page app.

  • zE.setHelpCenterSuggestions({ search: 'search string' }) - Searches the Help Center for the specified search string. If results are found, displays the results as top suggestions when users click the Web Widget.

  • zE.setHelpCenterSuggestions({ labels: ['label1'] }) - For Guide Professional customers who use Help Center labels, searches the Help Center for articles with the given labels. If results are found, displays the results as top suggestions when users click the Web Widget.

Note: If you pass both search strings and labels, the labels are ignored.

Usage

Add the method in your HTML source code immediately after your Web Widget code snippet. Example:

<script type="text/javascript">  zE(function() {    zE.setHelpCenterSuggestions({ search: 'credit card' });  });</script>

The zE.setHelpCenterSuggestions() method can be called multiple times, which can be useful in a single-page application.