Name visitors on the widget

What it is

By default a website visitor is anonymous — the conversations list shows a dash where a name would be. Visitor identity lets your site tell Agentency who is chatting, so the row reads "Sara Ali / 4821" instead.

The mechanism depends on how you embedded the chat:

Embed type	How identity is passed
Script widget, server-rendered page	data-user-id and data-user-name attributes on the script tag
Script widget, single-page app	A identify() call from your code
Iframe or shared link	uid and uname query parameters on the address

This is a label, not a login. Anyone who can edit the page can change these values, so Agentency treats them as untrusted display data. They never sign anyone in, never grant access to anything, and are never used for billing or ownership. There is no signing or secret involved — because there is nothing to protect.

The values are also not sent to the model. The chatbot does not know the visitor's name and will not greet them by it. Identity is for your dashboard and your CRM.

When you would use it

• The widget sits behind your own login and you want to know which of your users asked what.
• You want the Customers list to show real people rather than a wall of anonymous rows.
• Support needs to match a conversation to an account without asking the customer to repeat themselves.

Where to find it

Open Dashboard → Chatbots → your chatbot → Integrations → Web widget, and open Identify your users — the last embed card.

Steps

1. Open Integrations → Web widget and open Identify your users.
2. Pick the panel that matches how you embedded the chat: Server-rendered pages, Single-page apps, or Iframe or shared link.
3. Copy that snippet.
4. Replace the placeholders with your template syntax. The snippet ships with {{ user.id }} and {{ user.name }} on purpose — your server must print the current user's values per request. Hardcoding one person is the classic mistake and attributes every conversation to them.
5. Optionally set a Column name on the same panel — for example "Employee ID" — to rename the Visitor column in your conversations list. Up to 40 characters.
6. Publish, then have a signed-in colleague send a message.
7. Open the chatbot's Conversations tab and confirm the name appears in the Visitor column, then check Customers in the sidebar.

The three mechanisms in detail

Server-rendered pages

Add two attributes next to the token on the existing script tag, printed by your template engine — Blade, Liquid, ERB, JSX, whatever you use.

You can also attach extra attributes as a small JSON object for things like company or plan, which show up alongside the conversation.

Single-page apps

React, Vue, and similar apps often do not know who is signed in when the embed script runs, so an attribute cannot cover it. Call identify() from your code once your own session resolves:

• It is safe to call before the chat has finished mounting.
• It applies to every chat instance on the page, including ones created later.
• Call it with null on sign-out, so the next person on a shared browser is not attributed to the previous one.

Iframe or shared link

An iframe has no script tag, so the details go in the address instead — uid and uname appended to the hosted page URL. Two caveats:

• If the page already carries a share secret, keep it. The parameters are appended without clobbering an existing one.
• Extra attributes are not available this way. Addresses are recorded by browsers, proxies, referrer headers, and analytics tools, so company names, plan tiers, and anything else sensitive should stay out of them. If you need those, use a scripted embed.

What to put in each field

User ID — a stable internal identifier. Your database id or account number is ideal. Do not use an email address if you can avoid it: it is personal data, it changes, and on the iframe route it would end up in a URL.

Name — a display name. This is what a colleague reads in the conversations list.

Extra attributes — only on scripted embeds. Keep them short and non-sensitive: company, plan, tier. Never a token, never a password, never a payment detail.

Everything is treated as plain text, so HTML and markdown are not rendered. Keep values short — a long name is truncated in the table.

What you get back

Once identity is flowing:

• The Visitor column in the conversations list shows the name, under whatever column heading you chose.
• Clicking a visitor cell filters the list to that person — every conversation they have had, in one click. Clicking again clears it.
• There is a Visitor filter in the filter bar, so you can search by user ID or name directly.
• A visitor card appears on the conversation detail page with the details your system sent.
• People flow into Customers in the sidebar. See Customers list.

That first one is the payoff. "Show me everything this customer ever asked" goes from impossible to one click.

Identity vs. lead capture

Two different ways to learn who someone is, and you can use both.

	Visitor identity	Lead capture
Source	Your website, from its own session	The visitor, typing into a form
When	Automatically, before the first message	Before the chatbot's first reply
Trustworthy	Only as much as your page is	It is whatever they typed
Good for	Signed-in areas of your product	Public pages with anonymous traffic

On a public marketing site, identity is unavailable and lead capture is the right tool — see Lead capture fields and Where leads come from.

What you will see

Identify your users is the last card on the Web widget tab, because it applies across all the embed options rather than being one of them. Its panel has one snippet per embed style, a privacy note, and the column-name field.

Limits and plan notes

Requires a paid plan with integrations, because it rides on the widget or the hosted page. The column name is capped at 40 characters.

Identity is never an authentication signal. If you need to restrict who can open the hosted page, that is a separate feature — see Hosted page access control.

Common problems

Every conversation shows the same person.

You hardcoded one id into the snippet instead of printing the current user's. Render the values per request.

Nothing shows up at all.

Check the attributes actually reached the browser — view source on the live page and confirm the values are real rather than literal {{ user.id }} text your template never processed.

In my single-page app, the first conversation is anonymous.

Your identify() call runs after the visitor has already sent a message. Call it as soon as your session resolves rather than waiting for a route to finish.

The name shows as raw code or a link.

Values are plain text and are never rendered as markup. Send a clean display name.

A signed-out visitor is still attributed to the last user.

Call identify(null) on sign-out. Shared and public computers make this a real problem, not a theoretical one.

Does the chatbot know the visitor's name in its answers?

No. Identity is not sent to the model. If you want personalised greetings, that is a different design — start with Write instructions.