Tell the AI agent about your visitor and page

The AI agent answers better when it knows who it's talking to and where they are. A Pro customer on your pricing page needs a different answer from a new visitor reading your docs. Pass those details with the widget, and the agent gets them with each message.

These details are context, not a sign-in. Anyone can change what a web page sends, so the agent uses them to tailor its answers, never as proof of who someone is. To prove who a signed-in user is, see Verify signed-in users.

What you can pass#

Add any other fields you like, such as seats or trial.

• area is your own name for that part of your site, such as pricing, docs or checkout.
• url fills itself from the page's address when you leave it out.

With the script tag#

<script
  src="https://cdn.help.ai/sdk/js/elements/1.12.0/elements.js"
  data-public-key="agent_pk_..."
  data-ai-agent-deployment-id="..."
  data-user-id="user_42"
  data-user-name="Jane Doe"
  data-user-context='{"plan": "pro", "role": "admin"}'
  data-page-area="pricing"
  defer
></script>

A named attribute wins over the same field in the JSON. JSON that can't be read is ignored.

With the <web-ai-chat> element#

Use the same attributes without data-, such as user-name, page-area and user-context. When you change an attribute, the widget picks up the new value.

<web-ai-chat
  public-key="agent_pk_..."
  ai-agent-deployment-id="..."
  user-name="Jane Doe"
  page-area="pricing"
></web-ai-chat>

With the NPM package or React#

import { init } from '@helpai/elements';

const chat = init({
  publicKey: 'agent_pk_...',
  aiAgentDeploymentId: '...',
  userContext: { id: 'user_42', name: 'Jane Doe', plan: 'pro' },
  pageContext: { area: 'pricing' },
});

In React, pass the same objects as the userContext and pageContext props of <HelpAI />. A changed prop updates the widget.

Update them as things change#

When the visitor signs in to your site, or moves to another page of a single-page app, update the details. Each call adds to what's already there.

const chat = await HelpAI.ready();

// After your own sign-in
chat.setUserContext({ id: 'user_42', name: 'Jane Doe', plan: 'pro' });

// On a route change
chat.setPageContext({ area: 'checkout', path: '/checkout' });

// After sign-out
chat.clearUserContext();

• clearPageContext() clears the page details.
• reset() clears the visitor details too, and keeps the page details.
• On <web-ai-chat>, change or remove its attributes instead.

Limits#

• Values must be text, numbers or true or false. Lists, objects and empty text are left out.
• Up to 50 fields each for the visitor and the page.
• Text is cut at 1,024 characters.
• An email that isn't a valid address is left out.
• visitorId, conversationId, jwt, token, authorization and password are left out: the widget manages those itself.

Where the details show up#

• The AI agent gets them with each message, and uses them to tailor its answers, never as proof of identity or as instructions.
• The Home tab's standard greeting uses name.
• Inbox shows the name or email you passed on the conversation, without a Verified tag.
• Forms in the chat can use them. A form whose When is On page area shows when area matches its Page area. Only if unknown, under Conditions, skips a form when the visitor details already have those fields. See Show a form in the chat widget (opens another site).