Controlling the widget from your own code

The widget exposes a small API on window.HelpShelf once it's loaded. window.helpshelf is an alias for the same object.

Methods

window.HelpShelf.open()            // open the panel
window.HelpShelf.close()           // close the panel
window.HelpShelf.toggle()          // toggle it
window.HelpShelf.search('refunds') // open the panel and run a search
window.HelpShelf.identify({ /* … */ })  // attach the logged-in user

identify() is covered in Identifying logged-in users.

Wiring your own help links

The most common use is replacing your existing "Need help?" links so they open the agent instead of navigating away:

<button onclick="window.HelpShelf.open()">Need help?</button>

Or send the visitor straight to an answer from a contextual link:

<a href="#" onclick="window.HelpShelf.search('how do I cancel'); return false;">
  Cancel my subscription
</a>

This works well beside form fields that confuse people — an inline "What's this?" that opens the exact answer beats a link to a docs page.

Calling before the widget loads

The script is loaded with async, so it may not be ready when your own code runs. identify() calls made early are queued and replayed automatically once the widget initialises.

The other methods aren't queued. If you're calling them from code that might run first, guard the call:

if (window.HelpShelf?.open) {
  window.HelpShelf.open()
}

Suppressing announcement auto-show

The API also carries a suppressAnnouncementAutoShow flag, letting you stop announcements from popping up on their own so you can choose the moment yourself.

Availability

The API is defined while the widget is mounted and removed when it unmounts. Always feature-detect rather than assuming it exists — on pages where the widget is disabled by a behavior setting, it won't be there at all.