Frontend Setup

Deploying agent and AI Chat

There are two ways to deploy AI chat in your front end:

iFrame Embedding
Native React Component Embedding 🔒

iFrame Embedding
Native React Component Embedding 🔒

Deploying an Application (Recommended)

To embed an Application Space for a specific user, use the following iFrame:

<iframe
  src={`https://ai-hub.upsolve.ai/share/application/${applicationId}?jwt=${projectUserToken}`}
  width="100%"
  height="800"
  style={{ border: "none" }}
/>

applicationId — found in your hub2 application settings, or in the URL when viewing the application: /projects/{projectId}/applications/{applicationId}
projectUserToken — a short-lived JWT obtained from your backend via POST /v1/api/projects/user-token (see Backend Setup)

Token expiry: Project user tokens expire after 1 hour by default. Replacing the jwt query parameter will reload the iFrame. To re-authenticate without a full reload, recreate the iFrame element programmatically.

Application Query Parameters

Parameter	Type	Required	Description
`jwt`	string	Yes	Project user token for authentication
`theme`	`light` \| `dark`	No	Visual theme

Only compatible with project users — the /share/application/ route requires a project user JWT obtained from POST /v1/api/projects/user-token. Legacy tenant JWTs are not supported for application embeds.

Deploying Chat via iFrame

You’ll need to get the JWT for the current user and the agent ID to render the chat interface. The JWT is generated by following the steps in Backend Setup.

Getting the Agent ID

You can find your agent ID by visiting your agents at https://ai-hub.upsolve.ai/agents. The agent ID is visible in the URL when you click on an agent, or in the agent list view.

Authentication via JWT: Chat iframes use JWT tokens passed via query parameters for authentication, similar to dashboards. Users don’t need to be logged into the Hub - they just need a valid JWT token in the URL.

Important: Changing the JWT token in the iframe src will cause the browser to reload the entire iframe and reset the chat session. This happens automatically when:

The JWT expires and gets refreshed
User switches tenants/organizations
Tenant permissions are updated

Each iframe load starts a fresh chat session. Plan your token refresh strategy carefully to avoid interrupting active conversations.

Below is an example of deploying chat with JWT using Clerk middleware:

"use client";
import React from "react";
import { useUser } from "@clerk/nextjs";

const AIChatInterface: React.FC = () => {
  // Get the user information from Clerk and extract the Upsolve token from the metadata
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const agentId = "your-agent-id"; // Replace with your agent ID

  // Embed the chat component into your app
  return (
    <>
      {upsolveToken != null && typeof upsolveToken === "string" && (
        <iframe
          id={agentId}
          title="AI Chat"
          width="100%"
          height="800"
          style={{ border: "none" }}
          src={`https://ai-hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&theme=light`}
        />
      )}
    </>
  );
};

export default AIChatInterface;

For organizations migrated to hub2.5, use the ai-hub.upsolve.ai URL format shown above. Legacy URLs (hub.upsolve.ai/share/dashboard/... and hub.upsolve.ai/share/chat/...) continue to work and will automatically forward to the new experience.

Dashboard Query Parameters

The dashboard iframe supports the following query parameters:

Parameter	Type	Required	Description
`jwt`	string	Yes	Tenant JWT for authentication
`theme`	`light` \| `dark`	No	Visual theme
`version`	number	No	Lock to a specific dashboard version (defaults to latest)
`hideHeader`	boolean	No	Hide the header UI
`hideDownloadButton`	boolean	No	Hide the download button
`themeConfigs`	JSON string	No	Custom theme configuration
`dbAuthToken`	string	No	Database authentication token for RLS (see RLS section)
`filter_{key}`	any	No	Controlled filter values (e.g., `filter_region=US`)

Version Locking

You can lock an embedded dashboard to a specific version using the version parameter. This ensures that the dashboard renders with a specific configuration, even if newer versions are published.

<iframe
  id="c5da5cb3-fedb-4656-9170-0cc65c9db29a"
  title="Example Dashboard"
  width="1000"
  height="1000"
  src="https://ai-hub.upsolve.ai/share/dashboard/c5da5cb3-fedb-4656-9170-0cc65c9db29a?theme=light&jwt=<upsolveToken>&version=5"
/>

Version locking is useful when: - You want to maintain consistency across deployments - You need time to test new dashboard versions before deploying them - Different customers should see different versions of the same dashboard

Chat Query Parameters

The chat iframe supports the following query parameters:

Parameter	Type	Required	Description
`jwt`	string	Yes	Project user JWT for authentication
`prompt`	string	No	Initial prompt — auto-sent when the chat loads
`theme`	`light` \| `dark`	No	Visual theme
`placeholderOverrides`	JSON string	No	Customize UI text (input placeholder, assistant name, disclaimer, etc.). See schema below
`exampleQuestions`	JSON string	No	Array of starter questions shown on the welcome screen before the user sends their first message

`placeholderOverrides` Schema

{
  "userName": "string",
  "assistantName": "string",
  "inputPlaceholder": "string",
  "thinkingPlaceholder": "string",
  "disclaimerText": "string"
}

All fields are optional. For example, to customize the input placeholder and disclaimer:

?placeholderOverrides={"inputPlaceholder":"Ask about your data...","disclaimerText":"Results may be approximate."}

`exampleQuestions` Example

?exampleQuestions=["What were our top sales last quarter?","Show revenue by region"]

Example with Initial Prompt

const AIChatWithPrompt: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];
  const agentId = "your-agent-id";
  const initialPrompt = "What were our top sales last quarter?";

  return (
    <iframe
      src={`https://ai-hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&prompt=${encodeURIComponent(
        initialPrompt
      )}&theme=dark`}
      width="100%"
      height="800"
      style={{ border: "none" }}
    />
  );
};

Understanding Session Reset on JWT Change

When the upsolveToken value changes, React re-renders the iframe with a new src URL. This causes the browser to completely reload the iframe and start a new chat session.

// Example: Token change triggers iframe reload and session reset
const AIChatInterface: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  // When upsolveToken changes, the chat session resets
  return (
    <iframe
      src={`https://ai-hub.upsolve.ai/share/chat/abc?jwt=${upsolveToken}`}
      // ↑ Changing upsolveToken resets the entire conversation
    />
  );
};

Common scenarios that trigger session reset:

Automatic token refresh (every hour)
User switches between tenants/organizations
User logs out and back in
Tenant permissions are updated

To preserve chat history across token refreshes, consider: 1. Implementing session persistence on your backend 2. Storing conversation history outside the iframe 3. Refreshing tokens during natural conversation breaks 4. Warning users before token expiration

Import Upsolve AI SDK

If you haven’t already, ask the Upsolve AI team for “a key to the private NPM library”. Use the key in your .npmrc or .yarnrc file. You can then import the SDK into your application.See the Dashboard Deployment section for detailed setup instructions.Once configured, install the SDK:

npm i @upsolve-labs/sdk
# or
yarn add @upsolve-labs/sdk

Deploy Chat - Tailwind and CSS Setup

If you haven’t already set up Tailwind and global CSS for the Upsolve SDK, follow these steps:Tailwind Configuration (tailwind.config.js):

tailwind.config.js

module.exports = {
  content: [
    ...
    "./node_modules/@tremor/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@upsolve-labs/**/*.{js,ts,jsx,tsx}",
    "./node_modules/flowbite-react/lib/esm/**/*.{js,ts,jsx,tsx}",
  ],
  ...
  presets: [require("@upsolve-labs/sdk/tailwind.config.js")],
};

Global CSS Import (layout.tsx):

layout.tsx

"use client";
import '@upsolve-labs/common/styles/global.css';

See the Dashboard Deployment section for complete setup details.

Deploy Chat Component

Use the UpsolveChat component to embed AI chat directly in your React application.

Important: Changing the tenantJWT prop will reset the chat session. The React component will:

Clear the current conversation
Re-fetch agent configuration with new authentication
Start a fresh session with updated data access

This ensures the chat reflects the current tenant’s permissions, but will interrupt ongoing conversations.

AIChat.tsx

"use client";
import React from "react";
import { UpsolveChat } from "@upsolve-labs/sdk";
import { useUser } from "@clerk/nextjs";

const AIChat: React.FC = () => {
  const { user } = useUser();
  const upsolveToken = user?.publicMetadata?.["upsolveToken"];

  return (
    <>
      {typeof upsolveToken === "string" && (
        <UpsolveChat
          tenantJWT={upsolveToken}
          agentId="your-agent-id"
          prompt="How can I help you today?"
        />
      )}
    </>
  );
};

export default AIChat;

Props

Prop	Type	Required	Description
`tenantJWT`	string	Yes	JWT token for authentication
`agentId`	string	No	Agent ID (fetches first agent if not provided)
`prompt`	string	No	Initial prompt to start the conversation
`apiHostOverride`	string	No	Custom API endpoint (default: `https://api.upsolve.ai`)
`useLocalApi`	boolean	No	Use localhost for testing (default: `false`)

Example with Custom Prompt

<UpsolveChat
  tenantJWT={upsolveToken}
  agentId="your-agent-id"
  prompt="Show me sales data for Q4 2024"
/>

Auto-selecting Agent

If you don’t specify an agentId, the component will automatically use the first available agent for the organization:

<UpsolveChat
  tenantJWT={upsolveToken}
  // No agentId - uses first agent automatically
/>

Deploy Chat - Deploy to Production

Make sure that your .npmrc or .yarnrc.yml values are provided to your deployment as env variables, otherwise the deployment will not work.

For enterprise features, look for the 🔒 symbol. These features are available in our Enterprise plan. Please contact us for more information.

Welcome to Upsolve AI

Get Started

Concepts

Encode Your Context

Deploy & Expose

Observability

Technical Reference

Deploying agent and AI Chat

Deploying an Application (Recommended)

Application Query Parameters

Deploying Chat via iFrame

Getting the Agent ID

Dashboard Query Parameters

Version Locking

Chat Query Parameters

`placeholderOverrides` Schema

`exampleQuestions` Example

Example with Initial Prompt

Understanding Session Reset on JWT Change

Props

Example with Custom Prompt

Auto-selecting Agent

Welcome to Upsolve AI

Get Started

Concepts

Encode Your Context

Deploy & Expose

Observability

Technical Reference

​Deploying agent and AI Chat

​Deploying an Application (Recommended)

​Application Query Parameters

​Deploying Chat via iFrame

​Getting the Agent ID

​Dashboard Query Parameters

​Version Locking

​Chat Query Parameters

​placeholderOverrides Schema

​exampleQuestions Example

​Example with Initial Prompt

​Understanding Session Reset on JWT Change

​Props

​Example with Custom Prompt

​Auto-selecting Agent

Deploying agent and AI Chat

Deploying an Application (Recommended)

Application Query Parameters

Deploying Chat via iFrame

Getting the Agent ID

Dashboard Query Parameters

Version Locking

Chat Query Parameters

`placeholderOverrides` Schema

`exampleQuestions` Example

Example with Initial Prompt

Understanding Session Reset on JWT Change

Props

Example with Custom Prompt

Auto-selecting Agent