Control the chat widget with JavaScript

The chat widget gives your page a small JavaScript API at window.Helpdesk. Use it to open chat from your own buttons, react when the chat opens, tell the widget about page changes, switch language or remove the widget completely.

Before you start

• Who can do this: a developer or anyone who edits your site's code.
• Plan: all plans.
• What you need: the chat snippet installed on the page.
• Time: a few minutes per change.

Step by step

1. Make sure the snippet from Settings > Chat widget > Install is on the page.
2. Add this small helper once. It calls the widget if it has loaded, and otherwise queues the call for the loader to replay:

function hd(method, ...args) {
  const h = window.Helpdesk;
  if (h && typeof h[method] === 'function') h[method](...args);
  else (window.Helpdesk = h || { _q: [] })._q.push([method, ...args]);
}

3. Call the method you need, for example on a "Contact us" link:

document.querySelector('#contact-us').addEventListener('click', (e) => {
  e.preventDefault();
  hd('open');
});

4. Test the page in a private window.

What happens next

Methods run as soon as the widget is ready. Calls queued in Helpdesk._q before that are replayed in order when the loader starts.

Available methods

Method	What it does
open()	Opens the chat, loading the window first if needed
close()	Hides the chat
toggle()	Opens or hides the chat
identify({ email, name, externalId, phone, hash })	Tells the widget who the visitor is. See Identify logged-in shoppers
page()	Reports a page change in single-page apps
cart({ items, subtotalCents, currency, … })	Sends the visitor's cart to Hushdesk
setLocale('fr')	Switches the widget language
on(event, callback)	Listens for ready, open, close, unread or message; returns an unsubscribe function
track(name, props)	Passes a named event to your message listeners only
destroy()	Removes the button, the chat window, every listener and window.Helpdesk

Tips

• Add a "Chat with us" link in your footer or contact page that calls open(), so shoppers find chat where they already look. The corner button stays too; set its position and size under Customise the chat button.
• Use on('unread', ({ count }) => …) to show an unread badge on your own button.
• destroy() is useful when a visitor opts out of chat in your privacy settings. Reload the page to bring the widget back.

Troubleshooting

"Helpdesk.open is not a function"

Your code ran before the loader, which uses defer. Use the hd helper, which queues the call until the widget is ready.

open() does nothing

Check that the page is an allowed site. On other sites, the chat window shows This chat is not available on this site. See Choose which sites can show chat.

Events fire twice

Your listener was added twice, for example on each route change. Keep the function on() returns and call it to remove the old listener.