Core API

Core settings and commands affect the entire widget.


The Web Widget (Classic) has the following core settings:


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


The widget's contactOptions object, which represents a component that lets the user choose between starting a chat or submitting a ticket, has the following settings:

Contact Options Example

To learn more about contact options, see Offering end-users multiple contact options in the Zendesk help center.

Note: chatLabelOnline and contactFormLabel applies to the contact options shown to the end user on the Answer Bot channel.


<script type="text/javascript">  window.zESettings = {    webWidget: {      contactOptions: {        enabled: true,        contactButton: { '*': 'Get in touch' }      }    }  };</script>


The widget's launcher object, which represents the launcher button, has the following settings:


<script type="text/javascript">  window.zESettings = {    webWidget: {      launcher: {        chatLabel: {          '*': 'Chat now'        },        mobile: {          labelVisible: true        }      }    }  };</script>


The Web Widget (Classic) has the following core commands:


zE('webWidget', 'clear');

Clears all forms in the Web Widget.




zE('webWidget', 'close');

If the widget is opened, this command closes the widget and shows the launcher.



get display

zE('webWidget:get', 'display');

Gets the current widget display. Depending on the features you have enabled, the command displays one of the following strings: helpCenter, chat, contactForm, talk, contactOptions, answerBot, or hidden.


zE('webWidget', 'hide');

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('webWidget', 'hide');</script>

After page load:

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


zE('webWidget', 'identify', data<object>);

Identifies an end user to Zendesk.

If you have access to your end user's name and email, use this command to pass the details to your Zendesk Support account.

If the user's email doesn't already exist in your Zendesk Support account, a new user record with the details is created.

User record creation is queued and there might be a few minutes delay before the user record appears in your Zendesk Support account. However, during high API traffic periods, Identify API calls are throttled and might be dropped resulting in user records not being created.

Identify API calls are throttled in several ways to prevent API abuse:

  • IP address: A limit to identify users on a single IP address.
  • Limit the creation of user records per account: Up to 50,000 user records created daily by a Zendesk Support account.
  • Payload: Throttled when a Zendesk Support account makes more than one API call using the same email address every 12 hours.

The Identify API call occurs when the widget loads. In the event that a ticket is submitted before a user record is created by the Identify API call, the details in the ticket are used for creating a user record.


  • The Identify API call can only specify an organization when a user record is first created. It can't be used to modify organizations on existing user records.

  • The Identify API only prepopulates the user's details in the Chat forms (Prechat, Chat Offline and Update Contact Details forms). To prefill all forms in any product configuration, please use prefill.

  • data: Object. Contains the properties name, email, and optional organization.

A console warning occurs when there are invalid keys, invalid data on valid keys, or when passing non-object types.

<script type="text/javascript">  zE('webWidget', 'identify', {    name: 'Akira Kogane',    email: '[email protected]',    organization: 'Voltron, Inc.'  });</script>

Note: Passing an organization only works for existing organizations in your Zendesk Support account. It does not create a new organization.


zE('webWidget', 'logout');

Clears an end user's session.



on open

zE('webWidget:on', 'open', callback<function>);

Executes a callback when the widget is opened.

  • callback: Function. Contains the code to be executed.
<script type="text/javascript">  zE('webWidget:on', 'open', function() {    console.log('The widget has been opened!');  });</script>

on close

zE('webWidget:on', 'close', callback<function>);

Executes a callback when the widget is closed.

  • callback: Function. Contains the code to be executed.
<script type="text/javascript">  zE('webWidget:on', 'close', function() {    console.log('The widget has been closed!');  });</script>

on userEvent

zE('webWidget:on', 'userEvent', function(userEvent<object>));

Executes a callback when a user event is fired. This can be used as a flexible way of integrating third party analytics tools into the widget, and filtering events sent to Google Analytics. This setting can be applied even when the analytics setting is used to disable user events tracking.

  • callback: Function. The callback to perform on each user event. Contains one parameter, userEvent, an object that contains the action, properties, and category of the event.

properties is either an object with the data for the given event or undefined as shown below.


Action Properties
Web Widget Opened undefined
Web Widget Minimised undefined


Action Properties
Chat Opened undefined
Chat Shown undefined
Chat Served by Operator { agent: <agent display name> }
Chat Rating Good undefined
Chat Rating Bad undefined
Chat Rating Removed undefined
Chat Comment Submitted undefined
Chat Request Form Submitted { department: <department name> }*

* Department may be undefined.

Contact Form

Action Properties
Contact Form Shown { id: <form id>, name: <form name>}**
Contact Form Submitted { id: <form id>, name: <form name>}**

** If ticket forms is not enabled, the property value is { name: 'contact-form'}.

Help Center

Action Properties
Help Center Shown undefined
Help Center Search { term: <search term>}
Help Center Article Viewed { id: <article id>, name: <article name>}
Help Center View Original Article Clicked { id: <article id>, name: <article name>}

Answer Bot

Note: Zendesk has renamed our bot capabilities. Answer Bot is now Zendesk bots. Article Recommendations are now autoreplies. For more information on this change, see this announcement.

Action Properties
Answer Bot Article Viewed { id: <article id>, name: <article name>}


Action Properties
Talk Shown { contactOption: <talk contact option> }
Talk Callback Request Submitted undefined
<script type="text/javascript">  zE('webWidget:on', 'userEvent', function(event) {    console.log(event.category, event.action,;  });</script>


zE('webWidget', 'open');

Forces the widget to open.




zE('webWidget', 'prefill', data<object>);

Pre-fills an end-user's details on forms inside the Web Widget.

  • data: Object. Contains a name, email and phone objects.
<script type="text/javascript">  zE('webWidget', 'prefill', {    name: {      value: 'isamu',      readOnly: true // optional    },    email: {      value: '[email protected]',      readOnly: true // optional    },    phone: {      value: '61431909749',      readOnly: true // optional    }  });</script>


zE('webWidget', 'reset');

Completely resets the state of the widget. To preserve end-user experience, this API only functions when the widget is minimized.




zE('webWidget', 'setLocale', data<string>);

Sets the widget locale.

The command takes a locale string as an argument. For a list of supported locales and associated codes, see

By default, the Web Widget (Classic) 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('webWidget', 'setLocale', data<string>); to specify the language.

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

  • data: String. The locale string to change the widget locale to.

The following example displays the widget in German:

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


zE('webWidget', 'show');

Displays the widget on the host page in the state it was in before it was hidden.

The widget is displayed by default on page load. You don't need to call show to display the widget unless you use hide.

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


zE('webWidget', 'toggle');

Opens the widget if it was closed, or closes the widget if it was opened.




zE('webWidget', 'updatePath', data<object>);

Updates the visitor path by setting the title to the current user's page title and url to the user's current url.

Note: This API also updates the path within Chat.

  • data: Object. This object accepts two optional string parameters title and url. Note that the url parameter must be a complete URL, including the scheme.
<script type="text/javascript">  zE('webWidget', 'updatePath', {    title: 'Voltron',    url: ''  });</script>


zE('webWidget', 'updateSettings', data<object>);

Updates the widget's zESettings. It can update multiple settings at once.

  • data: Object. Matches the structure defined in zESettings
<script type="text/javascript">  zE('webWidget', 'updateSettings', {    webWidget: {      chat: {        departments: {          enabled: ['finance', 'hr', 'sales'],          select: 'sales'        }      }    }  });</script>