Frontend Setup

Deploying agent and AI Chat

Deploy AI chat in your frontend by embedding it as an iFrame.

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 workspace ID to render the chat interface. The JWT is generated by following the steps in Backend Setup.

Getting the workspace ID

A workspace’s embed is addressed by its project ID and workspace ID, which appear both in the workspace URL — /projects/{projectId}/workspaces/{workspaceId} — and in the embed snippet on the workspace’s Deploy page. The Deploy page builds the iframe for you, so copying it from there is the quickest path:

A workspace's Deploy page with the numbered steps, the embed code and the preview link generator

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 projectId = "your-project-id"; // Replace with your project ID
  const workspaceId = "your-workspace-id"; // Replace with your workspace ID

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

export default AIChatInterface;

Deploying Chat via React SDK

For a more integrated experience, use the UpsolveChat React component from @upsolve-labs/sdk. This handles all rendering and chat interactions without needing to manage an iFrame manually.

import { UpsolveChat } from "@upsolve-labs/sdk";

export default function Chat() {
  // Replace with your own auth integration
  const { upsolveToken } = getLoggedInUserDetails();

  return (
    <UpsolveChat
      agentId={"your-workspace-id"}
      projectUserToken={upsolveToken}
    />
  );
}

agentId — the ID of the workspace’s agent: the workspace ID from its URL (see Getting the workspace ID above)
projectUserToken — a short-lived JWT obtained from your backend via POST /v1/api/projects/user-token (see Backend Setup)

The React SDK approach is recommended when you want tighter control over the chat component’s lifecycle and styling within your React application.

Preview Link Generator (Hub UI)

The workspace’s Deploy page provides a built-in preview link generator so you can quickly test your agent as a specific project user — no backend integration required. How it works:

Open your workspace in the Hub and navigate to the Deploy page.
Select a project user under Preview it as one of your users.
Click Generate preview link — this creates a 1-hour JWT token and produces a fully working chat URL.
Open the URL in a browser or paste it into an iFrame to preview the agent experience for that user.

Preview links are for testing only. The generated token expires after 1 hour and should not be used in production. For production deployment, integrate the token generation into your backend as described in Backend Setup.

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 projectId = "your-project-id";
  const workspaceId = "your-workspace-id";
  const initialPrompt = "What were our top sales last quarter?";

  return (
    <iframe
      src={`https://ai-hub.upsolve.ai/share/workspace/${projectId}/${workspaceId}?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/workspace/abc/def?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

Welcome to Upsolve AI

Get Started

Concepts

Encode Your Context

Deploy & Expose

Observability

Interact with Analytics Agents

Technical Reference

Deploying agent and AI Chat

Deploying an Application (Recommended)

Application Query Parameters

Deploying Chat via iFrame

Getting the workspace ID

Deploying Chat via React SDK

Preview Link Generator (Hub UI)

Chat Query Parameters

`placeholderOverrides` Schema

`exampleQuestions` Example

Example with Initial Prompt

Understanding Session Reset on JWT Change

​Deploying agent and AI Chat

​Deploying an Application (Recommended)

​Application Query Parameters

​Deploying Chat via iFrame

​Getting the workspace ID

​Deploying Chat via React SDK

​Preview Link Generator (Hub UI)

​Chat Query Parameters

​placeholderOverrides Schema

​exampleQuestions Example

​Example with Initial Prompt

​Understanding Session Reset on JWT Change

Deploying agent and AI Chat

Deploying an Application (Recommended)

Application Query Parameters

Deploying Chat via iFrame

Getting the workspace ID

Deploying Chat via React SDK

Preview Link Generator (Hub UI)

Chat Query Parameters

`placeholderOverrides` Schema

`exampleQuestions` Example

Example with Initial Prompt

Understanding Session Reset on JWT Change