> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/ai-workbench-qore/core-concepts/widget.md). # Widget The prebuilt chat interface that puts a Qore agent on your web page: what it is, what it needs, and what it handles for you. The **widget** is Qore's prebuilt chat interface for an agent, delivered in the `@uptiqai/widgets-sdk` package. You mount it on your own web page, and your users chat with the agent there. It handles conversation state, history and messaging for you. The widget is the UI behind **Embedded Chat**, one of the ways to [embed an agent](/ai-workbench-qore/core-concepts/embed-agent.md). Set it up from **Agent Config** › **Integrate Agent** › **Embedded Chat**. See [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md#embedded-chat). ## Forms of the widget The same package ships the widget in two technologies and two layouts, plus a headless option with no UI at all. | Form | React | HTML web component | Layout | | ------------------------- | ------------------------------- | --------------------------------- | ------------------------------------------------------------------------------ | | **Chat Widget** | `ChatWidget` | `` | A floating popover | | **Full Screen** | `FullScreenChatWidget` | `` | Full screen, with sidebar navigation | | **Headless Agent JS SDK** | `createHeadlessAgentInstance()` | — | None: you build the UI; the SDK handles sockets, agent events and file uploads | React takes **props** as objects. The web component takes **attributes** as JSON strings with kebab-case names. Otherwise they map one to one. ## What the widget does for you * A chat interface, as a floating popover or full screen * A conversation sidebar, and new chats * Message history kept across sessions * Real-time messaging with the agent * The agent's avatar on the trigger button * Theming to match your brand ## What it needs Two props are required. | Prop | Holds | | -------- | --------------------------------------------------------------------------------------------- | | `config` | `serverUrl`, the Qore API host; `agentId`; `widgetKey`; and optionally `agentExecutorVersion` | | `user` | The signed-in person in your app: `uid`, `firstName` and `email`, and optionally `lastName` | {% hint style="warning" %} **Fill `user` from your own authenticated session**, never from query parameters, form input or other untrusted sources. {% endhint %} The headless SDK also requires an `instanceId`, used for socket scoping. ### The widget key The widget authenticates with a **widget key**, created on the agent's [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication.md#key-types) page or in step 1 of the Embedded Chat setup. * **It's safe to ship in browser code**, because it works only from the platform itself and the domains on the agent's **Allowed Domains** list. * It's sent as the `x-widget-key` header. * The same key type is used by the headless SDK, and by the [Agent SDK](/ai-workbench-qore/platform-resources/the-agent-development-sdk.md) in the browser. * **Try Agent**, which opens the Agent Playground, needs the agent to have a widget key. An API key and secret, by contrast, are for server-to-server calls and must never reach a browser. ### Allowed Domains **Allowed Domains** lists the web origins where the agent's widget may run. A widget-key request is accepted only from a page on the list, or from the platform's own domain. * **With the list empty, the widget runs nowhere outside the platform.** * Enter each domain exactly as the browser sends it. A mismatch in protocol, subdomain or port is refused. * Step 2 of the Embedded Chat setup, **Whitelist domains**, adds to the same list. ## Scope | Item | Belongs to | | ---------------- | --------------------------------------------------------------------------------------------------------------- | | Widget key | One agent. An agent can have several keys; each can be renamed or deactivated, and deactivation can't be undone | | Allowed Domains | One agent, shared by all of its widget keys | | A mounted widget | One agent, through `agentId`. Give each widget on a page its own `instanceId` to show several agents | ## Options | Prop / attribute | What it does | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `theme` / `theme` | Palette overrides, such as `primary`, `background`, `foreground` and `sidebar` | | `instanceId` / `instance-id` | Distinguishes several widgets on one page | | `defaultOpen` / `default-open` | Opens the widget on mount | | `hideTrigger` / `hide-trigger` | Full Screen only: hides the default launcher, so you open it from your own button | | `widgetRef` | React only: `open()` and `close()` for programmatic control | | `defaultExecutionId` / `default-execution-id` | Opens a specific conversation, to continue a previous chat | | `onExecutionChange`, `onClose` | React only: callbacks when the conversation changes or the widget closes | | `authToken` / `auth-token` | The signed-in person's identity token, for an agent with [Authentication](/ai-workbench-qore/console/agent-builder/deploy/authentication-1.md) on | | `allowDeveloperMode` / `allow-developer-mode` | **Available on request.** Shows a **Developer Mode** switch, which reveals **Setup Identity Token** | The full list, with types and examples, is on [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md), under **Props / attributes reference**. ## Identity in the widget `user` tells the agent who your app says the person is. `authToken` lets Qore verify it. * With Authentication on, the widget sends `authToken` with new chats, follow-up turns, and permission or credential requests. The headless SDK's `setAuthToken()` replaces it after your app refreshes it. * Qore exposes the verified token to the agent's MCP connections as `$auth.token`. See [MCP](/ai-workbench-qore/core-concepts/mcp.md). * The widget keeps the token only in session memory. * **Setup Identity Token**, under **Developer Mode**, lets you try the agent as a specific person by pasting their token. It lasts for the session and is never stored. A token passed as `authToken` replaces one entered by hand. ## Versions The widget package version is released alongside an executor version. Pin the version that the Embedded Chat panel shows for your agent, so the widget and the executor stay in step. To get a newer widget, upgrade the agent's executor version first. See [Runtime & Versioning](/ai-workbench-qore/console/agent-builder/build/runtime-and-versioning.md). ## Where widget activity shows up [Monitoring](/ai-workbench-qore/console/agent-builder/monitor.md) lists the agent's executions, including those from the embedded widget, alongside API calls and triggers. ## Related * [Embed Agent](/ai-workbench-qore/core-concepts/embed-agent.md): choosing between the widget, the headless SDK and the Agent API * [Integrate Agent](/ai-workbench-qore/console/agent-builder/deploy/agent-integration.md): setup steps, props and examples * [Access & Security](/ai-workbench-qore/console/agent-builder/deploy/authentication.md): widget keys and Allowed Domains *** {% columns %} {% column width="83.33333333333334%" %}

Maintained by Abhishek Paul
AI-assisted, human-approved

{% endcolumn %} {% column width="16.666666666666664%" %}
{% endcolumn %} {% endcolumns %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.uptiq.ai/ai-workbench-qore/core-concepts/widget.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.