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

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. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'messagingOpened'}

Example

zE("messenger:on", "open", function (event) {  console.log(`You have opened the messaging Web Widget`, event)})

const unsubscribe = zE("messenger:on", "open", function (event) {  console.log(`You have opened the messaging Web Widget`, event)});
unsubcribe() // calling it will unsubscribe from the event

On Close

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

Executes a callback when the messaging Web Widget closes. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'messagingClosed'}

Example

zE("messenger:on", "close", function (event) {  console.log(`You have closed the messaging Web Widget`, event)})

const unsubscribe = zE("messenger:on", "close", function (event) {  console.log(`You have closed the messaging Web Widget`, event)});
unsubcribe() // calling it will unsubscribe from the event

On Proactive Message Displayed

zE('messenger:on', 'proactiveMessageDisplayed', callback<function>)

Executes a callback when a proactive message is displayed. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'proactiveMessageDisplayed'  payload: {    proactiveMessageId: number //The ID of the proactive message    campaignId: string //The ID of the campaign for the proactive message  }}

Example

zE("messenger:on", "proactiveMessageDisplayed", function (event) {  console.log(`Proactive message displayed`, event)})

const unsubscribe = zE("messenger:on", "proactiveMessageDisplayed", function (event) {  console.log(`Proactive message displayed`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Proactive Message Clicked

zE('messenger:on', 'proactiveMessageClicked', callback<function>)

Executes a callback when a proactive message is clicked. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'proactiveMessageClicked'  payload: {    proactiveMessageId: number //The ID of the proactive message    campaignId: string //The ID of the campaign for the proactive message  }}

Example

zE("messenger:on", "proactiveMessageClicked", function (event) {  console.log(`Proactive message clicked`, event)})

const unsubscribe = zE("messenger:on", "proactiveMessageClicked", function (event) {  console.log(`Proactive message clicked`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation Started

zE('messenger:on', 'conversationStarted', callback<function>)

Executes a callback when a conversation is started. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationStarted'  payload: {     conversation: {      id: string //The ID of the created conversation    }  }}

Example

zE("messenger:on", "conversationStarted", function (event) {  console.log(`Conversation started`, event)})

const unsubscribe = zE("messenger:on", "conversationStarted", function (event) {  console.log(`Conversation started`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation Opened

zE('messenger:on', 'conversationOpened', callback<function>)

Executes a callback when the conversation view is shown to the user. This event does not wait for messages to be rendered.

Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationOpened'  payload: {    conversation: {      id: string | null //The ID of the conversation (optional - null when there is no active conversation yet - eg while starting new conversation)    }  }}

Example

zE("messenger:on", "conversationOpened", function (event) {  console.log(`Conversation opened`, event)})

const unsubscribe = zE("messenger:on", "conversationOpened", function (event) {  console.log(`Conversation opened`, event)});
unsubscribe() // calling it will unsubscribe from the event

On New Conversation Button Clicked

zE('messenger:on', 'newConversationButtonClicked', callback<function>)

Executes a callback when the new conversation button is clicked. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'newConversationButtonClicked'  payload: {    newConversationSource: string //The source from which the new conversation button is clicked (CONVERSATION_LIST)  }}

Example

zE("messenger:on", "newConversationButtonClicked", function (event) {  console.log(`New conversation button clicked`, event)})

const unsubscribe = zE("messenger:on", "newConversationButtonClicked", function (event) {  console.log(`New conversation button clicked`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation With Agent Requested

zE('messenger:on', 'conversationWithAgentRequested', callback<function>)

Executes a callback when a conversation with an agent is requested. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationWithAgentRequested'  payload: {    conversation: {      id: string //The unique identifier of the conversation    }  }}

Example

zE("messenger:on", "conversationWithAgentRequested", function (event) {  console.log(`Conversation with agent requested`, event)})

const unsubscribe = zE("messenger:on", "conversationWithAgentRequested", function (event) {  console.log(`Conversation with agent requested`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation Agent Assigned

zE('messenger:on', 'conversationAgentAssigned', callback<function>)

Executes a callback when an agent is assigned to a conversation. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationAgentAssigned'  payload: {    conversation: {      id: string //The unique identifier of the conversation    }  }}

Example

zE("messenger:on", "conversationAgentAssigned", function (event) {  console.log(`Agent assigned to conversation`, event)})

const unsubscribe = zE("messenger:on", "conversationAgentAssigned", function (event) {  console.log(`Agent assigned to conversation`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Messages Shown

zE('messenger:on', 'messagesShown', callback<function>)

Executes a callback when messages are being rendered in the conversation screen. This event is called every time messages (not typing indicators or timestamps) are being added to the view.

Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'messagesShown'  payload: {    conversation: {      id: string //The ID of the conversation    },    messages: [      {        id: string //The ID of the message        received: number //Timestamp of when message was received        role: string //Author role: business or user      }    ]  }}

Example

zE("messenger:on", "messagesShown", function (event) {  console.log(`Messages shown`, event)})

const unsubscribe = zE("messenger:on", "messagesShown", function (event) {  console.log(`Messages shown`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Postback Button Clicked

zE('messenger:on', 'postbackButtonClicked', callback<function>)

Executes a callback when a postback button is clicked. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'postbackButtonClicked'  payload: {    actionName: string //The postback button action name    conversation: {      id: string //The unique identifier of the conversation    }  }}

Example

zE("messenger:on", "postbackButtonClicked", function (event) {  console.log(`Postback button clicked`, event)})

const unsubscribe = zE("messenger:on", "postbackButtonClicked", function (event) {  console.log(`Postback button clicked`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation Extension Opened

zE('messenger:on', 'conversationExtensionOpened', callback<function>)

Executes a callback when the end user clicks a button to open conversation extensions. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationExtensionOpened'  payload: {    conversation: {      id: string //The unique identifier of the conversation    },    url: string //The URL of the page to be loaded  }}

Example

zE("messenger:on", "conversationExtensionOpened", function (event) {  console.log(`Conversation extension opened`, event)})

const unsubscribe = zE("messenger:on", "conversationExtensionOpened", function (event) {  console.log(`Conversation extension opened`, event)});
unsubscribe() // calling it will unsubscribe from the event

On Conversation Extension Displayed

zE('messenger:on', 'conversationExtensionDisplayed', callback<function>)

Executes a callback when a conversation extension finishes loading. Every call returns a function you can use to unsubscribe from the event.

Parameters

callback: Function.

The callback receives an event object <object> when it runs.

The event object <object> has the following structure:

{  id: string //The unique identifier of the event (UUID)  createdAt: number //The Unix timestamp when the event is fired  type: 'conversationExtensionDisplayed'  payload: {    conversation: {      id: string //The unique identifier of the conversation    },    url: string //The URL of the loaded page  }}

Example

zE("messenger:on", "conversationExtensionDisplayed", function (event) {  console.log(`Conversation extension displayed`, event)})

const unsubscribe = zE("messenger:on", "conversationExtensionDisplayed", function (event) {  console.log(`Conversation extension displayed`, event)});
unsubscribe() // calling it will unsubscribe from the event

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 current count<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 are all, functional, and none.

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. Additionally, conversation fields are added to the support ticket at the time of ticket creation. This API can't be used to update metadata of an existing ticket.

System ticket fields, such as the Priority field, are not supported.

Conversation fields are cleared when the reset widget API or 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 with id and value properties.

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.5 }])

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.5 }],  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. Additionally, conversation tags are added to the support ticket at the time of ticket creation. This API can't be used to update metadata of an existing ticket.

Conversation tags are cleared when the reset widget API or 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 also clears all conversation tags and conversation fields data. Use the Conversation Fields and Tags API again to apply conversation fields and tags data to a new conversation. The resetWidget method 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`)})

Set Customization

zE('messenger:set', 'customization', customizationOptions<object>);

Dynamically updates the Web Widget Messenger's appearance and behavior. The Customization API lets you adjust the widget using configuration objects for theme colors, common settings, conversation list, and message log.

Parameters

theme: Object. Optional parameter. Defines the color palette for supported UI elements of the Web Widget Messenger. The theme object accepts any subset of supported color properties, allowing you to customize one or many aspects of the messenger's appearance. Each property must be a valid CSS color string (for example, hex, rgb, hsl, or named color). If a property is not provided, the widget uses the default color. See Customizing Web Widget colors.

common: Object. Optional parameter. Settings that apply globally to all parts of the widget.

Property	Type	Description
`hideHeader`	boolean	Hides the header across both the conversation list and the message log
`contentScale`	number	Adjusts the widget's content scaling as a percentage (range: 50-200, default: 100)

conversationList: Object. Optional parameter. Settings that customize the conversation list.

Property Type Description
hideNewConversationButton boolean Hides the "New Conversation" button
hideHeader boolean Hides the header only on the conversation list
messageLog: Object. Optional parameter. Settings that customize the message log view.

Property Type Description
hideHeader boolean Hides the header on the message log page

Property	Type	Description
`hideNewConversationButton`	boolean	Hides the "New Conversation" button
`hideHeader`	boolean	Hides the header only on the conversation list

Property	Type	Description
`hideHeader`	boolean	Hides the header on the message log page

Examples

Theme customization:

zE("messenger:set", "customization", {  theme: {    primary: "#FE5E41",    onPrimary: "#FFFFFF",    message: "#F3C178",    onMessage: "#5F0F00",    action: "#B0DB43",    onAction: "#000000",    businessMessage: "#fff",    onBusinessMessage: "#F10404",    background: "#DFE0E2",    onBackground: "#F10404",    error: "#FF1744",    onError: "#FFFFFF",    notify: "#FF007F",    onNotify: "#FFFFFF",    onSecondaryAction: "#000000"  }})

Hide header globally:

zE("messenger:set", "customization", {  common: {    hideHeader: true  }})

Adjust content scale:

zE("messenger:set", "customization", {  common: {    contentScale: 125  }})

Hide new conversation button:

zE("messenger:set", "customization", {  conversationList: {    hideNewConversationButton: true  }})

Full customization example:

zE("messenger:set", "customization", {  theme: {    primary: "#FE5E41",    onPrimary: "#FFFFFF",    message: "#F3C178",  },  common: {    contentScale: 110,    hideHeader: false  },  conversationList: {    hideNewConversationButton: true,    hideHeader: false  },  messageLog: {    hideHeader: true  }})

Create New Conversation

zE('messenger:ui', 'newConversation', conversationOptions<object>);

Creates a new conversation with options to customize the display name, icon, and metadata. Once created, the conversation is immediately loaded into the message log.

Parameters

conversationOptions: Object. Optional parameter. Configuration for the new conversation.

Property Type Description
displayName string Conversation title
iconUrl string Icon URL of the conversation
metadata object Conversation metadata

Property	Type	Description
`displayName`	string	Conversation title
`iconUrl`	string	Icon URL of the conversation
`metadata`	object	Conversation metadata

Examples

Create conversation with default settings:

zE("messenger:ui", "newConversation")

Create conversation with display name:

zE("messenger:ui", "newConversation", {  displayName: "Technical Support"})

Create conversation with full options:

zE("messenger:ui", "newConversation", {  displayName: "Support Request",  iconUrl: "https://example.com/icon.png",  metadata: {    priority: "high",    orderId: 12345  }})

Embedded Mode

zE('messenger', 'render', config<object>, errorCallback<function>);

Renders the widget in either floating or embedded mode. In embedded mode, the widget integrates directly into specified containers on your page, automatically adjusting its dimensions to fit the container.

Disabling Auto-Rendering

To prevent the widget from automatically rendering in floating mode, include the following script before the widget loads:

<script>  window.zEMessenger = {    autorender: false  }</script>

Parameters

Name	Type	Mandatory	Description
config	object	false	Configuration options for how the widget is rendered. If omitted, the widget renders in floating mode
errorCallback	function	false	A callback function to handle the result of the render attempt

Config Object Properties:

Property	Type	Description
`mode`	string	Render mode: `'embedded'` or `'floating'`
`widget`	object	Full widget configuration
`conversationList`	object	Conversation list configuration
`messageLog`	object	Message log configuration

Each component object (widget, conversationList, messageLog) accepts a targetElement property — a CSS selector or element ID that specifies where the component should be rendered.

Note: In embedded mode, your configuration must include at least one of the following: widget, conversationList, or messageLog.

Error Callback

When errorCallback is called, it receives an error parameter which will be either:

null, indicating a successful render
An instance of RenderFailedError which contains information about why the render failed

The RenderFailedError class has the following properties:

Name	Type	Description
message	string	A descriptive message that explains the error
reason	string	Provides additional details on the cause of the failure
type	string	Identifies the error type as `RenderFailedError`

Possible Error Reasons:

Reason	Description
InvalidArgument	Config is not an object
InvalidMode	Mode is not `'floating'` or `'embedded'`
MissingEmbeddedConfiguration	Embedded mode without required config
InvalidConfiguration	Widget, conversationList, or messageLog is not an object
InvalidTargetElement	targetElement is missing or not a string
TargetElementNotFound	Target element doesn't exist in the DOM
InvalidCssSelector	CSS selector is invalid

Examples

Full widget in a container:

First, create an HTML container element where you want the widget to appear. This <div> acts as a placeholder on your page:

<div id="my-messenger-container"></div>

Next, use JavaScript to embed the widget inside that container by calling the render method and specifying the target by its selector:

zE("messenger", "render", {  mode: "embedded",  widget: {    targetElement: "#my-messenger-container"  }})

With error handling:

zE("messenger", "render",   {    mode: "embedded",    widget: {      targetElement: "#my-messenger-container"    }  },  function errorCallback(error) {    if (error) {      // Example error handling      const { type, reason, message } = error      console.error(`Render failed: ${reason} - ${message}`)            // Handle specific error types      if (reason === 'TargetElementNotFound') {        console.error("The container element was not found in the DOM")      }    } else {      console.log("Widget rendered successfully")    }  })

Conversation list only:

zE("messenger", "render", {  mode: "embedded",  conversationList: {    targetElement: "#conversations-container"  }})

Message log only:

zE("messenger", "render", {  mode: "embedded",  messageLog: {    targetElement: "#messages-container"  }})

Split view (conversation list + message log):

zE("messenger", "render", {  mode: "embedded",  conversationList: {    targetElement: "#left-sidebar"  },  messageLog: {    targetElement: "#main-content"  }})

Container Availability

Make sure the HTML container element is present in the DOM before calling zE('messenger', 'render', config). If the element is missing, an error will be logged in the console.

Web

Android

iOS

Unity

Core messaging Web Widget API