Widget JavaScript API
Open and close the chat from your own code, and show an unread count on your own help button.
On a page with the widget, window.SupportWidget controls the chat. You can call its methods before the widget has loaded. The support-widget:ready event fires on window when it is ready.
Methods
| Method | What it does |
|---|---|
open() | Opens the chat. |
close() | Closes the chat. |
toggle() | Opens the chat if it is closed, and closes it if it is open. |
identify({ token }) | Shows the signed-in customer's conversations. See Identified chat. |
anonymous() | Tells the widget nobody is signed in. Only used with pending identity, below. |
reset() | Forgets this browser's chat. Call it when the customer signs out. |
Use your own button
To open the chat from your own help button and hide the widget's button, set launcher to "hidden" before the widget loads:
<script>
window.SupportWidgetSettings = { launcher: "hidden" };
</script>
<button onclick="SupportWidget.open()">Help</button>
Unread count
SupportWidget.unread is the number of team replies the customer has not read. To keep a badge up to date, use onUnreadChange. It calls your function now and on every change, and returns a function that stops it.
const stop = SupportWidget.onUnreadChange((count) => {
helpButton.classList.toggle("has-unread", count > 0);
});
The same count fires as the support-widget:unread event on window, in event.detail.count. While the chat is closed, the count refreshes every 30 seconds.
Pending identity
If your app only knows who is signed in after the page loads, add data-identity="pending" to the widget's script tag. The widget then waits, with no button and no requests, until you call one of these:
if (user) SupportWidget.identify({ token }); // token from your server
else SupportWidget.anonymous();
This keeps one customer's chat from showing briefly to another person on a shared computer.