Integrate and Customize the Business Messaging (BM) Widget Using JavaScript APIs

Integrating Custom Actions in the Business Messaging Widget

This guide explains how to integrate and customize the Business Messaging (BM) widget within your web application. It covers setting up an IM channel, creating a global ZOHOIM object, and customising the widget’s layout and appearance.

JavaScript API Overview

JavaScript APIs for business messaging are client-side APIs designed to manage contact information, events, and API calls related to the BM widget. You can use these APIs to pre-fill data, retrieve contact details, and customize the widget’s appearance.

Using the JavaScript API

To use the necessary JavaScript API, you need to copy and paste the relevant code into the source code of your website within the <script> tags. Before executing the BM script, ensure that you have set the respective JavaScript API details in the code.

BM Widget Setup

To display the BM widget:

Create a Channel in IM.
Obtain the channel's Embedded Code Script.
Inject the Embedded Code Script into your webpage.
Initialize the ZOHOIM object before injecting the script:

window.ZOHOIM = window.ZOHOIM || {};

Set the necessary properties for rendering the BM widget within the window.ZOHOIM variable.

BM widget script sample

<script type="text/javascript" nonce="{place_your_nonce_value_here}" src="https://im.zoho.com/api/v1/public/channel/435798000000140015/widget" defer> var _d=document;_d.prefilledMessage=</script>

Set API

Define the following properties in window.ZOHOIM before rendering the widget:

Prop Name	Type	Description
widgetContainerId	string	Element ID in which ZBM will be rendered
widgetLayout	object	Describes the options required for customising the ZBM Widget layout
widgetLayout.showWidget	boolean	Whether to show the BM widget
widgetLayout.needWidgetBubble	boolean	Whether to render the BM widget with the Bubble Icon or not
widgetLayout.needCloseIcon	boolean	In the ZBM Widget header, whether the close Icon is required or not
widgetProps.sessionVariableValues	array	To set a session variable for GC bot Refer here
**customStyles	string	Describes the options required for customizing the styles of ZBM Widget
customStyles.mode	string	In which mode ZBM needs to be rendered. expected values : "light", "dark"
customStyles.theme	string	Describes the theme of ZBM widget. expected value : Hex Color Code
customStyles.actionTheme	string	Describes the action theme of ZBM widget. expected value : Hex Color Code
customStyles.wallpaper	object	Describes the options required for ZBM widget wallpaper.
customStyles.wallpaper.src	object	Describes the options required for ZBM widget wallpaper in different modes.
customStyles.wallpaper.src.light	string	Wallpaper needs to be rendered in light mode. expected value : Image URL
customStyles.wallpaper.src.dark	string	Wallpaper needs to be rendered in dark mode. expected value : Image URL
poweredByTag	object	Describes the options required for rendering the powered by tag in ZBM Widget footer.
poweredByTag.isChecked	boolean	Whether to display the powered by tag or not in the ZBM footer
customHandlers	object	Describes the options required for the functionality of the ZBM Widget
customHandlers.closeButtonHandler	function	Executes when the close icon is clicked
customHandlers.backButtonHandler	function	Executes when the back icon is clicked
customHandlers.openArticle	function	Executes when the article message is clicked Refer here

Trigger API

The following methods allow communication between the BM widget and your application.

Method Name	Description	Arguments	Return Value
triggerEvent	triggers a particular event that executes all the methods which are subscribed to the triggered event	ZOHOIM.triggerEvent('eventName',...args)	NIL
subscribeToEvent	A method can subscribe to a particular event	ZOHOIM.subscribeToEvent( 'eventName', method)	NIL

Below is a sample code snippet illustrating how to render the BM widget.

<html>
<head>
<title>Page Title</title>
<script> 
window.ZOHOIM = window.ZOHOIM || {};
window.ZOHOIM.widgetContainerId = "test";
window.ZOHOIM.widgetLayout = { needWidgetWithBubble : false, needCloseIcon : true};
window.ZOHOIM.customStyles = '{ "mode": "light", "theme": "#71198c","actionTheme":"#1a7063", "wallpaper": {"src": {"light":"https://fastly.picsum.photos/id/703/536/354.jpg?hmac=1NZ7SzrTrnA-1O2S18kJC-IFIOZyYeHt8x98Iqdd5kM"}},"poweredByTag": { "isChecked": false } }';
customCloseButtonHandler = ()=>{alert('clicked the close button');}
customBackButtonHandler = ()=>{
  if(a===1){
    a=0;
    window.ZOHOIM.triggerEvent('showCloseIcon',true);
  }else{
    a=1;
    window.ZOHOIM.triggerEvent('showCloseIcon',false);
  }
}
window.ZOHOIM.customHandlers = {
 closeButtonHandler : customCloseButtonHandler,
 backButtonHandler : customBackButtonHandler
}
</script>
 
<script type="text/javascript" nonce="{place_your_nonce_value_here}" src="https://implus.localzoho.com/api/v1/public/channel/c572beb392335194a3f8e528fb092408/widget" defer> var _d=document;_d.prefilledMessage= </script>
</head>
 
<body>
<div id="test" style="height: 500px; width: 400px; border: 1px solid black;"></div>
</body>
</html>

Get Contact Info API (Web)

You can provide custom contact information using widgetProps.

Prop Name	Type	Description
ContactInfo	object	Describes the details of the contact

Sample

window.ZOHOIM.widgetProps = { 'contactInfo': {'name':'Manoj','phone': '+91203354', 'email': 'abc@gmail.com'}};

For Android, refer to this link: Setting the Contact Info for the Business Messaging SDK (Android)

For iOS, refer to this link: Setting the Contact Info for the Business Messaging SDK (iOS)

Authenticated Cases API

We provide the following methods to handle authenticated flows with Business Messaging.

Method to set Csrfcookie:

window.ZOHOIM.setCsrfParamName(csrfParamName);
window.ZOHOIM.setCsrfToken(csrfToken);

Method to set OAuth (JWT case):

window.ZOHOIM.setAuthtoken(token);

Method to set Domain:

window.ZOHOIM.setCustomDomainUrl(DomainURL);

Method to add ZohoAccountId to BM:

window.ZOHOIM.setZaid(zaid);

Pre-Render Action API:

You can execute actions before rendering the widget.

window.ZOHOIM.beforeRenderCallback= () => {
//todo
}

BM Widget Control Changes

We've introduced a set of public methods that allow end users to control the Business Messaging (BM) widget directly from the page. These methods enable dynamic interaction with the widget interface.

Supported Events

Event Name	Description
openWidget	Opens the BM widget
closeWidget	Closes the BM widget
toggleWidget	Toggles the widget between open and closed states
showBubble	Displays the widget's bubble icon
hideBubble	Hides the widget's bubble icon

Sample Implementation

The following code snippet is only a sample to demonstrate how you can use the new widget control methods.

<script>
window.ZOHOIM = window.ZOHOIM || {};
function closeWidget() {
const { triggerEvent } = window.ZOHOIM;
triggerEvent('closeWidget');
}
function openWidget() {
const { triggerEvent } = window.ZOHOIM;
triggerEvent('openWidget');
}
function toggleWidget() {
const { triggerEvent } = window.ZOHOIM;
triggerEvent('toggleWidget');
}
</script>
<button type="button" onclick="openWidget()">Open</button>
<button type="button" onclick="closeWidget()">Close</button>
<button type="button" onclick="toggleWidget()">Toggle</button>