Embedded Space

6 min read

What it is

Embedded Apps let a customer show one of their own web apps (a customer portal, a case system, an internal tool) inside Unique, so users don't have to switch tabs. There are two ways to use it:

  1. Embedded App space. A space whose whole page is the external app. Admins create it with a name and a URL, and control who can see it with the usual space access settings. There is no chat in this space.

  2. embed: links in a Unique AI space. A normal chat space whose instructions tell the model to answer with links like [Example Portal](embed:example.com/). Clicking such a link opens the app in the side panel next to the chat.

Why

  • Keep users in one place. Many answers end with "go to the portal and look up case 12345". With Embedded Apps the portal opens right next to the answer, at the right page.

  • Simple to set up. A space only needs a name, a URL and its access settings. No connectors, no code, no data exchange between Unique and the app.

  • Safe by default. Unique only frames sites the deployment operator has approved in EMBEDDED_FRAME_URL_ALLOWLIST. Unique never passes its tokens, cookies, chat content or user data to the app. The app handles its own sign-in.

  • Explicit in chat. Only links the space author marks with embed: open in the side panel. Ordinary links keep opening a new tab, so existing spaces don't change behaviour.

How it works

Step

What happens

Operator

Lists the approved sites in EMBEDDED_FRAME_URL_ALLOWLIST on chat, admin and node-chat, and turns the feature flag on for the company.

Admin

Creates an Embedded App space, or writes embed: links into the instructions of a Unique AI space. A URL outside the allowlist is rejected when saving.

Chat

Loads the app in a sandboxed frame. The browser only allows sites on the allowlist (the chat Content Security Policy is built from the same variable).

External app

Must allow Unique to frame it (see Requirements for the external app) and signs the user in itself.

Feature flag

  • Name: FEATURE_FLAG_ENABLE_EMBEDDED_APP_UN_26694

  • Default: off.

  • Turn it on per company on the Feature Flags page in the theme app (requires feature flag management, which is on in QA).

  • What it controls:

    • Admin: shows the Embedded App card on the Create space page.

    • node-chat: allows saving Embedded App spaces.

    • Chat: shows Embedded App spaces and opens embed: links in the side panel. With the flag off, an allowed embed: link still works as a normal link that opens a new tab.

Environment variable: EMBEDDED_FRAME_URL_ALLOWLIST

The list of sites Unique may show inside a frame. It is set by the deployment operator in the Helm values, not in the UI. An empty or missing value allows nothing.

Set the same value on all three services: chat, admin and node-chat. Chat uses it for the browser's frame policy and to check embed: links, admin uses it to show an error in the space form, and node-chat uses it to reject saving a URL outside the list.

Format

Space-separated list of https:// sites. Paths are not allowed (a trailing slash is fine).

yaml
env:
  EMBEDDED_FRAME_URL_ALLOWLIST: 'https://example.com https://portal.acme.com:8443'

Matching rules

Entry

Allows

Does not allow

https://example.com

https://example.com, https://app.example.com and any other subdomain

http://example.com, https://example.com.evil.io

https://*.example.com

Subdomains only, such as https://app.example.com

https://example.com itself

https://portal.acme.com:8443

That host (and its subdomains) on port 8443

The same host on port 443

Entries that are not https, IP addresses and localhost are ignored. On top of the allowlist, Unique always refuses URLs that contain a username or password, internal or local host names, IP addresses, and Unique's own chat and admin addresses.

Create an Embedded App space

  1. Make sure the feature flag is on for the company and the app's site is on EMBEDDED_FRAME_URL_ALLOWLIST.

  2. In admin, go to Spaces and choose Create space.

  3. Pick the Embedded App card ("Show an external web app to your users inside Unique.").

  4. Fill in Name (for example Customer portal) and App URL (for example https://app.example.com).

  5. Use Access in the header to choose who can see the space, the same as for any other space.

  6. Save. Users with access now see the space in chat, and opening it shows the app full page.

If the URL is not allowed, the form shows the reason before saving, for example: "This site is not on the allowed list for Embedded Apps (example.com). Ask your administrator to add it." If the list is empty: "No sites are allowed for Embedded Apps on this deployment yet. Ask your administrator to add one."

In a normal Unique AI space, tell the model to answer with markdown links whose target starts with embed:. You don't need to write https://; chat adds it.

Example space instructions

text
You can link users to the Example Portal at example.com.

- When the user asks for the portal, reply with this exact markdown link:
  [Example Portal](embed:example.com/)
- When the user asks about a case number, link to it using a query string:
  [Case 12345](embed:example.com/?case=12345)
  Replace 12345 with the number the user gave you. Never invent a number.
- Always write these as markdown links starting with embed:. Never put them
  in a code block and never change the domain.

A user asking "Can you open case 4711?" then gets an answer containing Case 4711. Clicking it opens https://example.com/?case=4711 in the side panel. Ctrl/Cmd-click opens it in a new tab.

Situation

Result

Site on the allowlist, flag on, normal chat

Opens in the side panel

Site on the allowlist, flag off, or chat running in the embedded widget

Normal link to the https address, opens a new tab

Site not on the allowlist, or the target is not a valid https address

Only the link text is shown, as plain text

Plain https:// link, even to an allowed site

Normal link, opens a new tab (never the side panel)

Accepted forms: embed:example.com/path, embed://example.com/path and embed:https://example.com/path. Any other scheme, such as embed:http://..., is refused. Copying an answer copies the real https address, not the embed: text.

Requirements for the external app

  • Allow framing by Unique. Send Content-Security-Policy: frame-ancestors https://<your-unique-chat-host> and don't send X-Frame-Options: DENY or SAMEORIGIN. Otherwise the browser blocks the frame and chat shows a "could not load" message with an option to open the app in a new tab.

  • HTTPS only, on a public host name.

  • Own sign-in. Unique does not sign the user in. Because the app runs in a frame on another site, its session cookies need SameSite=None; Secure, or the user has to sign in through a pop-up or a new tab. Sign-in pages that refuse to be framed (many identity providers) must open outside the frame.

  • No data from Unique. The app receives nothing from Unique: no tokens, no chat content, no user data, and no referrer. Everything it needs must be in the URL (for example ?case=12345) or come from its own backend.

Security notes

  • The frame is sandboxed with allow-scripts allow-same-origin allow-forms allow-storage-access-by-user-activation, uses referrerPolicy="no-referrer", and grants no browser permissions (camera, microphone and so on).

  • allow-same-origin is needed for the app's own sign-in. That is why Unique's own addresses and internal hosts are always refused, and why only operator-approved sites can be framed.

  • embed: links are written by the model, so they are treated as untrusted. Each one is checked against the same rules as a space URL before it is opened.

Troubleshooting

Symptom

Check

No Embedded App card on Create space

The feature flag is off for this company.

"This site is not on the allowed list..." when saving

Add the site to EMBEDDED_FRAME_URL_ALLOWLIST on chat, admin and node-chat, then redeploy.

Space or side panel shows "could not load"

The app blocks framing (frame-ancestors or X-Frame-Options), or chat's allowlist differs from admin's.

An embed: link shows as plain text

The site isn't on the allowlist, or the model wrote an invalid target (for example http://).

An embed: link opens a new tab instead of the side panel

The flag is off, or chat is running inside the embedded widget.

The app keeps asking to sign in

The app's session cookies are not SameSite=None; Secure, or its sign-in page refuses to be framed.

Last updated