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