# Helpmate

> Customer support for startups: a live chat widget, a shared inbox, a hosted help
> center, and outbound messages. This file documents the JavaScript SDK you embed on
> your site — installing the widget, identifying signed-in users, sending the contact
> properties that outbound audiences and the directory are built on, and the help
> center that answers customers before they ask.

## Quickstart

Paste the loader before `</body>` in a layout that renders on every page:

```html
<script type="text/javascript" data-navigate-once>
    window.helpmateSettings = {
        locale: 'en',
        position: 'right',
        type: 'expanded_bubble',
        launcherTitle: 'Contact Us',
        hideMessageBubble: false,
        containerId: 'hm',
    };

    (function (d, t) {
        var BASE_URL = 'https://api.helpmate.so';
        var g = d.createElement(t), s = d.getElementsByTagName(t)[0];
        g.src = BASE_URL + '/dist/sdk.js?v=18';
        g.defer = true;
        g.async = true;
        s.parentNode.insertBefore(g, s);
        g.onload = function () {
            window.helpmateSDK.run({
                websiteToken: 'YOUR_WEBSITE_TOKEN',
                baseUrl: BASE_URL,
            });
        };
    })(document, 'script');
</script>
```

Then identify signed-in users, so a reply still reaches them after they close the tab:

```html
<script type="text/javascript">
    window.addEventListener('helpmate:ready', function () {
        window.$helpmate.setUser('USER_ID', {
            email: 'jane@acme.com',
            name: 'Jane Doe',
            avatar_url: 'https://acme.com/avatars/jane.png',
        });
    });
</script>
```

Four rules behind most broken installs:

1. `window.$helpmate` exists only after the `helpmate:ready` event. Calling `setUser`
   before it is a silent no-op.
2. At least one of `email`, `name`, `avatar_url` must be present, or
   `setUser` throws before it sends.
3. Call `$helpmate.reset()` on logout, or the next person at that browser inherits the
   previous visitor's conversation.
4. Sign the identifier server-side (see Identity verification). Unverified, the same
   person on a second device starts a second contact.

## Docs

- [Installation](https://helpmate.so/docs/installation.md): Add the loader script, confirm it booted, and configure the launcher.
- [Live chat](https://helpmate.so/docs/live-chat.md): The conversation surface: starting a chat, attachments, conversation context, and the email fallback that only works if you sent an address.
- [Identify users](https://helpmate.so/docs/identify.md): setUser(), every field it accepts, the fields it silently ignores, and when to call it.
- [Contact properties](https://helpmate.so/docs/properties.md): custom_attributes: the supported keys, the value formats, and what happens to a key nobody defined.
- [Companies](https://helpmate.so/docs/companies.md): There is no company payload: company_name is an identify field, everything else is a property.
- [Identity verification](https://helpmate.so/docs/identity-verification.md): HMAC-SHA256 of the identifier with the workspace secret; required to attach an identify call to a contact that already exists.
- [Help center](https://helpmate.so/docs/help-center.md): Article and collection URLs, putting it on your own domain, locales, and the article card inside the widget.
- [JavaScript API](https://helpmate.so/docs/javascript-api.md): Full reference for window.$helpmate — methods, window events, and when each is safe to call.

## Full documentation

- [https://helpmate.so/llms-full.txt](https://helpmate.so/llms-full.txt): every page above, concatenated, in markdown