- <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>
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.
Access your files securely from anywhere
Zoho CRM Training Programs
Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.
Zoho DataPrep Personalized Demo
If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.
- Zoho Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Writer?
Create. Review. Publish.
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.
New to Zoho Survey?
Zoho Sheet Resources
Zoho Forms Resources
New to Zoho Sign?
Zoho Sign Resources
Sign, Paperless!
New to Zoho TeamInbox?
Zoho TeamInbox Resources
New to Zoho ZeptoMail?
Design. Discuss. Deliver.
New to Zoho Workerly?
New to Zoho Recruit?
New to Zoho CRM?
New to Zoho Projects?
New to Zoho Sprints?
New to Zoho Assist?
New to Bigin?
Related Articles
Working with the Business Messaging SDK for iOS
You can handle your customer questions instantly from a dedicated Business Messaging channel facilitated by Zoho Desk's IM Module. This feature allows businesses to promote the latest trends, track their sales, and much more. The Business Messaging ...How to display the Business Messaging on your iOS app?
Displaying Business Messaging The following keys are essential to call the methods for displaying the conversation AI in your app. • OrgId • AppId • Domain The values of these keys appear under the Instant Messaging section on the setup page in Zoho ...Guided Conversations in Business Messaging
What is Guided Conversations? Guided Conversations (GC) is a powerful conversation builder platform that allows you to create structured, automated chat flows. With a variety of ready-to-use blocks and seamless integration capabilities, GC helps ...Adding a Business Messaging widget to your website
You can integrate Zoho Desk's native Business Messaging widget seamlessly across webpages and apps, customizing it to align with your brand's style. This allows seamless hand-offs between bots and agents and automation to facilitate personalized and ...How to customize the Business Messaging SDK Widget UI?
Customizing the theme Predefined themes The SDK UI has two predefined themes: light and black. The following methods help you apply these themes. ZDTHEMETYPE.LIGHT ZDTHEMETYPE.DARK Methods for applying the light (Default) theme: Swift ...
New to Zoho LandingPage?
Zoho LandingPage Resources