{"Status":true,"Message":"","Response":{"post":{"postuid":"ac186448-2081-4b6d-b06b-78a23048fa86","tenantuid":"d8b744fc-2e70-4089-bb80-dd1d08f6c7b2","projectuid":"fc6490ac-7527-4f49-b06e-46f701280e85","title":"Chat Messenger JavaScript API","slug":"article/chat-messenger-javascript-api","html":"\u003Cp\u003EThe messenger\u0027s 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 \u003Ccode\u003EHelpGuidesChat(command, value)\u003C/code\u003E. Commands sent before the messenger finishes loading are queued and run in order.\u003C/p\u003E\u003Ch2 id=\u0022boot_settings\u0022\u003EBoot settings\u003C/h2\u003E\u003Cp\u003EThese go in \u003Ccode\u003Ewindow.HelpGuidesChatSettings\u003C/code\u003E, or are passed to \u003Ccode\u003EHelpGuidesChat(\u0027boot\u0027, settings)\u003C/code\u003E.\u003C/p\u003E\u003Ctable border=\u00221\u0022 style=\u0022border-collapse: collapse; width: 100%;\u0022\u003E\u003Cthead\u003E\u003Ctr\u003E\u003Cth\u003ESetting\u003C/th\u003E\u003Cth\u003EDescription\u003C/th\u003E\u003C/tr\u003E\u003C/thead\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Eapp_id\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003ERequired. Your messenger\u0027s app ID, from the install snippet.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Euser_id\u003C/code\u003E, \u003Ccode\u003Eemail\u003C/code\u003E, \u003Ccode\u003Ename\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EThe signed-in user. Shown to your team in the inbox.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Euser_hash\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EIdentity verification signature. See \u003Ca href=\u0022/article/chat-identity-verification\u0022\u003EChat Identity Verification\u003C/a\u003E.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Eattributes\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EUp to 50 extra details shown to your team, as simple values (text, numbers or true/false), for example \u003Ccode\u003E{ plan: \u0022Business\u0022, company: \u0022Northwind\u0022 }\u003C/code\u003E\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Ealignment\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003E\u003Ccode\u003E\u0022left\u0022\u003C/code\u003E or \u003Ccode\u003E\u0022right\u0022\u003C/code\u003E, overriding the \u003Cb\u003EPosition\u003C/b\u003E setting\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Ehide_default_launcher\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003E\u003Ccode\u003Etrue\u003C/code\u003E hides the chat button, so you can open the chat from your own button\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Ehide_notifications\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003E\u003Ccode\u003Etrue\u003C/code\u003E stops reply previews appearing above the button\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003Ecookie_domain\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EShare one visitor across subdomains, for example \u003Ccode\u003E\u0022example.com\u0022\u003C/code\u003E. Overrides \u003Cb\u003EShare visitors across subdomains of\u003C/b\u003E in Messenger settings.\u003C/td\u003E\u003C/tr\u003E\u003C/table\u003E\u003Ch2 id=\u0022commands\u0022\u003ECommands\u003C/h2\u003E\u003Ctable border=\u00221\u0022 style=\u0022border-collapse: collapse; width: 100%;\u0022\u003E\u003Cthead\u003E\u003Ctr\u003E\u003Cth\u003ECommand\u003C/th\u003E\u003Cth\u003EWhat it does\u003C/th\u003E\u003C/tr\u003E\u003C/thead\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027boot\u0027, settings)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EStarts the messenger with the boot settings above. The install snippet does this for you. Call it again after \u003Ccode\u003Eshutdown\u003C/code\u003E to show the messenger to the next visitor.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027show\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EOpens the messenger\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027hide\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003ECloses it\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027toggle\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EOpens or closes it\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027showMessages\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EOpens the visitor\u0027s list of conversations\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027showNewMessage\u0027, \u0027Hi!\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EOpens a new conversation with text pre-filled\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027showConversation\u0027, id)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EOpens a specific conversation\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027update\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003ETells the messenger the page changed. The messenger checks for page changes every five seconds, so single-page apps work without it.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027update\u0027, { user_id, email, name, user_hash })\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EA different user signed in. The messenger restarts as that user.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027shutdown\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EForgets the visitor on this browser and removes the messenger from the page. Call this when a user signs out.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027getVisitorId\u0027)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EReturns the visitor\u0027s ID, or \u003Ccode\u003Enull\u003C/code\u003E if the messenger hasn\u0027t started yet\u003C/td\u003E\u003C/tr\u003E\u003C/table\u003E\u003Ch2 id=\u0022when_a_user_signs_out\u0022\u003EWhen a user signs out\u003C/h2\u003E\u003Cp\u003ECall \u003Ccode\u003Eshutdown\u003C/code\u003E 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 \u003Cb\u003EOnly for signed-in customers\u003C/b\u003E would still look up the previous user\u0027s account. See \u003Ca href=\u0022/article/chat-actions\u0022\u003EChat Actions\u003C/a\u003E.\u003C/p\u003E\u003Cp\u003E\u003Ccode\u003Eshutdown\u003C/code\u003E 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:\u003C/p\u003E\u003Ccode\u003EHelpGuidesChat(\u0027shutdown\u0027);\nHelpGuidesChat(\u0027boot\u0027, { app_id: \u0022YOUR_APP_ID\u0022 });\u003C/code\u003E\u003Ch2 id=\u0022chat_links\u0022\u003EChat links\u003C/h2\u003E\u003Cp\u003ETo send a customer straight into the chat, for example from an email or a text, add \u003Ccode\u003E?chat=1\u003C/code\u003E to any page address on your site. No code is needed:\u003C/p\u003E\u003Ccode\u003Ehttps://www.example.com/?chat=1\u0026chat_name=James\u003C/code\u003E\u003Cul\u003E\u003Cli\u003E\u003Ccode\u003Echat=1\u003C/code\u003E opens the messenger when the page loads, on the home screen or the conversation they were last in.\u003C/li\u003E\u003Cli\u003E\u003Ccode\u003Echat_name\u003C/code\u003E is optional and only read together with \u003Ccode\u003Echat=1\u003C/code\u003E. It names the visitor, so your team sees \u0022James\u0022 in the inbox and the greeting says \u0022Hi James\u0022. It\u0027s used only when your site doesn\u0027t pass a \u003Ccode\u003Ename\u003C/code\u003E at boot. Up to 80 characters. It isn\u0027t called \u003Ccode\u003Ename\u003C/code\u003E because WordPress treats \u003Ccode\u003E?name=\u003C/code\u003E as a post address and shows a page-not-found error.\u003C/li\u003E\u003Cli\u003EBoth are removed from the address bar once read, so reloading the page or sharing the address doesn\u0027t repeat them. Other parameters, such as \u003Ccode\u003Eutm_source\u003C/code\u003E, are kept.\u003C/li\u003E\u003C/ul\u003E\u003Ccite class=\u0022recommended\u0022\u003E\u003Cspan class=\u0022title\u0022\u003EThe name isn\u0027t verified\u003C/span\u003E\u003Cp\u003EA chat link only labels the visitor. It doesn\u0027t sign them in, and it can\u0027t reach anyone\u0027s past conversations. To recognize signed-in customers, use \u003Ca href=\u0022/article/chat-identity-verification\u0022\u003EChat Identity Verification\u003C/a\u003E.\u003C/p\u003E\u003C/cite\u003E\u003Ch2 id=\u0022events\u0022\u003EEvents\u003C/h2\u003E\u003Ctable border=\u00221\u0022 style=\u0022border-collapse: collapse; width: 100%;\u0022\u003E\u003Cthead\u003E\u003Ctr\u003E\u003Cth\u003ECommand\u003C/th\u003E\u003Cth\u003ECalled when\u003C/th\u003E\u003C/tr\u003E\u003C/thead\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027onUnreadCountChange\u0027, function (count) { \u2026 })\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EThe number of unread replies changes. It\u0027s also called immediately with the current count.\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027onShow\u0027, fn)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EThe messenger opens\u003C/td\u003E\u003C/tr\u003E\u003Ctr\u003E\u003Ctd\u003E\u003Ccode\u003EHelpGuidesChat(\u0027onHide\u0027, fn)\u003C/code\u003E\u003C/td\u003E\u003Ctd\u003EThe messenger closes\u003C/td\u003E\u003C/tr\u003E\u003C/table\u003E\u003Ch2 id=\u0022examples\u0022\u003EExamples\u003C/h2\u003E\u003Cp\u003EA \u0022Chat with us\u0022 link that opens a pre-filled conversation:\u003C/p\u003E\u003Ccode\u003E\u003Ca href=\u0022#\u0022 onclick=\u0022HelpGuidesChat(\u0027showNewMessage\u0027, \u0027I have a question about my order\u0027); return false;\u0022\u003EChat with us\u003C/a\u003E\u003C/code\u003E\u003Cp\u003EYour own button with an unread count, with the default chat button hidden:\u003C/p\u003E\u003Ccode\u003Ewindow.HelpGuidesChatSettings = { app_id: \u0022YOUR_APP_ID\u0022, hide_default_launcher: true };\n// \u2026install snippet\u2026\nHelpGuidesChat(\u0027onUnreadCountChange\u0027, function (n) {\n  document.getElementById(\u0027chat-badge\u0027).textContent = n || \u0027\u0027;\n});\ndocument.getElementById(\u0027chat-button\u0027).onclick = function () { HelpGuidesChat(\u0027toggle\u0027); };\u003C/code\u003E\u003Cp\u003ESee \u003Ca href=\u0022/article/installing-the-chat-messenger-on-your-website\u0022\u003EInstalling the Chat Messenger on Your Website\u003C/a\u003E for the full install snippet.\u003C/p\u003E","publish_status":0,"post_type":"Article","author":{},"featured_image_updating":false,"meta_description":"Learn how to use the HelpGuidesChat JavaScript API to control chat, manage users, react to events, and customize your website\u2019s messenger integration easily.","display_toc":true,"has_workingcopy":false,"allow_indexing":true,"sort_order":16,"total_views":5,"date_published":"2026-09-26T16:45:29.357","date_updated":"2026-10-07T16:19:21.04","date_created":"2026-09-26T16:31:20.483"}}}