Javascript API - Control widget behavior, register for events
Loading the Insent Javascript provides an Insent object that exposes few methods, that allow host JS in the page to control the behavior of the Insent widget. The current version of the Insent JS provides the below methods.
To hide the Insent widget on any page
This method will hide the Insent widget completely
insent.widget(‘hide’)
To show the Insent widget on any page
This method will show the Insent widget and restore it to its most recent UI state.
insent.widget(‘show’)
By default, all widgets either show a greeting message or the widget icon on load. Based on user interaction, the state of the widget is stored and replicated across multiple pages on the site and on-page reloads.
To expand the Insent widget on any page
This method will expand and show the full widget.
insent.widget(‘expand’)
Note: If the previous widget state is minimized, then the widget will load and show the conversation related to that page. If the previous widget state was expanded, then the widget will show that state.
This method will minimize the widget and show only the widget icon.
Note: If the previous widget state is minimized, then the widget will load and show the conversation related to that page. If the previous widget state was expanded, then the widget will show that state.
This method will minimize the widget and show only the widget icon.
insent.widget(‘minimize’)
Show a Particular Conversation
This method will allow a specific conversation to be invoked on a page. You have to pass the 'conversationID' on pages where you would like to invoke a specific conversation. dimSetting is an optional parameter that enables you to invoke a conversation with a dimmed background.
window.insent.showConversation('conversationID', dimSetting)
Arguments
- conversationID - Parameter to trigger a specific conversation based on the conversationID.
- dimSetting - Flag to toggle the dim background effect around the chat widget.
- dimSetting must be a boolean value.
- true - dims the background around the widget, making the website visitor focus on the chat.
- false - does not apply the dimming effect.
A 'conversationID' param can be located in the conversation URL. A sample is presented below.
Identifying the conversationID from the conversation page
Example of showConversation
Snippet | Use Case |
window.insent.showConversation('conversationID', false) | Invokes a conversation without a dimmed background |
window.insent.showConversation('conversationID', true) | Invokes a conversation with a dimmed background |
Widget Events
Insent JS also offers a listener that is triggered when specific events occur. The structure of the listener is as below. Use event names listed below to listen to those specific events using the listener
insent.listener('<event_name>', callback)
Event Names
- onExpand - When the widget icon or a greeting message is clicked to expand the widget state
- onMinimize - When the close button in the widget is clicked during an expanded state in order to minimize the widget
- onShow - When the widget visibility is toggled to a show state
- onHide - When the widget visibility is toggled to a hide state
Note: These functions should be added only after the Insent script on any page
Sending additional visitor data to Insent
insentLoadLazy is an optional parameter, if set to true it will not call the getUser API and not show the widget, to show the widget user will have to call
insent.setVisitor(visitor_details)
Example of visitor_details
visitor_details = {firstName: 'John', lastName: 'Doe', email: 'jd@insent.ai'} insent.setVisitor(visitor_details)
visitor_details is optional if no visitor details exist.
The setVisitor should always come after the Javascript snippet you copied and pasted to Install Insent widget on your website
You are always welcome to get in touch with our support team at support@insent.ai for any further clarification.