> ## Documentation Index
>
> Fetch the complete documentation index at: https://chat.sh/help/llms.txt
> Use this file to discover all available pages before exploring further.

# Messenger JavaScript API

> Open, close, hide, and listen to the messenger from your own code.

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](https://chat.sh/help/articles/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.

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

## Hide it on some pages

```js
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:

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