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. Shown to your team in the inbox. |
user_hash | Identity verification signature. See Chat Identity Verification. |
attributes | Up to 50 extra details shown to your team, as simple values (text, numbers or true/false), for example { plan: "Business", company: "Northwind" } |
alignment | "left" or "right", overriding the Position setting |
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". Overrides Share visitors across subdomains of in Messenger settings. |
Commands
| Command | What it does |
|---|---|
HelpGuidesChat('boot', settings) | Starts the messenger with the boot settings above. The install snippet does this for you. Call it again after shutdown to show the messenger to the next visitor. |
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. The messenger checks for page changes every five seconds, so single-page apps work without it. |
HelpGuidesChat('update', { user_id, email, name, user_hash }) | A different user signed in. The messenger restarts as that user. |
HelpGuidesChat('shutdown') | Forgets the visitor on this browser and removes the messenger from the page. Call this when a user signs out. |
HelpGuidesChat('getVisitorId') | Returns the visitor's ID, or null if the messenger hasn't started yet |
When a user signs out
Call shutdown as part of your sign-out. Until you do, the browser stays signed in to the chat as that user. The next person on the same browser would continue their session and see their conversations, and actions set to Only for signed-in customers would still look up the previous user's account. See Chat Actions.
shutdown also removes the messenger from the page. If the page stays open after sign-out and should still show the chat, boot it again for an anonymous visitor:
HelpGuidesChat('shutdown');
HelpGuidesChat('boot', { app_id: "YOUR_APP_ID" });Chat links
To send a customer straight into the chat, for example from an email or a text, add ?chat=1 to any page address on your site. No code is needed:
https://www.example.com/?chat=1&chat_name=Jameschat=1opens the messenger when the page loads, on the home screen or the conversation they were last in.chat_nameis optional and only read together withchat=1. It names the visitor, so your team sees "James" in the inbox and the greeting says "Hi James". It's used only when your site doesn't pass anameat boot. Up to 80 characters. It isn't callednamebecause WordPress treats?name=as a post address and shows a page-not-found error.- Both are removed from the address bar once read, so reloading the page or sharing the address doesn't repeat them. Other parameters, such as
utm_source, are kept.
A chat link only labels the visitor. It doesn't sign them in, and it can't reach anyone's past conversations. To recognize signed-in customers, use Chat Identity Verification.
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.