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 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.

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', isEnabled<boolean>);

The messaging 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 messaging Web Widget know that it is unable to use any of these storage options.

Currently, disabling cookies will result in the messaging Web Widget being hidden from the end user and all values in local and session storage being deleted.

Parameters

• isEnabled: Boolean. If false, the messaging Web Widget will be hidden from view and all stored data will be deleted.

Example

zE("messenger:set", "cookies", false)