Integrating Custom Actions in the Business Messaging Widget

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

JavaScript

<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
`**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

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.

JavaScript

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

Language Support and Fallback Behavior

You can configure the languages that you want to display in the BM widget using widgetProps.languages.

JavaScript

<script type='text/javascript'>window.ZOHOIM=window.ZOHOIM||function(a,b){ZOHOIM[a]=b;};window.ZOHOIM.prefilledMessage="";</script>
<script>
window.ZOHOIM = window.ZOHOIM || {};
window.ZOHOIM.locale = 'en_US'; // locale is mandatory
window.ZOHOIM.widgetProps = { languages: ['en_US','fr_FR','ta_IN','ar_EG']}; // locale should be present in the langauges list
</script>

Replace the languages in ['en_US','fr_FR','ta_IN','ar_EG'] with the required language codes in the same format.

The languages configured in widgetProps.languages are displayed in the language dropdown. However, adding a language to this property does not mean that the language is supported by the BM widget.

The language selected in the dropdown, the language used to display the BM widget UI, and the language used by the GC bot depend on different language configurations.

Language dropdown: Determined by the languages configured in widgetProps.languages.

BM widget UI: Depends on whether an IM translation is available for the selected language.

Languages supported in IM

Code	Language	Code	Language
`en_US`	English - US	`nb_NO`	Norwegian Bokmål
`ar_EG`	Arabic - Egypt	`nl_NL`	Dutch
`da_DK`	Danish	`or_IN`	Odia
`de_DE`	German	`pl_PL`	Polish
`es_ES`	Spanish	`pt_BR`	Portuguese - Brazil
`fr_FR`	French	`ro_RO`	Romanian
`hi_IN`	Hindi	`ru_RU`	Russian
`in_ID`	Indonesian	`sv_SE`	Swedish
`is_IS`	Icelandic	`ta_IN`	Tamil
`it_IT`	Italian	`te_IN`	Telugu
`iw_IL`	Hebrew	`th_TH`	Thai
`ja_JP`	Japanese	`tr_TR`	Turkish
`kk_KZ`	Kazakh	`vi_VN`	Vietnamese
`ko_KR`	Korean	`zh_CN`	Chinese - Simplified
		`zh_TW`	Chinese - Traditional

GC bot response: The language used by the GC bot depends on whether the selected language is supported by IM.

Refer to the GC supported language documentation to view the complete list of languages supported by the GC bot.

What happens if an unsupported IM language is configured?

You can include a language in widgetProps.languages even when a corresponding IM translation is not available. The language will still appear in the BM language dropdown and can be selected.

However, when the language is selected:

The selected language continues to be displayed as the current language in the dropdown.
Since the corresponding IM translation is unavailable, the BM widget UI falls back to the default language, English (en_US).
The GC bot's response language depends separately on whether the selected language is supported by IM.

Important: A language appearing in the BM language dropdown only indicates that it has been configured in widgetProps.languages. It does not indicate that the language is supported by IM or the GC bot.

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

JavaScript

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:

JavaScript

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

Method to set OAuth (JWT case):

JavaScript

 window.ZOHOIM.setAuthtoken(token);

Method to set Domain:

JavaScript

window.ZOHOIM.setCustomDomainUrl(DomainURL);

Method to add ZohoAccountId to BM:

JavaScript

window.ZOHOIM.setZaid(zaid);

Pre-Render Action API:

You can execute actions before rendering the widget.

JavaScript

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.

JavaScript

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

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

Integrating Custom Actions in the Business Messaging Widget

JavaScript API Overview

Using the JavaScript API

BM Widget Setup

BM Widget Script Sample

Set API

Trigger API

Language Support and Fallback Behavior

What happens if an unsupported IM language is configured?

Get Contact Info API (Web)

Authenticated Cases API

Method to set Csrfcookie:

Method to set OAuth (JWT case):

Method to set Domain:

Method to add ZohoAccountId to BM:

Pre-Render Action API:

BM Widget Control Changes

Supported Events

Sample Implementation