Embed a project on your website with a widget and site context injection

A widget puts a chat window for a Tensic project on any web page with one script tag. Site context injection lets your own application tell the project who the logged-in user is, so the assistant can personalise answers and call your internal tools on that user's behalf.

How Tensic widgets work

• A widget belongs to one project. Messages typed into the widget go to that project, with its prompt, tools, guards and budget.
• Creating a widget generates a widget key automatically. The widget key is read-only and scoped to that one project: it can send messages to the project but cannot change any settings, and it is used only for widgets. You do not create an API key by hand.
• A project can have several widgets, for example one per website, each with its own key and settings.
• Widgets are managed in the project's Integrations tab, in the Widgets section.

Create a widget for a project

1. Open the project and select the Integrations tab. Scroll to Widgets.
2. Under Create widget, fill in:
   • Widget Name – an internal name, for example Chat Widget.
   • Allowed Domains – comma-separated list of the domains that may load the widget. Leave empty to allow all domains.
   • Title and Subtitle – shown in the widget header, for example AI Assistant / Ask me anything.
   • Primary Color – the widget's accent colour.
   • Position – where the chat button sits on the page, for example Bottom Right.
   • Welcome Message – the first message the bot shows when the chat opens.
   • Avatar URL – a custom bot avatar; leave empty for the default.
   • Enable streaming – show the answer while it is being generated.
3. Check the look in Preview on the right.
4. Click Create Widget.
5. Copy the Widget Key from the banner and store it safely. It is shown only once.

Always set Allowed Domains for production widgets. It stops other sites from embedding your widget and protects against hijacking and phishing.

Embed the widget in a web page

After you create the widget, the Live preview panel shows an embed snippet:

<script
  src="https://<your-tensic-host>/widget/chat.js"
  data-widget-key="<widget key>"
  data-server="https://<your-tensic-host>">
</script>

1. Click the copy icon next to the snippet.
2. Paste the snippet into the HTML of your page, typically just before </body>.
3. Load the page. The chat button appears in the configured position; click it to open the chat.

The snippet works in any HTML page, including a static file opened directly in the browser, which is useful for a quick test.

Manage an existing widget

Each widget is listed under Widgets with its status (for example Active) and the allowed domains. The actions on the row let you:

• Enable or disable the widget. Disabling takes effect almost immediately; the widget stops answering on every site.
• Preview the widget in the Live preview panel.
• Edit the name, domains, title, colours, position, welcome message, avatar and streaming setting.
• Generate Context Secret (lock icon) – create or regenerate the secret used for site context injection.
• Regenerate the widget key (key icon) – issue a new key, for example if the old one was exposed. Update the data-widget-key in your page afterwards.
• Delete the widget.

Click New widget to add another widget to the same project.

Pass the logged-in user to Tensic with site context injection

By default, a widget only receives the text the user types. The project does not know who is writing, so it cannot, for example, answer "show me my products" safely. Site context injection solves this: your application signs a token with the user's details, and the widget passes it to Tensic. The project can then use that context in its system prompt, templates and tool calls.

Typical context: user ID, name, email, role or permissions, company, plan or department.

1. Generate a Context Secret. In Widgets, click the lock button (Generate Context Secret) on your widget. Store the secret in your backend's environment variables. Never put it in front-end code.

2. Sign a JWT on your backend. When a logged-in user loads the page, create a signed token with any JWT library. Always include an exp (expiry) claim. Example in Python:

   import jwt, time
   
   token = jwt.encode({
       "sub": user.id,
       "name": user.name,
       "role": user.role,
       "email": user.email,
       "meta": {"plan": "enterprise", "department": "engineering"},
       "exp": int(time.time()) + 3600  # 1 hour
   }, CONTEXT_SECRET, algorithm="HS256")
   

   The Site Context Injection panel under Widgets shows the same example for Node.js (jsonwebtoken) and PHP (Firebase\JWT).

3. Hand the token to the widget. Render the widget snippet with the signed token in a data-context-token attribute. Generate it on your server for each page load and never build it in the browser:

   <script
     src="https://<your-tensic-host>/widget/chat.js"
     data-widget-key="<widget key>"
     data-server="https://<your-tensic-host>"
     data-context-token="<signed JWT>">
   </script>
   

   The widget sends the token with every message. Tensic verifies the signature and makes the claims available to the project's system prompt as {{context.<claim>}}: a token with "user_name": "Mette Hald" fills {{context.user_name}}.

Because the token is signed with your secret, users cannot change their own identity or role in the browser. Regenerate the context secret with Generate Context Secret if it may have leaked, and update your backend with the new value.

Use site context to call internal tools safely

Site context injection is what makes a widget useful inside a logged-in product such as a SaaS dashboard or a customer portal.

• Reference the injected fields in the project's system prompt or templates so answers are addressed to the right person and respect their role.
• Pass the user's ID or company from the context to the project's tools or MCP servers, so a request like "renew my licence" or "show my invoices" acts only on that user's own data.
• Base permission checks on the signed context, not on what the user types in the chat. A user can claim anything in a message, but cannot forge the signed token.

Example: a billing portal embeds a widget whose agent has tools to renew, cancel and provision licences. Because the portal injects the logged-in customer's identity, the agent can carry out "provision a new licence for my point-of-sale device" for that customer only.

Common questions