Close mobile menu

API Reference

OverviewSMSVoice CallingVoice MessagingConversationsOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRReportingBalanceLookupContactsGroups

Omnichannel Widget Javascript API

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:

var MessageBirdChatWidgetSettings = {
widgetId: 'YOUR-WIDGET-ID',
initializeOnLoad: true,
!function(){"use strict";if(Boolean(document.getElementById("live-chat-widget-script")))console.error("MessageBirdChatWidget: Snippet loaded twice on page");else{var e,t;window.MessageBirdChatWidget={},window.MessageBirdChatWidget.queue=[];for(var i=["init","setConfig","toggleChat","identify","hide","on","shutdown"],n=function(){var e=i[d];window.MessageBirdChatWidget[e]=function(){for(var t=arguments.length,i=new Array(t),n=0;n<t;n++)i[n]=arguments[n];window.MessageBirdChatWidget.queue.push([[e,i]])}},d=0;d<i.length;d++)n();var a=(null===(e=window)||void 0===e||null===(t=e.MessageBirdChatWidgetSettings)||void 0===t?void 0:t.widgetId)||"",o=function(){var e,t=document.createElement("script");t.type="text/javascript",t.src="".concat(a),t.async=!0,"live-chat-widget-script";var i=document.getElementsByTagName("script")[0];null==i||null===(e=i.parentNode)||void 0===e||e.insertBefore(t,i)};"complete"===document.readyState?o():window.attachEvent?window.attachEvent("onload",o):window.addEventListener("load",o,!1)}}();

API Reference


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 prioritze the argument passed in over the one set on the settings object. This can be called before the widget has fully loaded


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


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


Shows the whole widget (including the icon)


Returns a DOM element of the widget


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.


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.

email: "",
phone: "+31 123 456 789",
premiumUser: true,
itemsInCart: 2

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


We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings