> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat & Widget

> Deploy your agent as an authenticated in-platform chat or as an embeddable widget on your website

The **Chat** and **Widget** deployments are Noxus-hosted interfaces — they need no third-party credentials and ship with a built-in conversation UI.

* **Chat** — an authenticated web chat available inside the Noxus platform (or at a deployment URL) for users in your workspace.
* **Widget** — an embeddable chat widget you can drop onto any website, letting external visitors talk to the agent.

Both deployments share the same rendering layer, so the agent can send markdown, images, file attachments, buttons, and adaptive cards. They differ mainly in **who can access them** and in **how they're branded**.

<Note>
  Both the Chat and the Widget include a built-in **conversation history** panel — users can pick up any of their previous conversations where they left off or start a brand-new one at any time.
</Note>

## Chat Deployment

Chat is the quickest way to put an agent in front of a user. No setup is needed beyond publishing the agent and choosing who is allowed to use it.

<Frame>
  <img src="https://mintcdn.com/spot-16018069/V74P-n082FsZpgqT/images/agents/deployments/chat-interface.png?fit=max&auto=format&n=V74P-n082FsZpgqT&q=85&s=a0ffef66f0b7ad929408230793064904" alt="Chat interface" width="2228" height="1668" data-path="images/agents/deployments/chat-interface.png" />
</Frame>

### Deployment

| Field       | Description                                                                                           |
| :---------- | :---------------------------------------------------------------------------------------------------- |
| **Status**  | Toggle the deployment **Online** or **Offline**. A published version is required before going online. |
| **Version** | The published agent version this deployment uses.                                                     |

<Note>
  A published **version** is required before you can set a deployment to Online. Switch the deployment to **Offline** before editing its configuration.
</Note>

### Access

Control who in your workspace can open the chat.

| Field                                   | Description                                                                                             |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------ |
| **Custom Instructions**                 | Per-deployment instructions appended to the agent's system prompt (e.g. `"Always respond in Spanish"`). |
| **Allow all app users to use this app** | When enabled, every **App user** in the workspace can open the chat.                                    |
| **Allowed users**                       | When the toggle above is off, pick a specific list of users who can access this deployment.             |

### Branding

Override the default Noxus look and feel to match your brand.

| Field                   | Description                                                                                |
| :---------------------- | :----------------------------------------------------------------------------------------- |
| **Use custom branding** | Master toggle — when off, the chat uses the default theme and the fields below are hidden. |
| **Agent logo**          | Image shown next to the agent name in the chat header.                                     |
| **Sidebar logo**        | Image shown at the top of the sidebar. Falls back to your tenant logo when empty.          |
| **Main color**          | Primary / accent color set. Pick from presets or provide a custom color.                   |

<Note>
  Pick **fairly light** colors — chat text is rendered in black, so dark backgrounds make messages hard to read. When you edit the **main color**, the system automatically derives a matching **accent color**; you can override it afterwards if you'd prefer a different pairing.
</Note>

***

## Widget Deployment

The Widget is an embeddable chat that can live on any public website. It shares the agent's configuration with the rest of the platform, but exposes a public front-end that anonymous visitors can use.

<Frame caption="Every label and image shown above is customizable in the Widget content and Branding sections as described below.">
  <img src="https://mintcdn.com/spot-16018069/V74P-n082FsZpgqT/images/agents/deployments/widget-interface.png?fit=max&auto=format&n=V74P-n082FsZpgqT&q=85&s=b37914a41a44d431bd6979a3a5106246" alt="Widget chat and conversation history" width="1301" height="892" data-path="images/agents/deployments/widget-interface.png" />
</Frame>

### Setting Up the Widget

<Steps>
  <Step title="Create a Widget deployment">
    On the agent's **Deployments** page, create a new **Widget** deployment and publish a version.
  </Step>

  <Step title="Copy the embed snippet">
    Once the deployment is Online, Noxus generates an embed snippet you can paste into your website's HTML.

    <Frame>
      <img src="https://mintcdn.com/spot-16018069/V74P-n082FsZpgqT/images/agents/deployments/widget-embed-snippet.png?fit=max&auto=format&n=V74P-n082FsZpgqT&q=85&s=9eff0e54eb08a97edf631693c23c5103" alt="Widget embed snippet" width="1228" height="746" data-path="images/agents/deployments/widget-embed-snippet.png" />
    </Frame>
  </Step>

  <Step title="Paste the snippet on your site">
    Add the snippet to any page where the widget should appear. Visitors will see the chat bubble in the corner and can start a conversation without signing in.
  </Step>
</Steps>

### Deployment

| Field       | Description                                       |
| :---------- | :------------------------------------------------ |
| **Status**  | Toggle the deployment **Online** or **Offline**.  |
| **Version** | The published agent version this deployment uses. |

### Widget content

Copy shown to visitors in the widget UI. Every field is optional — leave blank to use the defaults.

| Field                               | Description                                                        |
| :---------------------------------- | :----------------------------------------------------------------- |
| **Widget title**                    | Shown at the top of the widget panel.                              |
| **Widget description**              | Short subtitle shown under the title.                              |
| **Custom Instructions**             | Per-deployment instructions appended to the agent's system prompt. |
| **Title**                           | Title shown on the **conversations history** page.                 |
| **Subtitle**                        | Subtitle shown on the conversations history page.                  |
| **New conversation button**         | Label used for the "start a new conversation" CTA.                 |
| **No conversations message**        | Placeholder text shown when the visitor has no conversations yet.  |
| **Title logo**                      | Optional square image shown next to the widget title.              |
| **Show "Powered by Noxus" message** | Toggle the Noxus credit line in the widget footer.                 |

### Branding

| Field                   | Description                                                                                                                                            |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use custom branding** | Master toggle for the branding fields below.                                                                                                           |
| **Bubble logo**         | SVG code for the icon shown inside the chat bubble on your site. We recommend a 24×24px icon — the SVG is rendered with the theme's colors and sizing. |
| **Main color**          | Primary / accent color set used throughout the widget. Pick from presets or provide a custom color.                                                    |

<Tip>
  Because the widget is **public**, keep Custom Instructions focused on behavior (tone, scope, fallback responses). Avoid putting secrets or internal URLs there — anything in the agent's prompt can be surfaced to visitors through conversation.
</Tip>

### Access & security

By default the widget is fully public: it can be embedded on any site and anyone who loads it can chat. Two independent, opt-in controls let you lock that down.

#### Domain locking

Restrict which websites are allowed to embed the widget. When enabled, Noxus emits a `Content-Security-Policy: frame-ancestors` header so browsers refuse to render the widget anywhere else.

| Field                                     | Description                                                                                                                        |
| :---------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |
| **Restrict embedding to allowed domains** | When on, only the domains you list can embed the widget. When off, it can be embedded anywhere.                                    |
| **Allowed domains**                       | Origins permitted to embed the widget, e.g. `https://example.com` or `https://*.example.com` (wildcard subdomains). One per entry. |

#### Authentication

| Field                                                 | Description                                                                                                                                                                                                                                                                                      |
| :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Authentication**                                    | **Public** — anyone who can load the widget can chat. **Signed token** — your site's backend mints a signed token for each user; calls without a valid token are rejected. **Noxus user** — the agent runs as the visitor's real Noxus account, authenticated by a Noxus-issued JWT (see below). |
| **Token signing algorithm**                           | **HS256** — a shared secret your backend signs with (stored encrypted by Noxus). **RS256** — your backend signs with a private key; Noxus verifies with your public key / JWKS, so no secret is stored.                                                                                          |
| **Signing secret** *(HS256)*                          | The shared secret used to verify tokens. Leave blank when editing to keep the current value.                                                                                                                                                                                                     |
| **JWKS URL** / **Public key (PEM)** *(RS256)*         | Where Noxus fetches your verification key.                                                                                                                                                                                                                                                       |
| **Token audience (`aud`)** / **Token issuer (`iss`)** | Optional expected claims. Setting `aud` is strongly recommended in production to isolate this widget's tokens from other services that share the signing key.                                                                                                                                    |

<Warning>
  In **Signed token** mode the visitor's chat is bound to the token's `sub` claim, so users can only see their own conversations. Always set the **Allowed domains** so a token can't be replayed from an unapproved site.
</Warning>

#### Host page integration (signed token)

When **Signed token** mode is on, your embedding page supplies a token that Noxus validates on every request. Define a provider function before loading the embed snippet:

```html theme={null}
<script>
  // Called by the widget whenever it needs a (fresh) token.
  window.NOXUS_EMBED_TOKEN_PROVIDER = async () => {
    const res = await fetch("/my-backend/noxus-widget-token");
    const { token } = await res.json();
    return token; // a signed JWT
  };
</script>
<!-- ...then the Noxus embed snippet... -->
```

A static `window.NOXUS_EMBED_TOKEN = "<jwt>"` is also supported, but a provider function is preferred because it can return a fresh token when the previous one expires.

Your backend mints the JWT after authenticating the user. Required and optional claims:

| Claim         | Required                  | Description                                                                             |
| :------------ | :------------------------ | :-------------------------------------------------------------------------------------- |
| `exp`         | Yes                       | Expiry. Keep it short-lived.                                                            |
| `sub`         | Yes                       | Stable per-user id — conversations are keyed to it.                                     |
| `origin`      | When domain locking is on | The embedding page's origin (e.g. `https://example.com`); must match an allowed domain. |
| `aud` / `iss` | Optional                  | Must match the configured audience / issuer when set.                                   |

The token is delivered to the widget over `postMessage` and sent to Noxus in an `x-embed-token` header — it never appears in the page URL.

#### Authenticate as a Noxus user (`noxus_user`)

Choose **Noxus user** when the agent should run as the visitor's *real Noxus account* — it can read and act on everything that user can in Noxus. Authentication is a **Noxus-issued JWT** your integration obtains and relays as a bearer token; it does **not** rely on browser cookies (third-party cookies are blocked inside cross-origin iframes, so cookie-based sessions aren't reliable here).

Noxus is the authorizer: the user consents, Noxus mints an **ES256** access token (≈1h) signed with a platform keypair, and your page relays the access token to the widget. Each authorized client is revocable from **Settings → Authorized clients**.

##### Recommended: the Noxus consent popup (no backend, no CORS)

For a website with no backend, open the Noxus-hosted consent popup and wait for the token — the whole flow runs on the Noxus origin, so your page never makes a cross-origin call:

```html theme={null}
<script>
  function getNoxusToken() {
    return new Promise((resolve, reject) => {
      const noxus = "https://app.noxus.ai";
      const popup = window.open(
        `${noxus}/embed/authorize?deployment_id=YOUR_DEPLOYMENT_ID&origin=${encodeURIComponent(location.origin)}`,
        "noxus_auth",
        "width=480,height=640"
      );
      window.addEventListener("message", function onMsg(e) {
        if (e.origin !== noxus || e.data?.type !== "noxus_embed_token") return;
        window.removeEventListener("message", onMsg);
        e.data.error ? reject(new Error(e.data.error)) : resolve(e.data.access_token);
      });
    });
  }
  window.NOXUS_EMBED_TOKEN_PROVIDER = getNoxusToken; // widget calls it on demand
</script>
```

Noxus validates the requesting `origin` against the deployment's **Allowed domains** and delivers the token via `postMessage` scoped to that origin, so it can only reach the page you authorized. When the token expires, the provider is called again and re-opens the popup — silent if the Noxus session is still valid.

##### Alternative: server-side PKCE (browser extensions, host backends)

If you have a backend (or you're a browser extension), run the PKCE flow and exchange the code server-side, then relay the access token the same way. This is the flow the Noxus Copilot extension uses.

<Steps>
  <Step title="Authorize (PKCE consent, per device)">
    With the user signed in to Noxus, send them to the consent page with a PKCE `code_challenge` and your `redirect_uri`. On consent, Noxus registers a device and redirects back with a one-time `code`.
  </Step>

  <Step title="Exchange the code for tokens">
    ```http theme={null}
    POST /api/public/clients/token
    Content-Type: application/json

    { "grant_type": "authorization_code", "code": "<code>", "code_verifier": "<verifier>" }
    ```

    Returns `access_token`, `refresh_token`, and `expires_in`.
  </Step>

  <Step title="Relay the access token to the widget">
    ```html theme={null}
    <script>
      window.NOXUS_EMBED_TOKEN_PROVIDER = async () => getNoxusAccessToken();
    </script>
    <!-- ...then the Noxus embed snippet... -->
    ```

    The widget sends it as `Authorization: Bearer`; Noxus verifies the signature, checks the device is still active, and runs the conversation as that user.
  </Step>

  <Step title="Refresh before expiry">
    ```http theme={null}
    POST /api/public/clients/token
    Content-Type: application/json

    { "grant_type": "refresh_token", "refresh_token": "<refresh token>" }
    ```

    Because the provider is called on demand, returning a refreshed token from it keeps the session alive with no reload.
  </Step>
</Steps>

Revoke a device at any time — this invalidates its access and refresh tokens immediately:

```http theme={null}
POST /api/backend/clients/{client_id}/revoke
POST /api/backend/clients/revoke-all
```

<Note>
  Domain locking is **recommended** for `noxus_user` but not required: a forged token fails signature verification server-side no matter where the widget is framed, so the JWT — not the frame origin — is the security boundary.
</Note>

### Page context

A host page (e.g. a browser extension or your own app) can feed the agent **what the user is currently looking at**, so it can answer with that context in mind — the record open in your CRM, the article being read, the cart contents, etc.

1. Enable **Accept page context from the embedding page** in the widget deployment's **Access & security** settings. It's off by default; only turn it on for embeds you trust, since the context is client-supplied.
2. From the host page, push context whenever it changes:

```js theme={null}
// Using the embed.js script:
window.SpotChatWidget.setContext({ objectType: "Case", recordId: "500X", title: "Login fails on SSO" });

// Pass null to clear it:
window.SpotChatWidget.setContext(null);

// Or, if you embed the iframe yourself, post the message directly:
iframe.contentWindow.postMessage(
  { type: "SPOT_WIDGET_CONTEXT", context: { /* any JSON or string */ } },
  "*"
);
```

The context is attached to each message the user sends and injected into that turn only — it is **never** stored in conversation history. It is treated as untrusted reference data (not instructions) and is capped at 8,000 characters. A string is used verbatim; any other value is JSON-encoded.