By default a visitor is anonymous: the widget stores a random token in the browser and the inbox shows "Visitor". If your product has accounts, tell Svellyo who is chatting. You will see their name and email in the inbox, their attributes in the contact panel, and the same person keeps their chat history across devices and browsers.

Identify a user

Call identify after login, on every page load where you know who the user is.

window.Svellyo("identify", {
  userId: "usr_123", // your stable user id (recommended)
  email: "jane@acme.com",
  name: "Jane Doe",
  avatarUrl: "https://…/jane.png",
  attributes: {
    plan: "pro",
    company: "Acme",
    signedUpAt: "2026-03-01",
    seats: 4,
  },
});

With the React component, pass a user prop instead. Change the object when the user changes, and set it to null on logout.

<SvellyoWidget
  workspaceId="ws_xxxxxxxx"
  user={
    session ? { userId: session.user.id, email: session.user.email, name: session.user.name } : null
  }
/>

Rules:

• userId or email is required. Use userId if you have one; emails change.

• Attributes accept strings, numbers, booleans and null. Keep them flat. They are shown in the contact panel and included in the context the AI sees, so plan: "pro" lets the agent answer plan-specific questions correctly.

• Identifying the same userId from a new browser merges that anonymous visitor into the existing contact and shows their past conversations.

Update attributes later

window.Svellyo("setAttributes", { plan: "scale", trialEndsAt: null });

Attributes merge into the contact. Set a value to null to remove it.

Log out

window.Svellyo("reset");

This clears the visitor session so the next person on that browser starts fresh and cannot see the previous user's chats. Call it in your logout handler. The React component does this automatically when user becomes null.

Verified identity

Anything that runs in a browser can be faked. Without verification, someone could call identify with another customer's email and read their chat history. To prevent this, turn on Require verified identity under Settings → Installation and sign the identity on your server.

1. Copy the identity secret from the Installation page. Keep it on your server only.

2. Compute an HMAC-SHA256 of the userId (or the email, if you do not send a userId) with that secret, as a hex string.

3. Pass the result as hash in identify.

Node.js example:

import { createHmac } from "node:crypto";

const hash = createHmac("sha256", process.env.SVELLYO_IDENTITY_SECRET!)
  .update(user.id)
  .digest("hex");

// send `hash` to the browser along with the user object

Browser:

window.Svellyo("identify", { userId: user.id, email: user.email, name: user.name, hash });

When verification is required, identify calls without a valid hash are ignored and the visitor stays anonymous. Verified contacts show a check mark in the contact panel.

Other stacks: Python uses hmac.new(secret, user_id.encode(), hashlib.sha256).hexdigest(); PHP uses hash_hmac('sha256', $userId, $secret); Ruby uses OpenSSL::HMAC.hexdigest('sha256', secret, user_id).

Contacts

Every identified user becomes a contact. Open Contacts in the sidebar to search, see attributes and conversation history, export a contact's data as JSON, or delete them. Deleting a contact removes their identity and unlinks their conversations; see the privacy article for details.