Tracking with Messaging Web Widget events

Messaging Web Widget events allow your website to listen for key moments and state changes in the Zendesk Messaging experience. By subscribing to these events, you can track engagement signals, follow support flows, and trigger your own logic at key points in the customer journey. For example, when the widget opens, a proactive message appears, or a conversation begins.

Why use Web Widget events?

• Analytics: Send events to your analytics platform (such as Google Analytics, Amplitude, or Mixpanel) to measure engagement and support effectiveness.
• Logging & Monitoring: Log unexpected states or behavior (for example, users repeatedly opening the widget without starting a conversation), track user journeys, and troubleshoot integration issues.

How it works

The Messaging Web Widget exposes an extended event API via:

zE('messenger:on', '<eventName>', callback)

Parameters

• callback: Function.

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

Each Web Widget event has its own event object <object> structure. You can find details about each event's structure in the API reference sections below.

Each call returns an unsubscribe function, allowing you to remove the listener. Example:

const unsubscribe = zE('messenger:on', 'open', (event) => {
  console.log('Widget opened', event)
})

unsubscribe()

Available Events

• MessagingOpened: Triggers when the messaging Web Widget opens.
• MessagingClosed: Triggers when the messaging Web Widget closes.
• ProactiveMessageDisplayed: Triggers when a proactive message is displayed.
• ProactiveMessageClicked: Triggers when a proactive message is clicked by the user.
• ConversationStarted: Triggers when a conversation is started.
• ConversationOpened: Triggers when the conversation view is shown to the user. This event does not wait for messages to be rendered.
• NewConversationButtonClicked: Triggers when the new conversation button is clicked.
• ConversationWithAgentRequested: Triggers when a conversation with an agent is requested.
• ConversationAgentAssigned: Triggers when an agent is assigned to a conversation.
• MessagesShown: Triggers 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.
• PostbackButtonClicked: Triggers when a postback button is clicked.
• ConversationExtensionOpened: Triggers when the end user clicks a button to open conversation extensions.
• ConversationExtensionDisplayed: Triggers when a conversation extension finishes loading.