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


To show the Insent widget on any page

This method will show the Insent widget and restore it to its most recent UI state. 


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. 


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.


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)


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

How to locate the conversationID

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 


Example of  visitor_details

visitor_details = {firstName: 'John', lastName: 'Doe', email: ''} 

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 for any further clarification.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us