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:
POST https://teem.so/install/claimswith no body. It answers withclaim_urlandpoll_url.- Give the person
claim_urland tell them to open it to sign up for teem, or to log in and pick an organization. Keeppoll_urlto yourself; it is how you collect the key. - Wire everything below with the
PUBLIC_KEYplaceholder while you wait. - Keep calling
GET poll_urlevery ten seconds while they sign up, which takes a minute or two, instead of ending your turn to wait.202means they have not finished.200returnsorganization_keyandorganization_name; use that key and tell the person which organization it belongs to.410means 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.jstag 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.