- <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
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'}};
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:
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
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 ...Add an embeddable Business Messaging chat bubble to your website
You can handle your customer questions instantly from a dedicated Business Messaging channel facilitated by Zoho Desk. This feature also allows businesses to communicate the latest trends, track their sales, and more. The Business Messaging user ...Working With Custom Actions Gallery
Zoho Desk offers numerous functionalities to automate, customize, and simplify your customer support process. It allows you to create webhooks and write custom functions to automate your repetitive support workflows, reduce the manual ...FAQs: Custom Actions Gallery
What is Custom Actions Gallery? Custom actions gallery includes a set of custom actions that help you automate key tasks, like assigning tickets, adding/removing tags, adding followers/comments, sending email replies, replying and notifying via ...Session Variables in Business Messaging
A session variable is a temporary piece of information that captures user-specific details, such as name, email, or phone number, while they’re using the chat or flow in your website. It helps the Business Messaging widget remember who the user is ...
New to Zoho LandingPage?
Zoho LandingPage Resources