Widget JavaScript API
Open, close and control the Bot Widget from your own code, for example from a branded "Chat with us" button on your site.
On this page
- Open the chat from your own button
- Use one button to open and close
- Change your button's label to match
- Where the chat opens
- Ask a question on the visitor's behalf
- Tell the bot who the visitor is
- API reference
- Common questions
- My button does nothing
- Can I open the chat automatically when the page loads?
- Can I put the chat inside my page instead of a floating panel?
- Can I change how the widget looks from JavaScript?
Once the Bot Widget is on your page, you can control it from your own JavaScript. The most common use is a branded button of your own ("Chat with us", "Talk to support") that opens the chat panel, but you can also send a question on the visitor's behalf or tell the bot who the visitor is.
Everything here lives on one global object, window.HelpJet.widget. There is nothing extra to install: if the Bot Widget embed code is on the page, the API is there too.
Open the chat from your own button
Add your button anywhere on the page, styled however you like:
1<button type="button" id="open-support-chat" class="your-button-class">2 Chat with us3</button>
Then wire it up with a few lines of JavaScript. Put this after your HelpJet embed code:
1document.getElementById('open-support-chat').addEventListener('click', function () {2 var helpjet = window.HelpJet && window.HelpJet.widget;3 if (helpjet) {4 helpjet.open();5 }6});
Clicking the button opens the chat panel and puts the cursor in the message box, exactly as if the visitor had clicked the chat bubble.
The if (helpjet) check matters. The widget loads in the background after your page, so on a slow connection a visitor can click your button before it's ready. Without the check, that click throws an error; with it, the click does nothing and the next one works.
Use one button to open and close
If you want the same button to close the chat when it's already open, call toggle() instead of open():
1document.getElementById('open-support-chat').addEventListener('click', function () {2 var helpjet = window.HelpJet && window.HelpJet.widget;3 if (helpjet) {4 helpjet.toggle();5 }6});
Change your button's label to match
isOpen tells you whether the panel is open right now, so you can update your button after each click:
1var button = document.getElementById('open-support-chat');23button.addEventListener('click', function () {4 var helpjet = window.HelpJet && window.HelpJet.widget;5 if (!helpjet) return;6 helpjet.toggle();7 button.textContent = helpjet.isOpen ? 'Close chat' : 'Chat with us';8});
The widget doesn't fire events, so if the visitor closes the chat with the bubble or the panel's own controls, your label won't update until the next click. Read isOpen whenever you need the current state rather than tracking it yourself.
Where the chat opens
The panel always opens in the same corner as the chat bubble (bottom right or bottom left, depending on your widget's position setting), not next to your button. Your button is another way to open the same chat, not a different chat window.
Ask a question on the visitor's behalf
sendMessageWithText() sends a message as if the visitor had typed it, and the bot replies as normal. Pair it with open() so the visitor sees the answer arrive. This works well for contextual help buttons, such as "Ask about this plan" on a pricing page:
1document.getElementById('ask-about-pro').addEventListener('click', function () {2 var helpjet = window.HelpJet && window.HelpJet.widget;3 if (!helpjet) return;4 helpjet.open();5 helpjet.sendMessageWithText('What do I get on the Pro plan?');6});
The bot's reply counts as an interaction, the same as any other answer. If the bot is still writing a reply when you call it, the message is ignored, so check isLoading first if your button can be clicked repeatedly.
Tell the bot who the visitor is
If your visitors are logged in to your site, you can attach their details to their conversations. They then show up against the conversation in your bot's Activity page, so you can see who asked what.
The simplest way is to set window.HelpJet.visitor before your embed code runs:
1window.HelpJet = window.HelpJet || {};2window.HelpJet.visitor = {3 email: 'jane@example.com',4 name: 'Jane Smith',5};
Put that in a <script> tag above the HelpJet embed code, filled in by your site with the logged-in visitor's details. If the visitor logs in or out after the page has loaded, call identify() instead:
1// After login2window.HelpJet.widget.identify({ email: 'jane@example.com', name: 'Jane Smith' });34// After logout5window.HelpJet.widget.identify(null);
You can pass any of email, name and id (your own user ID). When you pass both a name and an email, the conversation shows them as Jane Smith <jane@example.com>; otherwise it uses the email, then the name, then the ID. Each value is trimmed to 200 characters.
API reference
All methods and properties live on window.HelpJet.widget.
Method or property | What it does |
|---|---|
| Opens the chat panel. Does nothing if it's already open. |
| Closes the chat panel. Does nothing if it's already closed. |
| Opens the panel if it's closed, closes it if it's open. |
|
|
|
|
| Sends |
| Clears the current conversation and starts a fresh one, as the panel's Start new chat menu option does. |
| Attaches |
| The widget's resolved settings, read-only. Useful for debugging; don't change it. |
Two settings live directly on window.HelpJet and must be set before your embed code runs:
Setting | What it does |
|---|---|
| The visitor's |
| Set to |
Common questions
My button does nothing
Work through these in order:
- The widget hasn't loaded yet. Wait a moment after the page loads and try again. If it never works, open your browser's developer console and type
window.HelpJet.widget. If that'sundefined, the widget isn't loading at all; see the troubleshooting steps in Deploying Your Bot. - A display rule hides the widget on this page. When Widget Display Rules hide the widget, the API is still there but
open()has nothing to open. Add a rule that shows the widget on the pages where your button appears. - The bot is Inactive. An Inactive bot doesn't load a widget, so there's no API either. Set the bot to Active under General settings.
- Your page hides the widget with CSS. Remove any rule that hides
helpjet-widget; see the warning above.
Can I open the chat automatically when the page loads?
Yes, but wait until the widget is ready. This checks every half second for up to ten seconds:
1var attempts = 0;2var timer = setInterval(function () {3 var helpjet = window.HelpJet && window.HelpJet.widget;4 if (helpjet) {5 clearInterval(timer);6 helpjet.open();7 } else if (++attempts >= 20) {8 clearInterval(timer);9 }10}, 500);
Use this sparingly. A chat that opens on every page load gets in the way, especially on mobile.
Can I put the chat inside my page instead of a floating panel?
Not with the Bot Widget. Use Page Embed instead, which places the chat inline wherever you put the code. See Embedding & Sharing Your Bot.
Can I change how the widget looks from JavaScript?
No. The widget's look comes from your bot's Appearance page and the Bot Widget's Customization card, and page styles can't reach inside it. See Customizing the Chat Widget.
Was this article helpful?