Chat Messenger JavaScript API
The messenger's JavaScript API lets your website open and close the chat, start a conversation with pre-filled text, react to unread messages, and update who the visitor is. Every command goes through HelpGuidesChat(command, value). Commands sent before the messenger finishes loading are queued and run in order.
Boot settings
These go in window.HelpGuidesChatSettings, or are passed to HelpGuidesChat('boot', settings).
| Setting | Description |
|---|---|
app_id | Required. Your messenger's app ID, from the install snippet. |
user_id, email, name | The signed-in user |
user_hash | Identity verification signature. See Chat Identity Verification. |
attributes | Up to 50 extra details shown to your team, for example { plan: "Business" } |
alignment | "left" or "right", overriding your settings |
hide_default_launcher | true hides the chat button, so you can open the chat from your own button |
hide_notifications | true stops reply previews appearing above the button |
cookie_domain | Share one visitor across subdomains, for example "example.com" |
Commands
| Command | What it does |
|---|---|
HelpGuidesChat('show') | Opens the messenger |
HelpGuidesChat('hide') | Closes it |
HelpGuidesChat('toggle') | Opens or closes it |
HelpGuidesChat('showMessages') | Opens the visitor's list of conversations |
HelpGuidesChat('showNewMessage', 'Hi!') | Opens a new conversation with text pre-filled |
HelpGuidesChat('showConversation', id) | Opens a specific conversation |
HelpGuidesChat('update') | Tells the messenger the page changed. Single-page apps are detected automatically, so this is rarely needed. |
HelpGuidesChat('update', { user_id, email, name, user_hash }) | A different user signed in |
HelpGuidesChat('shutdown') | Forgets the visitor on this browser. Call this when a user signs out. |
HelpGuidesChat('getVisitorId') | Returns the visitor's ID |
Events
| Command | Called when |
|---|---|
HelpGuidesChat('onUnreadCountChange', function (count) { … }) | The number of unread replies changes. It's also called immediately with the current count. |
HelpGuidesChat('onShow', fn) | The messenger opens |
HelpGuidesChat('onHide', fn) | The messenger closes |
Examples
A "Chat with us" link that opens a pre-filled conversation:
Chat with usYour own button with an unread count, with the default chat button hidden:
window.HelpGuidesChatSettings = { app_id: "YOUR_APP_ID", hide_default_launcher: true };
// …install snippet…
HelpGuidesChat('onUnreadCountChange', function (n) {
document.getElementById('chat-badge').textContent = n || '';
});
document.getElementById('chat-button').onclick = function () { HelpGuidesChat('toggle'); };See Installing the Chat Messenger on Your Website for the full install snippet.