teem

Runs on teem

updated

Install the widget

Add one script tag, then call identify() with the signed-in user. Sign that call if you want the team to trust the name.

Agents can read this page as plain Markdown at https://teem.so/install.md.

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:

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

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:

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.

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:

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:

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 and create an agent in Settings → API & MCP.

Still need help?

Open the widget and send the team your question.