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. "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://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&theme=light`}
/>
)}
</>
);
};
export default AIChatInterface;
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://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 | Tenant JWT for authentication |
prompt | string | No | Initial prompt to start the conversation |
theme | light | dark | No | Visual theme |
isAdmin | boolean | No | Enable admin features (default: false) |
hideHeader | boolean | No | Hide the header UI |
themeConfigs | JSON string | No | Custom theme configuration |
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://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&prompt=${encodeURIComponent(
initialPrompt
)}&theme=dark`}
width="100%"
height="800"
style={{ border: "none" }}
/>
);
};
Admin Mode
By default, the chat interface runs in end-user mode with simplified views. Set isAdmin=true to enable detailed tool execution information:<iframe
src={`https://hub.upsolve.ai/share/chat/${agentId}?jwt=${upsolveToken}&isAdmin=true`}
width="100%"
height="800"
/>
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://hub.upsolve.ai/share/chat/abc?jwt=${upsolveToken}`}
// ↑ Changing upsolveToken resets the entire conversation
/>
);
};
- 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):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")],
};
layout.tsx):"use client";
import '@upsolve-labs/common/styles/global.css';
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. "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.
