Messenger JavaScript API

Once the tag is on the page, window.chatSh controls the messenger. Every call is safe before the messenger has loaded. Calls wait and run once it has. If you call open(), close(), or toggle() several times before then, only the last one counts.

Methods

Method	What it does
chatSh.open()	Opens the window. Also undoes hide().
chatSh.close()	Closes the window.
chatSh.toggle()	Opens it if it is closed, closes it if it is open.
chatSh.hide()	Takes the messenger off the page: the window closes and the corner button goes.
chatSh.show()	Puts back what hide() took away.
chatSh.isOpen()	true while the window is open.
chatSh.isHidden()	true after hide(), until show() or open().
chatSh.identify({...})	Names the signed-in person. See Identify signed-in users.
chatSh.reset()	For sign-out: forgets the person and starts a fresh conversation.
chatSh.on(event, fn)	Calls fn on "open", "close", or "ready". Returns a function that stops it.

Events

chatSh.on() takes one of three events:

• "open": the window opened.
• "close": the window closed.
• "ready": the messenger has loaded. If it already has, fn runs at once.

const stop = chatSh.on("open", () => analytics.track("Messenger opened"));
// later
stop();

Hide it on some pages

chatSh.hide(); // on pages where it should not show
chatSh.show(); // to bring it back

In a single-page app, call hide() when the user goes to a page without the messenger, and show() when they leave it.

Name the user before the tag loads

If you know who is signed in when the page renders, set it before the tag:

<script>
  window.chatShSettings = {
    user: { userId: "u_123", email: "ada@acme.com", name: "Ada", userHash: "…" }
  };
</script>
<script src="https://chat.sh/widget.js" data-site="YOUR-SITE-ID" async></script>

This does the same as calling chatSh.identify() with those fields.

What is not available

There are no events for new messages and no unread count in the API. The corner button shows its own unread badge.