# Install teem

You are installing teem in an existing application. teem owns and hosts the widget. Wire the
hosted widget into the application; do not generate, copy, vendor or reimplement it.

The person who sent you here usually supplied an organization key beginning with `pk_`. It is
public and belongs in HTML. They may also have supplied a signing secret beginning with `sk_`,
which is optional and stays on the server; step 2 says what it buys. Neither key is an agent
access key.

If no `pk_` key was supplied, get one with a claim instead of asking for it:

1. `POST https://teem.so/install/claims` with no body. It answers with `claim_url` and `poll_url`.
2. Give the person `claim_url` and tell them to open it to sign up for teem, or to log in and pick
   an organization. Keep `poll_url` to yourself; it is how you collect the key.
3. Wire everything below with the `PUBLIC_KEY` placeholder while you wait.
4. Keep calling `GET poll_url` every ten seconds while they sign up, which takes a minute or two,
   instead of ending your turn to wait. `202` means they have not finished. `200` returns
   `organization_key` and `organization_name`; use that key and tell the person which organization
   it belongs to. `410` means the link ran out after thirty minutes; open a new claim. Only if you
   cannot keep calling, ask the person to tell you when they are done, then call it once.

Do not invent a key. Do not ask for any other key the person did not give you, and do not treat
a missing signing secret as an incomplete install.

## 1. Load the hosted widget

Add this once to the shared layout, immediately before the closing `</body>` tag when practical:

```html
<script src="https://teem.so/t.js" data-organization="PUBLIC_KEY" defer></script>
```

Replace `PUBLIC_KEY` with the supplied `pk_...` value. Do not download `t.js`; its hosted URL is
how fixes reach every installation.

Run the application and open a page. Localhost counts. teem's Install page changes to
installed after the script completes its first valid bootstrap.

## 2. Identify the signed-in user

Call `identify()` wherever the application knows who is signed in:

```text
teem.identify({ id: user.id, name: user.name, email: user.email })
```

Sign it when you have the signing secret. The organization key sits in a script tag, so anyone
can open a console and call `identify()` with any address; the hash is what lets the team trust
the name. On the server, compute a lowercase hexadecimal HMAC-SHA256 of the user's stable id, a
newline, and their email trimmed and lowercased, then render the result beside the public fields:

```text
message = user.id + "\n" + lowercase(trim(user.email))
hash = HMAC_SHA256(message, TEEM_SIGNING_SECRET) # lowercase hex, server-side

teem.identify({
  id: user.id,
  name: user.name,
  email: user.email,
  hash: hash
})
```

A hash over the id alone still works, but it proves only the id: teem then tells the team the address
is unconfirmed. Use your framework's HMAC helper or standard crypto library. Never put the signing secret in
browser JavaScript, HTML, source control or a public environment variable. Signed examples for
Rails, Express, Next.js, Django and plain HTML are in
[teem-examples](https://github.com/andresmax/teem-examples).

Signing is optional and nothing depends on it. Omit `hash` when the secret was not supplied, when
the application has no server-side session, or when the person installing would rather not wire a
secret yet. Those identities arrive as self-declared, the same as a name typed into the widget,
and are never shown to the team as verified. The install is complete either way; signing can be
added later without changing anything else.

When the signed-in person signs out, or a different person signs in on the same browser, call:

```js
teem.reset()
```

It forgets the visitor session, identity and conversation and starts a new session in place, so
the next person never sees the last one's chat. Call `identify()` again afterwards for the new
person.

## 3. Optional feedback link

Any existing Help or Feedback control may open the widget explicitly:

```js
teem.open("feedback")
```

The launcher already opens the widget, so this is optional. The feedback surface arrives after
chat; keeping this call in the host now does not require a later integration change.

If the person turned off "Show the floating button" in teem's widget settings, there is no
launcher, and teem opens only from the application's own Help or Feedback link through
`teem.open()`. Wire it to that link. A team reply still shows on the page as a note in the
corner until it is read.

## Verify

- Only one `t.js` tag exists across the rendered page.
- The organization key is present in `data-organization`.
- If you signed the identity, the signing secret appears only in server-side code or secret storage.
- The launcher opens with keyboard and pointer input.
- On a phone, the panel fills the viewport and the page behind it does not scroll.
- teem's Install page reports the live origin and page.

For agent access after installation, use the separate [MCP reference](https://teem.so/mcp.md)
and create an agent in Settings → API & MCP.
