Web Widget API
Open
zE('messenger', 'open');
Opens the Web Widget.
Close
zE('messenger', 'close');
Closes the Web Widget.
Unread Messages
zE('messenger:on', 'unreadMessages', callback<function>)
Executes a callback when the number of unread messages changes.
Parameters
callback: Function. The callback is passed the currentcount<number>of unread messages when executed.
Example
zE('messenger:on', 'unreadMessages', function (count) {console.log(`You have ${count} unread message(s).`);})
Custom Launcher
To create a custom Web Widget launcher and define how it behaves, use the open, close & unreadMessages API and launcher settings for Messaging in Admin Center.
Set locale
zE('messenger:set', 'locale', newLocale<string>)
Sets the locale of the Web Widget. It overrides the Web Widget's default behavior of matching the same language an end user has set in their web browser.
The command takes a locale string as an argument. For a list of supported locales and associated codes, use the following Zendesk public REST API endpoint: https://support.zendesk.com/api/v2/locales/public.json.
Note: This code should be placed immediately after the Web Widget code snippet.
Parameters
newLocale: String. The locale string to change the locale to.
Set zIndex
zE('messenger:set', 'zIndex', newZIndex<number>);
Sets the CSS property z-index on all the iframes for the Web Widget.
When two elements overlap, the z-index values of the elements determine which one covers the other. An element with a greater z-index value covers an element with a smaller one.
By default, all iframes in the Web Widget have a z-index value of 999999.
Parameters
newZIndex: Number. The z-index value to use for all iframes for the Web Widget
Example
zE('messenger:set', 'zIndex', 123);
Set cookies
zE('messenger:set', 'cookies', isEnabled<boolean>);
The Web Widget uses a mixture of cookies as well as local and session storage in order to function.
If the end user has opted out of cookies, you can use the command below to let the Web Widget know that it is unable to use any of these storage options.
Currently, disabling cookies will result in the Web Widget being hidden from the end user and all values in local and session storage being deleted.
Parameters
isEnabled: Boolean. If false, the Web Widget will be hidden from view and all stored data will be deleted.
Example
zE('messenger:set', 'cookies', false);
Authentication
The Web Widget allows authentication of users so that their identity can be verified by agents using Zendesk.
Login
zE('messenger', 'loginUser', function (callback) {callback('new-jwt-for-user');});
If your application has a login flow, or if a user needs to access the same conversation from multiple devices, you can use the loginUser API.
You can associate users with your own user directory by issuing a JWT credential during the login flow. For information on creating signing keys, see Authenticating end users in messaging. For information on creating JWT tokens, see Enabling authenticated visitors for messaging with Zendesk SDKs.
Expiring JWTs
If you want to generate credentials that expire after a certain amount of time, using JWTs is a good way to accomplish this.
The exp (expiration time) property of a JWT payload is honored by the Web Widget. A request made with a JWT which has an exp that is in the past is rejected.
Keep in mind that using JWTs with exp means you need to handle regeneration of JWTs in the function that you provide when calling the loginUser API.
Logout
zE('messenger', 'logoutUser');
Your app may have a logout function that brings users back to a login screen. In this case, revert the Web Widget to a pre-login state by calling the logoutUser API.