Core messaging Web Widget API
Core settings and commands affect the entire messaging widget.
Show
zE('messenger', '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.
Parameters
None
Hide
zE('messenger', 'hide');
Hides all parts of the widget from the page. You can invoke it before or after page load.
Parameters
None
Open
zE('messenger', 'open');
Opens the messaging Web Widget.
Parameters
None
Close
zE('messenger', 'close');
Closes the messaging Web Widget.
Parameters
None
On Open
zE('messenger:on', 'open', callback<function>)
Executes a callback when the messaging Web Widget opens.
Parameters
callback: Function.
Example
zE("messenger:on", "open", function () {console.log(`You have opened the messaging Web Widget`)})
On Close
zE('messenger:on', 'close', callback<function>)
Executes a callback when the messaging Web Widget closes.
Parameters
callback: Function.
Example
zE("messenger:on", "close", function () {console.log(`You have closed the messaging 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 messaging 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 messaging Web Widget. It overrides the messaging 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 messaging Web Widget code snippet.
Parameters
newLocale: String. The locale string to change the locale to.
Example
zE("messenger:set", "locale", "es")
Set zIndex
zE('messenger:set', 'zIndex', newZIndex<number>);
Sets the CSS property z-index on all the iframes for the messaging 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 messaging Web Widget have a z-index value of 999999.
Parameters
newZIndex: Number. The z-index value to use for all iframes for the messaging Web Widget
Example
zE("messenger:set", "zIndex", 123)
Set cookies
zE('messenger:set', 'cookies', range<enum>);
The messaging Web Widget uses a mixture of cookies as well as local and session storage in order to function.
The messaging Web Widget defines three cookies categories: essential, functional, and analytics. For more information, see Zendesk In-Product Cookie Policy. By default, Web Widget stores essential, functional, and analytics cookies.
If the end user has opted in for all cookies, you can set range as "all" to let the messaging Web Widget know that all cookies, including analytics cookies, should be stored.
If the end user has opted out of cookies, you can set range to "none" to let the messaging Web Widget know that it is unable to use any of these storage options. Setting range to "none" will result in the messaging Web Widget being hidden from the end user and all values in local and session storage being deleted.
If the end user has opted out of analytics cookies, you can set range as "functional" to let the messaging Web Widget know that all cookies, besides analytics cookies, should be stored.
Note: Analytics cookies are currently used in two functionalities: Pages viewed (Visitor's path) and Proactive messages analytics. Disabling analytics cookies will cause the absence of these features.
Parameters
range: Enum. The only acceptable values areall,functional, andnone.
Example
zE("messenger:set", "cookies", "all")
Set Conversation Fields
zE('messenger:set', 'conversationFields', conversationFields<{ id: <string>, value: <string|number|boolean> }[]>;
Allows values for conversation fields to be set in the client to add contextual data about the conversation. Conversation fields must first be created as custom ticket fields and configured to allow their values to be set by end users in Admin Center. To use conversation fields, see Using Messaging Metadata with the Zendesk Web Widget and SDKs.
Note: Conversation fields aren't immediately associated with a conversation when the API is called. It'll only be applied when end users start a conversation or send a message in an existing conversation from the page it's called from. Associating conversation fields with a conversation is an asynchronous operation. Use callback to make sure your fields will be associated properly.
System ticket fields, such as the Priority field, are not supported.
Conversation fields are cleared when the authentication API to sign-out is called. The conversationFields API needs to be called again to apply field metadata to a fresh conversation.
Parameters
conversationFields: Array. Formatted as an array of objects withidandvalueproperties.
| Property | Type | Description |
|---|---|---|
id | string | id of custom ticket field |
value | string, number or boolean | value of custom ticket field |
callback: Function. Optional parameter.
Examples
For example, if the id of your custom field for order total is 123456789 and you want to set its value to 100.50, then you would call:
zE("messenger:set", "conversationFields", [{ id: "123456789", value: 100.50 }])
Also, if you want to make sure that your conversation fields were set properly before opening the messaging Web Widget, then you would call:
const openWidget = () => {// your function to trigger messaging Web Widget to open}zE("messenger:set", "conversationFields", [{ id: "123456789", value: 100.50 }], openWidget)
Set Conversation Tags
zE('messenger:set', 'conversationTags', conversationTags<string[]>);
Allows custom conversation tags to be set in the client to add contextual data about the conversation. To learn more about Messaging Metadata, see Introduction to Messaging Metadata.
Conversation tags do not need any prerequisite steps before the API can be used. To use conversation tags, see Using Messaging Metadata with the Zendesk Web Widget and SDKs.
Note: Conversation tags aren't immediately associated with a conversation when the API is called. It'll only be applied when end users start a conversation or send a message in an existing conversation from the page it's called from.
Conversation tags are cleared when the authentication API to sign-out is called. The conversationTags API needs to be called again to apply tag metadata to a fresh conversation.
Parameters
conversationTags: Array. Formatted as an array of strings.
Example
For example, to apply sales and computer_accessories tags to a sales conversation about computer accessories, then you would call:
zE("messenger:set", "conversationTags", ["sales", "computer_accessories"])
Reset Widget
zE('messenger', 'resetWidget', callback<function>)
The resetWidget method clears all widget local state, including user data, conversations, and connections. It accepts an optional callback function that executes after the reset completes successfully. The method also performs validation checks to ensure the widget isn't in a pending state before proceeding with the reset operation. This helps to prevent problems such as race conditions and abnormal application states.
Parameters
callback: Function. Executes when the widget has been reset successfully
Example
zE("messenger", "resetWidget", function () {console.log(`You have reset the messaging Web Widget`)})