Identity verification

What identification does

By default an embedded chat is anonymous: history is tied to a browser session. When you call identify() with a verified user ID, TeamAI:

Loads that user’s conversation history for this agent, on any device.
Creates or updates a contact in your workspace with the metadata you pass.
Attaches the identity to every request so the agent can use the user’s details.

Verification uses an HMAC. Your server signs the user ID with a secret only it and TeamAI know, so a visitor cannot claim another user’s ID by editing JavaScript.

Never put the verification secret in client-side code. Compute the hash on your server.

Set up the secret

In TeamAI, open Settings and then Identity Verification.
Generate the workspace secret and store it in your server’s configuration.
If the agent should refuse anonymous visitors, open the agent, go to the Advanced tab, and enable Enforce Identity Verification. With this on, requests without a valid identity are rejected with HTTP 401 and code identity_verification_required, and the chat shows an error instead of an answer.

Compute the hash on your server

The hash is HMAC-SHA256 of the user ID, hex encoded, keyed with the workspace secret. It must be computed over the exact string you later pass as user_id.

// Node.js
const crypto = require("crypto");

app.get("/api/chatbot-identity", requireLogin, (req, res) => {
  const userId = String(req.user.id);
  const userHash = crypto
    .createHmac("sha256", process.env.TEAMAI_VERIFICATION_SECRET)
    .update(userId)
    .digest("hex");

  res.json({ userId, userHash });
});

Use a stable identifier such as a database ID or UUID for user_id. Do not use an email address or other value that can change or that you would not want stored as an external ID.

Call identify() on the page

window.addEventListener("teamAIChatbotReady", async () => {
  const chatbot = tai.getInstance("YOUR_ASSISTANT_ID");

  const { userId, userHash } = await fetch("/api/chatbot-identity").then((r) => r.json());

  chatbot.identify({
    user_id: userId,
    user_hash: userHash,
    user_metadata: {
      email: "ada@example.com",
      firstName: "Ada",
      lastName: "Lovelace",
      plan: "Pro",
    },
  });

  // Held until verification finishes, then sent as this user
  await chatbot.sendMessage("Show me my recent orders.");
});

Property	Type	Required	Notes
`user_id`	string	Yes	Your stable identifier for the user.
`user_hash`	string	Yes	HMAC-SHA256 hex of `user_id`, computed on your server.
`user_metadata`	object	No	Up to 1000 characters when serialized. The SDK logs a warning above that and still sends it.

identify() returns nothing. It posts the config to TeamAI for verification and, on success, stores it and sends it to the iframe. On failure it logs an error and the chat stays anonymous. Turn on debug mode to see the result.

How metadata becomes a contact

On a successful verification TeamAI finds or creates a contact in your workspace whose external ID is user_id. These keys map to contact fields:

Metadata key	Contact field
`email`	Email
`firstName` or `first_name`	First name
`lastName` or `last_name`	Last name
`phone` or `phoneNumber`	Phone

Every other key is stored as a custom attribute on the contact.

Timing guarantees

You can call identify() before the agent is ready. The SDK re-sends a verified identity when the iframe loads.
sendMessage() and conversationReady() wait for the most recent identify() to finish verifying before they act, so a message sent right after identify() lands in the identified user’s chat.
Calling identify() with a different user_id reloads the conversation for the new user. A sendMessage() issued during the switch waits for the new history.
Identity is attached to every message the SDK sends to the iframe after verification, including context and tool updates.

Security notes

Serve the identity endpoint only to authenticated sessions, over HTTPS.
Rotate the workspace secret from Settings > Identity Verification if it leaks, then update your server. Hashes made with the old secret stop verifying once TeamAI’s cached copy of the secret refreshes.
The hash proves the ID came from your server. It does not encrypt user_metadata, which is visible in the browser.

Troubleshooting

Verification fails when the hash does not match. Check, in order:

The server hashed the exact string passed as user_id. A number hashed as 123 and passed as "123" is fine; a trimmed or lower-cased value is not.
The secret in your server config is the one shown in Settings > Identity Verification for this workspace. Each workspace has its own secret.
Open the browser console with ?taiDebug=true in your page URL. The SDK logs Identity verified and set for user: ... on success and Identity verification failed for user: ... on failure.

​What identification does

​Set up the secret

​Compute the hash on your server

​Call identify() on the page

​How metadata becomes a contact

​Timing guarantees

​Security notes

​Troubleshooting

What identification does

Set up the secret

Compute the hash on your server

Call identify() on the page

How metadata becomes a contact

Timing guarantees

Security notes

Troubleshooting