# Userport JavaScript SDK

The complete integration reference: the widget, live chat, identifying users,
contact properties, companies, identity verification, and the help center.
Everything below is generated from the code that serves it — the field tables, the
snippets and the limits are read from the endpoints themselves, not transcribed.

Contents:

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

---

# Installation

Helpmate ships as one JavaScript loader. It creates the launcher, mounts the widget in an
iframe, and exposes `window.$helpmate` for everything else in these docs.

## 1. Add the loader

Paste this before the closing `</body>` tag, in a layout that renders on **every** page —
marketing pages included. One tag across the whole site means one visitor journey; splitting
it means the same person shows up twice.

```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.userport.io';
        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>
```

The `websiteToken` identifies your workspace. It is public by design — it appears in the page
source of every site running Helpmate — and it grants nothing except the ability to start a
conversation. The secret that *does* matter is the identity verification secret, which never
leaves your server (see Identity verification).

## 2. Confirm it booted

Load a page and check the console:

```javascript
window.$helpmate            // an object, not undefined
```

The widget dispatches `helpmate:ready` on `window` when it is safe to call. Everything you
do with the SDK belongs inside that listener — calling `setUser` before the event does
nothing at all, silently.

```javascript
window.addEventListener('helpmate:ready', function () {
    // window.$helpmate is live from here on
});
```

## 3. Configure the launcher

`window.helpmateSettings` is read once, at boot. Set it *before* the loader runs.

| Key | Values | What it does |
| --- | --- | --- |
| `locale` | "en", "fr", … | Widget language. |
| `useBrowserLanguage` | true \| false | Take the language from the browser instead of `locale`. |
| `position` | "right" \| "left" | Which side the launcher sits on. |
| `type` | "standard" \| "expanded_bubble" | Launcher shape. `expanded_bubble` shows `launcherTitle` beside the icon. |
| `launcherTitle` | string | Label on the expanded launcher. |
| `hideMessageBubble` | true \| false | Boot with the launcher hidden — pair with your own trigger calling `showNewMessage()`. |
| `darkMode` | "light" \| "dark" \| "auto" | Colour scheme at boot. |
| `widgetStyle` | "standard" \| "flat" | Widget chrome. |
| `baseDomain` | string | Cookie domain, e.g. ".acme.com", when the widget spans subdomains. |
| `containerId` | string | Id of the element the widget mounts into. |

Most of these have a matching control in **Settings → Website widget**, and where both are
set **the dashboard wins** — the snippet is pasted into a site once, while the dashboard is
where somebody changes the design later without a deploy. A workspace that has never touched
those settings keeps whatever the snippet asked for, so treat this object as your defaults
rather than as overrides. See Live chat for the full list on each side.

## Single-page apps

The loader mounts once and survives client-side navigation — you do not need to re-run it on
route changes. Two things do need handling:

- **Sign-in.** Call `setUser` when the session resolves, not only on first paint.
- **Sign-out.** Call `window.$helpmate?.reset()`. Without it the next person at that browser
  inherits the previous visitor's conversation history.

## React and Next.js

### Load the SDK from the root layout

Next.js: put this in app/layout.tsx or pages/_document.tsx. Plain React: the same tag in index.html works. Keep it unconditional so marketing and product pages share one visitor journey.

```tsx
// app/layout.tsx — Next.js App Router
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en">
            <body>
                {children}
                <Script
                    id="helpmate"
                    src="https://api.userport.io/dist/sdk.js?v=18"
                    strategy="afterInteractive"
                    onLoad={() => {
                        window.helpmateSDK.run({
                            websiteToken: 'YOUR_WEBSITE_TOKEN',
                            baseUrl: 'https://api.userport.io',
                        });
                    }}
                />
            </body>
        </html>
    );
}
```

### Identify from a client component

Runs on the client only. The listener covers the case where the session resolves before the widget boots; the direct call covers the reverse.

```tsx
'use client';

import { useEffect } from 'react';

export function HelpmateIdentity({ user }: { user: { id: string; email: string; name: string } | null }) {
    useEffect(() => {
        if (!user) {
            window.$helpmate?.reset();
            return;
        }

        const identify = () => {
            window.$helpmate?.setUser(user.id, {
                email: user.email,
                name: user.name,
                company_name: user.company?.name,
                custom_attributes: {
                    signed_up_at: user.createdAt,   // ISO 8601
                    plan: user.plan,
                    company_id: user.company?.id,
                    company_website: user.company?.website,
                    monthly_spend: user.company?.monthlySpend,
                },
            });
        };

        // Whichever happens second wins: the widget may boot before or after
        // the session resolves.
        window.addEventListener('helpmate:ready', identify);
        if (window.$helpmate) identify();

        return () => window.removeEventListener('helpmate:ready', identify);
    }, [user]);

    return null;
}
```

### Reset on sign-out

Call this in the same handler that clears your session.

```tsx
window.$helpmate?.reset();
```

## Next steps

- Identify your signed-in users so conversations attach to a real person — and so an answer
  still reaches them after they close the tab.
- Send contact properties so you can target outbound messages and filter the directory.
- Read Live chat for what happens to a message after the visitor sends it.

---

# Live chat

Live chat is not a separate product to install. The loader from Installation is the whole of
it — the launcher, the composer, the thread list and the agent replies are all the same
widget. This page is about the behaviour you cannot see from the snippet: what happens to a
message after the visitor sends it.

## Starting a conversation

Three things open one, and they are equivalent as far as the inbox is concerned:

- The visitor clicks the launcher and picks **Send us a message** on the home screen.
- Your own UI calls `showNewMessage()`, which skips the home screen and opens the composer.
- Your help center's `/chat` page is the chat on its own; on your site, a link carrying
  `?hm_chat=1` opens it on arrival — see Linking straight to the chat.
- An outbound message reaches them and they reply to it.

For your own trigger, hide the launcher at boot rather than hiding it with CSS — a launcher
removed with `display: none` still loads and still animates:

```javascript
window.helpmateSettings = { hideMessageBubble: true };

document.querySelector('#support').addEventListener('click', function () {
    window.$helpmate?.showNewMessage();
});
```

## Linking straight to the chat

A link can open the chat on its own, with no code on the page that sends it. Your help center
has a page that is nothing but the chat:

```
https://{slug}.userport.io/chat
https://{slug}.userport.io/chat?hm_message=A%20question%20about%20the%20team%20plan
```

This is the answer to "put a Contact support button in our mobile app". The app opens the
link in a browser or a web view; the visitor sees the chat opening — in your colours, on a
blank page, with nothing else to load first — and lands in the conversation. Nothing is
installed on their side, and the same link works from an email footer, a menu item or a
status page. Closing the chat offers to reopen it or to browse the help center.

On a page of your own that carries the widget, add `?hm_chat=1` to the URL instead:

```
https://your-app.com/pricing?hm_chat=1&hm_message=A%20question%20about%20the%20team%20plan
```

| Parameter | Value | What it does |
| --- | --- | --- |
| `hm_chat` | `1` | Opens the widget on the visitor's conversation — their most recent one, or a new one if they have never written. Also accepts `true`, `yes`, `on`, `open`, `chat`. On the help center this redirects to `/chat`. |
| `hm_chat` | `home` | Opens the widget on its home screen instead — articles and search first, for a link that means "here is help" rather than "talk to us". |
| `hm_message` | `any text` | Prefills the composer, up to 1000 characters. Never sent on the visitor's behalf, and never over the top of something they have already typed. |
| `#hm-chat` | `fragment` | Same as `?hm_chat=1`, for a link that cannot carry a query string. `#hm-chat-home` matches `hm_chat=home`. |

The parameter is removed from the address bar the moment it is read, so a visitor who
bookmarks or shares the page afterwards does not reopen the chat on every visit — and your
page analytics do not gain a second copy of the URL. It stays armed: clicking the same link
again opens the chat again, including after they close it. On the help center,
`/?hm_chat=1` — the form of the link before `/chat` existed — redirects to `/chat` with
everything else on the URL intact.

**Send who they are with it.** A link is the only thing the widget knows about a visitor
arriving this way, and an app already knows who its user is:

```
https://{slug}.userport.io/chat?uid=8421&identifier_hash=…&email=jane@acme.com&name=Jane%20Doe&platform=ios&app_version=2.27.0
```

| Parameter | Value | What it does |
| --- | --- | --- |
| `uid` | `your user id` | Your own primary key for the person, the same string `setUser()` takes as its identifier. `user_id` is accepted as a synonym. |
| `identifier_hash` | `HMAC-SHA256` | Signs the identifier with this workspace's secret, computed on your server. Without it the claim is unverified: the visitor cannot be attached to the contact they already are, so a second device — or a web view whose cookies did not survive the last launch — starts a fresh conversation with none of their history. See Identity verification. |
| `email` | `an address` | Where a reply goes when it is not read in the widget within five minutes. A contact with no address never gets that fallback. |
| `name` | `a display name` | What the agent sees in the inbox. Also what makes an account with no email address identifiable at all: an identify call carrying none of email / name / avatar_url is rejected before it is sent. |
| `anything else` | `a value` | A contact property, written through the same typed path `custom_attributes` takes — so `?platform=ios&app_version=2.27.0` lands in the Directory and in outbound audiences. Ad and analytics click ids (`utm_*`, `fbclid`, …) are dropped, and properties travel only on a link that names somebody: an unknown key becomes a permanent property definition the first time it is seen, and a crawler appending junk to an article URL must not be able to create one. |

Without `identifier_hash` that is an unverified claim, and the visitor is treated as a new
anonymous person — a fresh conversation each time, and none of their history. With it, they
are the contact they already were, and the thread they started on their laptop last week is
the one that opens. In a mobile web view, where the browser's cookies rarely survive to the
next launch, this is the difference between continuous support and starting over. See
Identity verification.

**Build the whole URL on your server, not in the app.** The hash has to be computed there
anyway, and the property KEYS are permanent — the first time a workspace sends an unknown one
a definition is created for it, and a definition with values in it cannot be retyped. A
shipped mobile binary is the worst possible place for a key to be spelled, so let the app send
values to an endpoint of your own and let that endpoint name them and redirect.

The contact form at `/contact` reads exactly the same parameters, for callers who would rather
send someone to a form than to a conversation.

On a page that runs its own JavaScript, `$helpmate.openChat()` does the same thing without a
navigation — that is the right call for a button in your own UI.

## Anyone can chat; not everyone can be replied to

A visitor does not have to be identified to start a conversation. They are recognised by the
`cw_conversation` cookie, and that is enough for a back-and-forth while they have the tab
open.

It stops being enough the moment they leave, which is the part worth designing for:

- **An operator reply lands in the widget.** If the visitor is still on the site, they see it
  immediately and nothing is emailed — an actively chatting visitor is never double-notified.
- **A reply the visitor has not read within five minutes is emailed to them instead.** This is
  what makes live chat work asynchronously: the visitor closes the tab, the answer follows
  them.
- **With no email address on the contact, that fallback does not happen at all.** The reply
  sits in a widget nobody has open. The visitor may never come back to it.

So the practical reason to call `setUser` on authenticated pages is not the agent's
convenience — it is that a signed-in visitor who wanders off still gets their answer. For
anonymous visitors the widget asks for an address itself, and a reply that was pending when
they give one is picked up and sent.

Two cases are deliberately excluded from the email fallback: a contact who has unsubscribed,
and one whose address has hard-bounced. Neither is retried.

## Who is online

The widget shows the agents behind the workspace and whether anyone is available. An agent
counts as online while they have the dashboard open, and for ten minutes after.

Nobody being online does not close the composer. Messages sent to an empty inbox are queued
like any other, and answered when somebody arrives — which is again the email fallback doing
the work, and again only if you have an address.

## Attachments

The composer accepts files alongside — or instead of — text.

| Limit | Value | Notes |
| --- | --- | --- |
| File types | `jpg`, `png`, `svg`, `gif`, `pdf`, `movie`, `qt`, `mp4`, `mov` | Anything else is rejected before it is stored. |
| Maximum size | 8 MB per file | Applied to each attachment, not to the message. |
| Per message | Text, attachments, or both | A message with no text is valid when it carries at least one file. |

A rejected file fails visibly in the composer rather than silently, so a visitor who tries to
send a `.docx` finds out immediately.

## Giving the conversation context

Two different things, and picking the wrong one is the usual mistake:

- **Contact properties** describe the *person* and persist across every conversation they
  ever have. They are what outbound audiences and directory filters read. See Contact
  properties.
- **Conversation attributes** describe *this* conversation and nothing else. They are shown
  to the agent handling it and are invisible to targeting.

The order somebody is asking about belongs in the second:

```javascript
window.$helpmate.setConversationCustomAttributes({
    order_id: 'A-10432',
    started_from: window.location.pathname,
    plan_at_time_of_asking: 'trial',
});
```

Setting `started_from` is worth doing on every install. An agent opening a conversation
otherwise has no idea which page the question came from, and "where were you when this
happened" is the first thing they would have to ask.

Labels are the other half of this — `setLabel('billing')` tags the conversation for the
agent's own filters and views.

## More than one conversation

A visitor can have several threads open; the widget lists them and remembers which is which.
Anything you call from the SDK — a label, a conversation attribute — applies to the thread
they are currently in, defaulting to the most recently active one. There is no SDK call that
selects a thread, by design: the visitor chooses, not the host page.

## Appearance

The launcher is configured in two places, and they do not have equal standing.

**Settings → Website widget**, which is where the design is managed:

| Setting | Values | What it does |
| --- | --- | --- |
| Style | `standard`, `flat`, `expanded` | Launcher shape. `expanded` shows the label beside the icon. |
| Position | `right`, `left` | Which side of the viewport the launcher sits on. |
| Label | text, up to 120 characters | Shown beside the launcher when the expanded style is on. |
| Label frequency | `once_per_session`, `always` | How often the label reappears for the same visitor. |
| Icon animations | `horizontal_funnel`, `vertical_funnel`, `smile`, `winking_smile` | Attention animations. With more than one enabled the SDK picks a random one every 45 seconds. |
| Brand colour | hex colour, default `#1F93FF` | Drawn on the launcher, the widget header and outbound email alike. |

**`window.helpmateSettings`**, read once at boot from the host page:

| Key | Values | What it does |
| --- | --- | --- |
| `locale` | "en", "fr", … | Widget language. |
| `useBrowserLanguage` | true \| false | Take the language from the browser instead of `locale`. |
| `position` | "right" \| "left" | Which side the launcher sits on. |
| `type` | "standard" \| "expanded_bubble" | Launcher shape. `expanded_bubble` shows `launcherTitle` beside the icon. |
| `launcherTitle` | string | Label on the expanded launcher. |
| `hideMessageBubble` | true \| false | Boot with the launcher hidden — pair with your own trigger calling `showNewMessage()`. |
| `darkMode` | "light" \| "dark" \| "auto" | Colour scheme at boot. |
| `widgetStyle` | "standard" \| "flat" | Widget chrome. |
| `baseDomain` | string | Cookie domain, e.g. ".acme.com", when the widget spans subdomains. |
| `containerId` | string | Id of the element the widget mounts into. |

**The dashboard wins where both are set.** The snippet is pasted into a site once and then
forgotten; the dashboard is where somebody changes the colour a year later without
redeploying. A workspace that has never touched those settings sends nothing, and the values
in `helpmateSettings` stand — which is what makes them useful as defaults rather than as
overrides.

What the dashboard governs is exactly the launcher's shape, side, label and colour. Every
other boot setting is yours alone and is never overridden — `locale`, `darkMode`,
`hideMessageBubble`, `baseDomain` and `containerId` included. So a host page can still boot
the widget in the visitor's language and follow your own dark-mode switch, whatever the
dashboard says about the launcher.

## Signing out

```javascript
window.$helpmate?.reset();
```

Call it in the same handler that clears your own session. Without it, the conversation cookie
survives the logout and the next person to use that browser opens the widget onto somebody
else's conversation history. On shared machines this is the one bug in this document with a
real privacy cost.

## The endpoints underneath

The widget talks to a `/v1/widget/*` API, and it is visible in any browser's network tab. It
is the bundle's private transport, not a public interface: it is versioned with the widget,
authenticated with the conversation cookie, and changed without notice. Drive live chat
through `window.$helpmate` and nothing else.

---

# Identify users

Until you identify someone they are an anonymous visitor: a browser cookie, a conversation,
nothing else. `setUser` turns that into a contact — recognised across devices, reachable by
email, and targetable by outbound messages.

```javascript
window.addEventListener('helpmate:ready', function () {
    window.$helpmate.setUser('USER_ID', {
        email: 'jane@acme.com',
        name: 'Jane Doe',
    });
});
```

Call it on **every authenticated page load**, not just after login. The SDK hashes the payload
and skips the network request when nothing has changed, so the repeat calls are free.

## Fields

The first argument is your own user id. Everything else goes in the object.

| Field | Type | Required | Stored as | Notes |
| --- | --- | --- | --- | --- |
| `identifier` | string \| number | yes | `contacts.external_id` | Your own primary key for the user. Passed as the first argument, not inside the object. Recorded on the visitor's own contact even without a hash — but only a verified call can attach to the contact that already carries this id, so an unverified call finding the id already taken records nothing. |
| `identifier_hash` | string | no | `verified, not stored` | HMAC-SHA256 of the identifier, computed on your server with this workspace's secret. Without it an identify call cannot attach to an existing contact — so the same person on a second device starts a second contact instead of finding their history. |
| `email` | string | no | `contacts.email` | Reply-to address for the conversation. Attaching to an *existing* contact with this address requires a verified call; without verification the address is set on the current anonymous contact instead. |
| `name` | string | no | `contacts.name` | Display name shown in the agent inbox. |
| `avatar_url` | string (URL) | no | `contacts.avatar_url` | Absolute URL to the user's picture. Truncated at 255 characters. |
| `company_name` | string | no | `contacts.company_name + companies.name` | Display name of the account this person belongs to. Truncated at 255 characters. On its own this is enough to create a provisional company in the Directory; send company_id as a property to make it authoritative. |
| `segments` | string[] | no | `contact tags` | Tags to add to the contact. Additive — sending a shorter list never removes a tag. |
| `custom_attributes` | object | no | `contact properties (typed)` | Contact properties, as a flat map of slug => value. This is the only field the audience builder can target on, and the only place company details other than the name can travel. See the property reference. |

At least one of `email`, `name`, `avatar_url` must be present, or the SDK throws before it
sends anything. An id with no other detail is not enough to open a conversation with.

## Fields that are accepted and dropped

These are forwarded by the widget bundle but the API does not store them. If you are sending
any of them today, the value has never appeared anywhere.

| Field | What happens to it |
| --- | --- |
| `phone_number` | There is no phone column on a contact. Send it as a custom attribute if you want it visible and targetable. |
| `city` | Not stored. The contact's country is derived from the request IP instead. |
| `country_code` | Not stored — derived from the request IP. |
| `description` | Not stored. Agent-authored notes live on the contact instead. |
| `social_profiles` | Not stored. Send the handles you care about as custom attributes. |

Send them as `custom_attributes` instead — that is where anything targetable lives, and it is
also the only way they will show up on the contact's profile.

## Updating a property later

`setUser` is de-duplicated on a hash of the **identifier, email, name and avatar_url only**.
Change nothing but `custom_attributes` and the call never leaves the page.

To update properties after the first identify, use the dedicated method:

```javascript
window.$helpmate.setCustomAttributes({ plan: 'enterprise', seats: 12 });
```

## Verified vs unverified

Without an `identifier_hash`, an identify call is treated as *the visitor telling us about
themselves*. That is enough to record everything on their own anonymous contact — name, email,
user id, properties — which is why the widget works without any backend work at all.

It is deliberately **not** enough to **attach to a contact that already exists** with that
email or user id. Otherwise anyone could type a customer's address into the browser console and
be handed their conversation history. So an unverified call that names a user id somebody else
already holds records no id at all, rather than putting two people under one.

The practical cost of staying unverified: the same person on a second device, or after clearing
cookies, starts a **new** contact instead of finding their history. Signing the identifier
server-side is what joins them up — see Identity verification.

## One person, one contact

Two things decide whether the person in front of you is recognised, in this order:

1. **The `cw_conversation` cookie**, which is how an anonymous visitor is recognised at all. It
   is set for the exact host unless you set `baseDomain`, so `www.acme.com` and `app.acme.com`
   are two visitors until you do:

   ```javascript
   window.helpmateSettings = { baseDomain: '.acme.com' };
   ```

2. **A verified identify call**, for everything the cookie cannot survive — another browser,
   another device, a cleared cookie, a different domain entirely.

Without both, the same signed-in person accumulates one contact per browser, each carrying the
same email, and their conversation history is split across them. If you are seeing duplicates
in the Directory, this is why — start by checking that a real `identifier_hash` is arriving.

## Signing out

```javascript
window.$helpmate?.reset();
```

Clears the identity and the conversation cookie, and reloads the widget frame. Call it in the
same handler that clears your own session.

---

# Contact properties

Properties are what you target on. An outbound message audience ("everyone on the trial plan
who signed up more than 14 days ago"), a directory filter, a saved segment — all of them read
contact properties and nothing else.

They travel as `custom_attributes`, a **flat** map of key to value:

```html
<script type="text/javascript">
    window.addEventListener('helpmate:ready', function () {
        window.$helpmate.setUser('USER_ID', {
            email: 'jane@acme.com',
            name: 'Jane Doe',
            company_name: 'Acme Inc',
            custom_attributes: {
                // Person
                signed_up_at: '2024-03-11',
                role: 'admin',
                locale: 'en',

                // Company — everything except the name travels here
                company_id: 'acme-inc',
                company_website: 'https://acme.com',
                company_industry: 'SaaS',
                company_size: 120,
                company_created_at: '2021-06-02',
                plan: 'enterprise',
                monthly_spend: 490,
                is_paying: true,
            },
        });
    });
</script>
```

Nested objects are rejected, and so is anything past the 100th key in a single call. A value
may be an array of scalars — a multi-select, stored as the comma-separated string you then
target with `contains`; an empty one clears the property.

## Value formats

Each property has a type, fixed the first time the workspace sees the key. The type decides
which column the value is stored in, which is what makes `mrr > 100` and `signed_up_at` older
than 30 days expressible at all.

| Type | Accepted values | Example |
| --- | --- | --- |
| `string` | Any scalar — numbers and booleans are stringified. Trimmed, and truncated at 1024 characters. An array of scalars is joined with commas (["outreach","organize"] is stored as "outreach,organize") — that is how a multi-select is stored, and you target it with `contains`. An empty array clears the property. A nested array or an object is rejected. | `"SaaS"` |
| `number` | A JSON number or a numeric string. Stored with 6 decimal places. A non-numeric value is rejected with a 422 — it is a bug on your side, and storing it would leave an audience rule that matches nobody. | `490` |
| `boolean` | true / false. The strings "true", "false", "1", "0", "yes", "no", "on", "off" are accepted too. | `true` |
| `datetime` | ISO 8601 ("2024-03-11" or "2024-03-11T09:15:00Z"), any date string Carbon parses, or a Unix timestamp — milliseconds are detected and divided down, so Date.now() works. | `"2024-03-11T09:15:00Z"` |
| `list` | One of the options configured for the property in Settings. Behaves like a string otherwise — including a one-element array, which is unwrapped. It is a *single* select, so send one value: several are stored joined and then match no option. | `"enterprise"` |

A value that cannot be coerced to the property's type is **rejected with a 422** rather than
stored as a string. Sending `mrr: "lots"` is a bug on your side, and quietly keeping it would
leave an audience rule that matches nobody — far harder to find than an error.

Watch the `helpmate:error` window event during development; a rejected identify call surfaces
there with the API's message.

## Supported keys

These are predefined: their type is fixed, they have a proper name in the admin, and they are
grouped sensibly in the audience builder. Use them where they fit rather than inventing a
synonym — `subscription_tier` and `plan` are two properties as far as every filter is
concerned.

### Person

| Key | Name | Type | Group | Meaning |
| --- | --- | --- | --- | --- |
| `is_paying` | Paying customer | boolean | person | Whether the account currently pays you anything. |
| `last_order_at` | Last order | datetime | person | Most recent purchase. |
| `lifetime_value` | Lifetime value | number | person | Total revenue from this account to date. |
| `locale` | Locale | string | person | Preferred language. Also used to pick the outbound message translation. |
| `mrr` | MRR | number | person | Monthly recurring revenue for this account. |
| `onboarding_goals` | Onboarding goals | string | person | What this account said it wanted, comma-separated. |
| `role` | Role | string | person | The person's job role inside their organisation. |
| `sdk_installed_at` | Installed at | datetime | person | When this account first got the product running. |
| `seats` | Seats | number | person | Number of licensed users on the account. |
| `setup_completed_at` | Setup completed | datetime | person | When this account finished setting the product up. |
| `signed_up_at` | Signed up | datetime | person | When the account was created in your product. |
| `trial_ends_at` | Trial ends | datetime | person | When the free trial expires. |

### Company

Account-level attributes. See Companies for how these build a company record.

| Key | Name | Type | Group | Meaning |
| --- | --- | --- | --- | --- |
| `articles_count` | Articles | number | company | How much content this account has published. |
| `company_created_at` | Company created at | datetime | company | When the account was first created in your product. |
| `company_id` | Company ID | string | company | Your own identifier for the account this contact belongs to. |
| `company_industry` | Company industry | string | company | The account's industry or sector. |
| `company_size` | Company size | string | company | Size of the account's organisation. Usually a bucket ("51-100", "500+") rather than an exact count — use `employees_count` for the number. |
| `company_website` | Company website | string | company | The account's website. |
| `conversations_count` | Conversations | number | company | How many conversations this account has handled. |
| `linked_users` | Linked users | number | company | How many people from this account you have on file. |
| `monthly_spend` | Monthly spend | number | company | What the account pays you each month. |
| `plan` | Plan | list | company | Subscription tier. Options are managed in Settings. |
| `workspace_slug` | Workspace | string | company | The account's workspace in your product — what a link back into it is built from. |

## Keys you invent

Any key matching `[a-z0-9_]{1,64}` is accepted. The first time a workspace sends one, a
property definition is created for it, typed as a string, and it appears in **Settings →
Contact properties** where its name and type can be corrected.

Two consequences worth knowing before you ship:

- **A typo is permanent.** `plann` becomes a real property that clutters every field picker
  and matches nobody. Prefer the predefined keys, and check the spelling of your own.
- **A property that already has values cannot be re-typed.** Values live in the column the
  original type selected. If you sent `seats: "12"` into a string property, fixing it means
  archiving that property and starting a new key.

A workspace that has finished wiring things up can switch on **strict mode** in Settings →
Contact properties, after which an unknown key is rejected with a 422 instead of quietly
creating a definition.

## Reading them back

Properties show on the contact in the agent inbox and in the directory, and they can be
filtered and sorted on there. They are also the fields available in outbound message
personalisation.

---

# Companies

Helpmate keeps a company record for every account you send details about. It powers the
Companies tab of the directory, "everyone at this account" filters, and sorting a customer
list by monthly spend.

**There is no separate company object in the SDK.** You repeat the account's details on every
user who belongs to it, and the company record is derived from that. This is deliberate: it
means an installation that only ever wired up `setUser` gets companies for free, with no
payload change.

## The shape

`company_name` is a top-level identify field. Everything else — including the website — is a
`custom_attributes` key.

```javascript
window.$helpmate.setUser('user-42', {
    email: 'jane@acme.com',
    name: 'Jane Doe',
    company_name: 'Acme Inc',
    custom_attributes: {
        company_id: 'acme-inc',
        company_website: 'https://acme.com',
        company_industry: 'SaaS',
        company_size: 120,
        company_created_at: '2021-06-02',
        plan: 'enterprise',
        monthly_spend: 490,
    },
});
```

## What each key does

| Key | Lands on | Notes |
| --- | --- | --- |
| `company_name` | `companies.name` | Sent as a top-level identify field, not a property. Keys a provisional company on its own. |
| `company_id` | `companies.external_id` | Your own account id. Send it and the company row becomes authoritative — a provisional row keyed on the name is adopted rather than duplicated. |
| `company_website` | `companies.website` | Absolute URL, e.g. "https://acme.com". |
| `company_industry` | `companies.industry` |  |
| `company_size` | `companies.company_size` | Headcount, as a number. |
| `company_created_at` | `companies.company_created_at` | When the account was created in your product. |
| `monthly_spend` | `companies.monthly_spend` | What the account pays you each month, as a number. |
| `plan` | `companies.plan` | Subscription tier. Grouped with the company keys even without the prefix. |
| `linked_users` | `ignored` | Recomputed from the contacts pointing at the company. Sending it changes nothing — a host page cannot sort its own account to the top of the Directory. |

## Identified vs provisional companies

How the record is keyed depends on whether you send `company_id`.

- **With `company_id`** the record is *identified*. That id is your own account key, and it is
  authoritative: renaming the account in your product renames the company here, and does not
  create a second one.
- **With only `company_name`** the record is *provisional*, keyed on the lower-cased name. You
  get a populated Companies list while the id is still being wired up.

When an id finally arrives for an account previously known only by name, the existing record
is **adopted** — same row, same history, same member count. It is not duplicated. The reverse
works too: a user who sends only a name, at a company already known by id, joins the
identified record rather than opening a provisional one beside it.

Send `company_id` if your product has account ids. It is the difference between a company list
you can trust and one that drifts every time somebody renames their workspace.

## One company per person

A contact belongs to exactly one company. Sending a different `company_id` for an existing
contact moves them, and both companies' member counts are recalculated.

## What is ignored

`linked_users` is recomputed from the contacts pointing at the company and is ignored on the
way in — a host page cannot sort its own account to the top of somebody's directory.

---

# Identity verification

Anything the browser says about who it is, the browser can lie about. Without verification an
identify call may record whatever it likes on *its own* anonymous contact — name, email, user
id — but it cannot attach to a contact that already exists, because otherwise anyone could type
a customer's address into the console and be handed their conversation history.

Verification lifts that restriction. Your server proves it knows a secret that the browser
never sees.

That is not a small difference in practice: an unverified install starts a **new** contact
every time the same person arrives on a second device or with cleared cookies, and their
conversation history does not follow them.

## How it works

Compute an HMAC-SHA256 of the identifier using your workspace's identity verification secret,
and render the digest into the page next to the identifier. Helpmate recomputes it and
compares in constant time.

```
identifier_hash = HMAC_SHA256(identifier, workspace_secret)
```

The secret is per-workspace and is shown in **Settings → Installation**. Keep it in your
server environment — never in client-side code, never in a public repository, never in a
prompt handed to a third-party service.

## Compute the digest

### PHP / Laravel

Compute the digest wherever you render the page, and pass it through to the identify call. The secret stays on the server — never ship it to the browser.

```php
$identifier = (string) $user->id;
$identifierHash = hash_hmac('sha256', $identifier, env('HELPMATE_IDENTITY_SECRET'));
```

### Node.js

```javascript
import { createHmac } from 'node:crypto';

const identifier = String(user.id);
const identifierHash = createHmac('sha256', process.env.HELPMATE_IDENTITY_SECRET)
    .update(identifier)
    .digest('hex');
```

### Python

```python
import hashlib, hmac, os

identifier = str(user.id)
identifier_hash = hmac.new(
    os.environ["HELPMATE_IDENTITY_SECRET"].encode(),
    identifier.encode(),
    hashlib.sha256,
).hexdigest()
```

### Ruby

```ruby
identifier = user.id.to_s
identifier_hash = OpenSSL::HMAC.hexdigest('sha256', ENV['HELPMATE_IDENTITY_SECRET'], identifier)
```

### Pass it to the widget

The digest goes next to the identifier it signs. Send the same identifier you hashed — hashing the email and sending the user id verifies nothing.

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

## Rules

- **Hash the identifier you send.** Hashing the email and sending the user id verifies
  nothing; the two must be the same string.
- **The identifier must be stable.** Your primary key, not an email address that can change
  and not a session id that rotates.
- **Compute it server-side, every time.** Caching the digest in `localStorage` or handing it
  to the client to build defeats the entire mechanism.
- **Fail loudly when the secret is missing.** The usual way this ends up half-installed is code
  that computes the digest only when the environment variable is set, and quietly sends nothing
  when it is not. Everything keeps working, so nobody notices that no call is verified until a
  customer says their history vanished. Throw, log, or fail the build instead.

## Enforcement

Verification is optional by default: an unverified identify call still records what the
visitor says about themselves, so adding the feature does not break installations that have
not wired it up yet.

Once every page that identifies is sending a valid hash, turn on **enforcement** in Settings →
Installation. From then on an unverified identify call is rejected outright with a 403 rather
than being downgraded — which is what you want in production, and what makes the guarantee
above absolute rather than best-effort.

Enable it in that order. Switching enforcement on before the host page sends a hash silently
stops identifying anybody.

## Rotating the secret

**Settings → Installation → Identity verification → Rotate secret.**

Rotating invalidates every digest computed with the old value, so deploy the new secret to
your server first and rotate second. During the gap, unverified calls are downgraded (or
rejected, if enforcement is on) — they are never mis-attributed.

Rotate whenever the value has been somewhere it should not be: a committed `.env`, a pasted
log, a chat thread, or a coding agent you no longer trust with it.

---

# Help center

Every workspace has a help center, created with it at signup. It is a public, crawlable site
of collections and articles, and it is also where the widget's article card gets its content
— the same articles serve a customer searching Google and a customer who opened the chat.

There is nothing to install. It is hosted, and it is live before you write anything into it.

## URLs

| Surface | URL | What is there |
| --- | --- | --- |
| Home | `https://{slug}.userport.io/` | Collections, search, and the contact entry point. |
| Collection | `https://{slug}.userport.io/collection/{collection-slug}` | One group of articles. |
| Article | `https://{slug}.userport.io/article/{article-slug}` | A published article. This is the link to send a customer. |
| Changelog | `https://{slug}.userport.io/changelog` | Product updates, if the workspace publishes them. |
| Contact | `https://{slug}.userport.io/contact` | A form for visitors who did not find an answer. |
| Chat | `https://{slug}.userport.io/chat` | The chat as a page of its own — nothing else loads. The link to put behind a "Contact support" item in an app or an email footer. `?hm_message=` prefills the composer; `/?hm_chat=1`, the old form, redirects here. |
| Localised | `https://{slug}.userport.io/{locale}/article/{article-slug}` | Any of the above under a locale prefix, for the languages the help center enables. |
| Popular articles (JSON) | `https://api.userport.io/hc/{slug}/{locale}/articles.json` | What the widget's article card reads. Public, read-only, no token. |

`{slug}` is the help center's own, set in **Settings → Help center**. Renaming it changes
every URL above, so change it before you have links in the wild, not after.

The chat URL is the one to know about if you have an app: the help center is hosted and live,
so `/chat` gives you a working "Contact support" link with nothing installed anywhere. It is a
page that is nothing but the chat — no header, no search, no article list loading first — and
Live chat covers what else that link can carry.

## Your own domain

Point a CNAME at the hosted host and set the domain in the help center's settings. Enter it
as a bare hostname — `help.acme.com`, not `https://help.acme.com`; a scheme is stripped on
save.

Once it resolves, that domain becomes the canonical one: article links generated anywhere in
Helpmate — an agent pasting an article into a reply, the widget's article card — are built on
it, and the hosted subdomain keeps working underneath.

Serving docs from your own domain is worth the DNS record. It keeps customers on your brand,
and it is the difference between search traffic accruing to you and to a subdomain of ours.

## What goes in it

| Type | Where it shows |
|---|---|
| **Collections** | Groups of articles; the home page is a list of them. |
| **Articles** | The body of the documentation. Only published ones are public. |
| **FAQ** | Question-and-answer entries on the home page, also emitted as `schema.org/FAQPage` structured data so search engines can surface them directly. |
| **Changelog** | Dated product updates on their own page, for workspaces that publish them. |

Drafts are invisible everywhere — the public site, the widget card, the JSON endpoint. There
is no preview link to share; publish it or keep it in the editor.

## Languages

A help center declares the languages it supports and a default. Enabled locales get a path
prefix — `/fr/article/…` — and the widget follows the locale it resolved, so a visitor who
booted the widget with `locale: 'fr'` is offered the French URLs.

One honest limitation: **articles are not translated per locale yet.** The locale segment
scopes the URL and the surrounding chrome, not the article body. A multilingual help center
today means writing the articles in the language your customers actually read, not
maintaining one article in five.

## Inside the widget

When the help center has at least one published article, the widget's home screen grows an
article card above the conversation entry point, showing the most-read articles and letting
the visitor search before they ask. With no published articles the card is absent entirely —
the widget is chat-only until you write the first one.

That card is the cheapest support win available here: it deflects the questions you have
already answered, and it costs one article. The content comes from the public JSON endpoint
in the table above, which needs no token and can be read by anything.

## Linking to an article

There is no SDK method that opens a specific article inside the widget. Two options, and the
first is usually right:

- **Link straight to the article URL** from your own UI — an empty state, a tooltip, a
  settings page. The customer gets a full page they can read, search and bookmark.
- **Open the widget** with `window.$helpmate?.toggle('open')` and let them search the card,
  or link to `?hm_chat=home` from somewhere with no JavaScript of its own. This is for "I
  need help with something" rather than "here is the page about this".

## Search engines

The help center is indexable and is meant to be. Articles are served as ordinary server-rendered
pages, FAQ entries carry structured data, and a custom domain keeps that traffic on your
brand. If you are deciding what to write first, write the articles your customers currently
ask about in chat — the widget card and search results are fed by the same shelf.

---

# JavaScript API

Everything lives on `window.$helpmate`, which exists only after the `helpmate:ready` event.

```javascript
window.addEventListener('helpmate:ready', function () {
    window.$helpmate.setUser('user-42', { email: 'jane@acme.com' });
});
```

Outside a listener, guard the call: `window.$helpmate?.toggle('open')`.

## Methods

| Method | Area | What it does | Throws |
| --- | --- | --- | --- |
| `$helpmate.setUser(identifier, user)` | Identity | Tell the widget who the visitor is. Safe to call on every authenticated page load — the SDK hashes the payload and skips the request when nothing has changed. | If the identifier is not a string or number, or the user object carries none of email / name / avatar_url. |
| `$helpmate.setCustomAttributes(attributes)` | Identity | Write contact properties without re-identifying. This is how you update a property *after* the first setUser call: setUser is de-duplicated on a hash of the identifier, email, name and avatar_url only, so changing nothing but custom_attributes will not send anything. | If the map is empty. |
| `$helpmate.deleteCustomAttribute(key)` | Identity | Remove one property value from the contact. The definition stays in Settings. | If the key is empty. |
| `$helpmate.setLabel(label) / removeLabel(label)` | Identity | Add or remove a tag on the current conversation. | — |
| `$helpmate.setConversationCustomAttributes(attributes)` | Conversation | Attach data to the current conversation rather than to the person — order id, page the chat started from, plan at the time of asking. | If the map is empty. |
| `$helpmate.deleteConversationCustomAttribute(key)` | Conversation | Remove one conversation attribute. | If the key is empty. |
| `$helpmate.toggle("open" \| "close")` | Widget | Open or close the widget. Called with no argument it flips the current state. | — |
| `$helpmate.showNewMessage()` | Widget | Open the widget straight into the composer — the right target for your own "Talk to us" button. | — |
| `$helpmate.openChat({ message, destination })` | Widget | Open the widget on the visitor's conversation — their most recent one, or a new one if they have never written. `message` prefills the composer and is never sent for them; `destination: "home"` opens the home screen instead. This is what the `?hm_chat=1` link calls. | — |
| `$helpmate.toggleBubbleVisibility("show" \| "hide")` | Widget | Show or hide the launcher bubble while leaving the widget usable through your own trigger. | — |
| `$helpmate.setLocale(locale)` | Widget | Switch the widget language at runtime, e.g. "en", "fr", "pt_BR". | — |
| `$helpmate.setColorScheme("light" \| "dark" \| "auto")` | Widget | Follow your own theme switch. Anything else falls back to "light". | — |
| `$helpmate.popoutChatWindow()` | Widget | Open the conversation in a separate browser window. | — |
| `$helpmate.reset()` | Widget | Forget the current visitor and start clean. Call this on logout — otherwise the next person at that browser inherits the previous conversation. | — |

## Events

All dispatched on `window`.

| Event | Fired when |
| --- | --- |
| `helpmate:ready` | The widget has booted and window.$helpmate is safe to call. Every identify call belongs inside this listener — calling setUser before it is a no-op. |
| `helpmate:on-show` | The visitor opened the widget. |
| `helpmate:on-close` | The visitor closed the widget. |
| `helpmate:on-message` | A message was sent or received. |
| `helpmate:on-start-conversation` | The visitor started their first conversation in this session. |
| `helpmate:error` | An SDK call failed. `event.detail` carries the API response — a rejected identify (bad property type, failed verification) surfaces here. |

`helpmate:error` is the one worth wiring up during development — a rejected identify call
(bad property type, failed verification, unknown key in strict mode) surfaces there with the
API's message, and is otherwise invisible.

```javascript
window.addEventListener('helpmate:error', function (event) {
    console.warn('Helpmate rejected a call', event.detail);
});
```

## Opening the widget from your own UI

Hide the launcher at boot and drive it yourself:

```javascript
window.helpmateSettings = { hideMessageBubble: true };

// later, on your own "Talk to us" button
document.querySelector('#support').addEventListener('click', function () {
    window.$helpmate?.showNewMessage();
});
```

`showNewMessage()` opens straight into the composer. `openChat()` opens on the visitor's
conversation — the most recent one, or a new one if they have never written — and takes a
message to prefill:

```javascript
window.$helpmate?.openChat({ message: 'A question about invoice ' + invoice.number });
```

`toggle('open')` opens to whatever screen the visitor last had.

From somewhere that cannot run JavaScript — a mobile app, an email footer — link to your
help center's `/chat` page instead, or to `?hm_chat=1` on a page of your own that carries the
widget; both call `openChat()` on arrival. See Live chat.

## Conversation attributes

Person-level properties describe who someone is; conversation attributes describe *this*
conversation — the order they are asking about, the page they started from, the plan they were
on at the time.

```javascript
window.$helpmate.setConversationCustomAttributes({
    order_id: 'A-10432',
    started_from: window.location.pathname,
});
```

They show on the conversation in the agent inbox and do not affect contact-level targeting.

## Boot settings

Set before the loader runs; read once. Where a key also has a control in **Settings → Website
widget**, the dashboard wins — see Live chat.

| Key | Values | What it does |
| --- | --- | --- |
| `locale` | "en", "fr", … | Widget language. |
| `useBrowserLanguage` | true \| false | Take the language from the browser instead of `locale`. |
| `position` | "right" \| "left" | Which side the launcher sits on. |
| `type` | "standard" \| "expanded_bubble" | Launcher shape. `expanded_bubble` shows `launcherTitle` beside the icon. |
| `launcherTitle` | string | Label on the expanded launcher. |
| `hideMessageBubble` | true \| false | Boot with the launcher hidden — pair with your own trigger calling `showNewMessage()`. |
| `darkMode` | "light" \| "dark" \| "auto" | Colour scheme at boot. |
| `widgetStyle` | "standard" \| "flat" | Widget chrome. |
| `baseDomain` | string | Cookie domain, e.g. ".acme.com", when the widget spans subdomains. |
| `containerId` | string | Id of the element the widget mounts into. |