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=James

chat=1 opens the messenger when the page loads, on the home screen or the conversation they were last in.
chat_name is optional and only read together with chat=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 a name at boot. Up to 80 characters. It isn't called name because 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.

The name isn't verified

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 us

Your 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.