MessageBird’s Omnichannel Widget Javascript API allows you to customize the design, behaviour, and visibility of the Omnichannel Widget displayed on your website.

You can configure parts of the Omnichannel Widget directly in your Omnichannel Widget Settings in Inbox.

Getting started

The Omnichannel Widget Javascript API can be accessed through:

To initialize the Omnichannel Widget , you need to first embed your unique Omnichannel Widget installation snippet in either the header of your website (for all pages) or on the header of each page you wish to display the Omnichannel Widget.

You can find your installation snippet in your Omnichannel Widget Settings in Inbox.

Here is an example of the installation snippet:

API Reference

.init(widgetId: string): Promise

Will load and initialize the widget, you can either pass the widgetId to the init function as a param or set the widgetId to MessagebirdChatWidgetSettings.widgetId. If these are different values it will prioritize the argument passed in over the one set on the settings object. This can be called before the widget has fully loaded.

.toggleChat()

Opens/closes the widget main screen (excluding the icon)

.hide()

Hides the whole widget (including the icon). This can be called before the widget has fully loaded.

.show()

Shows the whole widget (including the icon)

.element

Returns a DOM element of the widget

.getVisitorId()

Returns a Promise containing the livechat visitor ID of the user of the widget. Please note that this can only be called once the livechat has been loaded onto the page. If its a first time user who has never interacted with the widget before it will only return a value when the user interacted / opens the widget.

.setAttributes()

Takes an object with the keys and values you would like to have on your visitors contact profile in inbox. The values must only be primitive values, ie a string, number or a boolean.

These values will only be attached to the visitor when the visitor sends a message from the livechat widget. It will also only attach the values to current visitor in the livechat.

window.MessageBirdChatWidget.setAttributes({
    email: "hello@test.com",
    phone: "+31 123 456 789",
    premiumUser: true,
    itemsInCart: 2
  })

.identify(uid: string, attributes?: Record<string, string | boolean | number>): Promise

Takes an unique identifier as an argument. It will then log in the widget user with the identifier passed as an its user returning a promise and resolving when complete.

window.MessageBirdChatWidget.identify('123-456-789');

identify can also take a second argument of attributes which is the exact same as the setAttributes methods.

window.MessageBirdChatWidget.identify('123-456-789', {
    email: "hello@test.com",
    phone: "+31 123 456 789",
    premiumUser: true,
    itemsInCart: 2
  })

.logout(): Promise

Logout will reset the widget, clearing all locally stored data and creates a fresh new anonymous visitor. the method will return a Promise and resolve when its complete.

This is useful if your using the identify feature and you want to make sure the user in widget is logged out when the user on your site it.

window.MessageBirdChatWidget.logout()

.shutdown(): Promise

Like logout, calling this method will reset the widget, clearing all locally stored data and creating a fresh new anonymous visitor. This method will also hide / remove the widget from the page.

window.MessageBirdChatWidget.logout()

startConversation(text: string)

startConversation will open the widget in the chat view and send a message from the visitor to the widget. This would be useful if you want to start certain flows programmatically for example via a button on your page.

window.MessageBirdChatWidget.startConversation('hello there')

setLanguage(language: string)

setLanguage will force the widget to change to the language passed in as an argument. The widget expects the languages in the ISO 639-1 Code format. It will respect the rules set up in the settings page, for example, if the language has been disabled the Widget will not update to that language.

window.MessageBirdChatWidget.setLanguage('nl')

.on(event, callback)

Pass a callback function to a set of preset events. This can be called before the widget has fully loaded.

event 'ready'

This will be called once the widget has loaded. Nothing is passed to the callback.

window.MessageBirdChatWidget.on('ready', () => {
    // do something here
})

event 'visitorCreated'

This will return the visitorID of the user. If its a first time user who has never interacted with the widget before it will only return a value when the user interacted / opens the widget.

window.MessageBirdChatWidget.on('visitorCreated', (id) => {
    // do something with id here
})

event 'toggle'

This will fire each time the widget is opened or closed, the callback will provide the state of the widget ie, if the widget is closed and the user clicks to open the widget the argument via the callback will be true.

window.MessageBirdChatWidget.on('toggle', (isOpen) => {
    // isOpen === true -> customer opened the widget
    // isOpen === false -> customer closed the widget
})