Messaging Web Widget events API

Events allow you to subscribe to key moments and state changes in the Zendesk Messaging experience. Each subscription returns an unsubscribe function.

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

On Article Clicked

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

Executes a callback when the end user clicks an article link and the article is successfully opened inside the Article Viewer. 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: "articleClicked"
  payload: {
    articleId: number //The ID of the article
    articleTitle: string | null //The title of the article
  }
}

Example

zE("messenger:on", "articleClicked", function (event) {
  console.log(`Article clicked`, event)
})

const unsubscribe = zE("messenger:on", "articleClicked", function (event) {
  console.log(`Article clicked`, event)
})

unsubscribe() // calling it will unsubscribe from the event

On Article Browser Clicked

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

Executes a callback when an article link is opened in a new browser tab, either directly or as a fallback when the article fails to load in the Article Viewer. 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: "articleBrowserClicked"
  payload: {
    url: string //The URL of the article opened in the browser
  }
}

Example

zE("messenger:on", "articleBrowserClicked", function (event) {
  console.log(`Article opened in browser`, event)
})

const unsubscribe = zE(
  "messenger:on",
  "articleBrowserClicked",
  function (event) {
    console.log(`Article opened in browser`, event)
  }
)

unsubscribe() // calling it will unsubscribe from the event

On Message Received

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

Executes a callback when a message is received in any 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: 'messageReceived'
  payload: {
    conversation: {
      id: string //The ID of the conversation
    },
    message: {
      id: string //The ID of the message
      receivedAt: number //Timestamp when the message was received
      role: string //Author role: business or user
      source: {
        type: string //Source type of the message
      }
    }
  }
}

Example

zE("messenger:on", "messageReceived", function (event) {
  console.log(
    `Message received in conversation ${event.payload.conversation.id}`,
    event
  )
})

const unsubscribe = zE("messenger:on", "messageReceived", function (event) {
  console.log(
    `Message received in conversation ${event.payload.conversation.id}`,
    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).`)
})