This hands-on tutorial shows you how to embed the Web Widget on a web page, and configure some basic settings using Web Widget APIs.

Basic Web Widget configuration can be performed in the Admin section of Zendesk Support > Admin. However, the Web Widget APIs provide more extensive Web Widget customization.

The Web Widget APIs are client-side JavaScript APIs that can be used in your website. The Web Widget API lets you change properties of the Web Widget using settings or perform actions using commands. This quickstart shows you how to work with both settings and commands.

Though not necessary to work through this quickstart, a general understanding of HTML and JavaScript is recommended to use the Web Widget API in your organization's website. For more information, see HTML Introduction and JavaScript MDN.

This tutorial contains the following sections:

Related information:

Requirements

Creating a sample web page

In this section, you'll create a “Hello World” web page in CodePen, an online code editor.

To create a “Hello World!” web page

  1. In your web browser, go to https://codepen.io/pen/.
  2. In the top UI pane, click Change View, and select the left view option.
  3. In the HTML editor on the top right side, click the dropdown menu, and select Maximize HTML Editor.
  4. Copy and paste the following HTML code into the HTML editor.

    <!DOCTYPE html><html lang="en">
    <head>    <title>Hello, World!</title></head>
    <body>    <p>Hello, World!</p></body>
    </html>

The web page is displayed in the window on the right side.

Adding the Web Widget on your web page

To add the Web Widget on your web page, you need to copy and paste the Web Widget script in Zendesk Support.

  1. Click the Admin icon () in the sidebar, then select Channels > Widget.
  2. Click the Setup tab, if it is not already selected.
  3. Under the code box, click Copy to clipboard.
  4. In your HTML editor, paste the script before the closing tag. For example:

    <!DOCTYPE html><html lang="en">

    <head> <title>Hello, World!</title> </head>

    <body> <p>Hello, World!</p>

    <!-- Start of Zendesk Widget script --> <script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=YOUR_SNIPPET_KEY">; </script> <!-- End of Zendesk Widget script --> </body>

    </html>

By default, the Web Widget is displayed on the bottom right of your web page.

Using API settings to customize the Web Widget

Next, you’ll use the API settings to change some common Web Widget properties. You access the API settings using JavaScript in the source code of your website. You can add the scripts directly to your web page, or maintain them in a separate folder and link to them from the web page. For the purposes of this tutorial, we’ll add scripts directly to the web page.

The basic JavaScript syntax for API settings is as follows:

window.zESettings = {  webWidget: {    setting,    setting,    ...  }};

The syntax can vary for API settings. For example, the offset API setting has multiple property value pairs, and channel-specific settings such as the attachment API setting for Contact Form contains a child object.

The window.zESettings object must be added before the Web Widget snippet in a web page, so the settings can be applied before the Web Widget is loaded.

In the following sections, you’ll use core settings to change the color of the Web Widget and to reposition it. For a complete list of core settings, see the Web Widget API documentation.

Changing the Web Widget color

In this example, the Web Widget’s default blue color will be changed to green using the theme property of the color setting. The theme property accepts HEX codes. For example:

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

To change the Web Widget color

In the HTML editor, paste the script in bold after the header tags, but before the Web Widget snippet.

<!DOCTYPE html><html lang="en">

<head> <title>Hello, World!</title> <meta charset="utf-8"> </head>

<body> <p>Hello, World!</p>

<script type="text/javascript"> window.zESettings = { webWidget: { color: { theme: '#78a300' } } }; </script> <!-- Start of Zendesk Widget script --> <script id="ze-snippet" src="https://static.zdassets.com/ekr/YOUR_SNIPPET_KEY">; </script> <!-- End of Zendesk Widget script --> </body>

</html>

The Web Widget color on the web page should be green.

Changing the Web Widget position

Next, you'll reposition the Web Widget on the web page to be 100px from the bottom and 100px from the right. You can reposition the widget using the offset setting.

To change the Web Widget position

In the HTML editor, add the offset setting to the existing window.zESettings object, setting the horizontal and vertical parameters to 100px. Make sure you don’t forget to add a comma after the color setting. For example:

<script type="text/javascript">window.zESettings = {  webWidget: {    color: { theme: '#78a300' },    offset: { horizontal: '100px', vertical: '100px' }  }};</script>

The web page should display the repositioned Web Widget.

Using API commands to customize the Web Widget

Commands let you customize some Web Widget general settings and functions embedded in the Web Widget. It follows the following basic syntax:

zE('webWidget:<action>', '<event|property>', <parameters>);

where

  • is a Web Widget setting or action
  • <event|property> is a property or event associated with the setting or action
  • is an argument or value associated with the event or property.

Note: All API commands must be placed after the Web Widget snippet in your web page source code.

In the following sections, you’ll use core commands to set the locale of the Web Widget and to hide it. For a complete list of core commands, see the Web Widget API documentation.

Setting the Web Widget locale

By default, the Web Widget displays the language that matches the header of the web browser. In this instance, we would like to change the Web Widget locale to French.

The setLocale command sets the language for the Web Widget. Supported locales are shown in https://support.zendesk.com/api/v2/rosetta/locales/public.json.

To change the locale

In the HTML editor, add the following setLocale command between script tags after the Web Widget snippet:

<script type="text/javascript">  zE('webWidget', 'setLocale', 'fr');</script>

The Web Widget language on the web page should display in French.

Hiding the Web Widget

Next, you'll create a button to hide the Web Widget using the hide command. It can also be used to hide the Widget before the page loads.

To create a button to hide the Web Widget

In the HTML editor, between the body tags, add the following hide command using button tags:

<button onclick="zE('webWidget', 'hide')">Hide Web Widget</button>

The Hide Web Widget button should be displayed on the web page. Clicking on the button hides the Web Widget.

After configuring your Web Widget, your HTML file should look something like this:

<!DOCTYPE html><html lang="en">
<head>    <title>Hello, World!</title>    <meta charset="utf-8"></head>
<body>    <p>Hello, World!</p>
    <script type="text/javascript">        window.zESettings = {            webWidget: {                color: {                    theme: '#78a300'                },                offset: {                    horizontal: '100px',                    vertical: '100px'                },                    };    </script>    <!-- Start of Zendesk Widget script -->    <script id="ze-snippet" src="https://static.zdassets.com/ekr/YOUR_SNIPPET_KEY">    </script>    <!-- End of Zendesk Widget script --><script type="text/javascript">  zE('webWidget', 'setLocale', 'fr');</script>
  <button onclick="zE('webWidget', 'hide')">Hide Web Widget</button></body></html>