Embed Chat on Your Website
Open in CMSPut your Qlar agent on your own website so visitors can talk to it without leaving the page. The chat can sit inside your page (inline) or open from a button pinned to a corner of the window (floating). It works in a plain HTML page and in a React app, with no build step and no backend changes.
The examples on this page put Atlas, Kirana Group's operations assistant, on Kirana's employee portal, so staff can ask who approves a purchase or how a site safety rule works without leaving the page.
Service agents only. A personal agent is yours alone, so it cannot be embedded on a website: the Embed page shows "only available for service agents" and its buttons are switched off.
How it works
The chat is a standard Web Component called <qlar-component>. You load one script from Qlar's CDN, then place the element where the chat should appear. HTML attributes on the element control how it looks and behaves.
<script type="module" crossorigin src="https://app-container.qlar.ai/qlar-component.mjs"></script>
When the element renders, it connects to your agent and runs the whole conversation UI.
Already using
<pusaka-container>? That is the element's earlier name. The script still registers it, so existing pages keep working. Use<qlar-component>for new embeds.
Before you start
- You need a Qlar account with an agent that is published. Your live site always talks to the published agent. If you have not published yet, see Preview and Publish Changes.
- Your agent should already answer well in Preview: a clear identity, the right knowledge, and a welcome message.
- You need to be able to add a
<script>tag to your page. - Opening-line settings (see Opening lines from websites) reach your live site only after you save them and publish the agent.
Open the Embed page
In the Qlar CMS, move your pointer over the icon sidebar on the left edge to expand it (on a narrow screen, click the menu button (☰) at the top left instead), then open Channels → Embed. Everything on the page applies to the active agent.
The page has three blocks, top to bottom:
| Block | What it is for |
|---|---|
| Build your embed | The fastest path. Open builder opens the builder in a new browser tab. Copy basic snippet copies a small working embed. |
| Opening lines from websites | What an embedding site may send to open the chat in place of the Welcome Message. This is the only saved setting on the page. |
| Developer guide | The hand-wiring guide: Install, In React, Layout, Floating panel, Theme and colors, Top bar, Behavior, Opening line from code, and Attribute reference. It is a short version of this page. |
Older links such as /widget?tab=introduction still work. They scroll to the matching block.

Build it in the builder
Click Open builder on the Build your embed card. The builder opens in its own browser tab, without the CMS around it, because what you look at there is a sample website with your chat on it. That is also the only way to see floating mode as your visitors will: pinned to a corner of a real page.
The header shows Embed builder with your agent's name, for example Embed builder · Atlas, and a breadcrumb back to Channels › Embed. On a wide screen, the settings are on the left and the sample page, a stand-in site called your-site.example, is on the right. On a phone or a narrow window, the page stays on screen and the settings and code open in a sheet from a bottom navigation bar. You can drag the sheet between half and full height.
Start from a preset
The Layout tab opens with a preset strip. Pick Change to see the three starting points:
| Preset | For | What it sets |
|---|---|---|
| Full app | A chat page of its own | Fills the whole page. |
| Page section | Part of an existing page | Chat only, no top bar, no examples. |
| Support bubble | A launcher on every page | Floating, chat only, no top bar, no logo, panel title "Need help?". |
Until you pick a preset, the strip shows Defaults (Inline · Full app · 600px), or Custom with the number of changes once you edit a field, for example 1 change from the defaults. A preset sets only what it is about and puts every other field back to its default. Once you edit a field after applying a preset, the preset shows Modified. After you apply a preset or use Reset settings, an Undo button stays on screen for a few seconds.
The settings tabs
| Tab | What you set |
|---|---|
| Layout | How the chat sits on the page: Inline or Floating. For floating: Position (Corner, Horizontal, Vertical) and Panel size (Width, Height). For inline: Size, the height of the box on the sample page. That height is not an attribute; 100% makes the chat the whole page. |
| Look | Theme (System, Light, Dark), What the chat shows (Full app or Chat only), Show the agent logo above the greeting, While the chat loads (Qlar logo, Spinner, Your image or Nothing, with the ten spinners shown moving). For floating: Show the panel header, Panel title (blank means "Chat") and Panel header colors (Light bar, Light text, Dark bar, Dark text). |
| Top bar | Show the top bar, and the single items: conversation list (menu), new chat, light/dark toggle, sign-in and account menu. |
| Intro | Show example messages under the greeting, and What your site sends: Nothing, Introduction text, Introduction prompt, or Introduction prompt, no system prompt. Fill in a sample writes an example for you. |
| Behavior | Focus the chat input on load, and Resume window for anonymous visitors: 30 min, 1 hour, 6 hours (the default), 1 day, 7 days, or Custom… in minutes, hours or days. |

A dot on a tab means it holds changes. Turn on Show attribute names at the bottom of the settings to see the data-* attribute next to each field. Fields that do nothing in the layout you picked are hidden, not greyed out.
Chat only also turns the top bar off. In the builder, picking Chat only switches Show the top bar off, and picking Full app switches it back on. In your own code, the top bar is controlled by
data-show-top-baralone. See Top bar.
Preview
Press Start (in the top-right, or in the middle of the empty sample page, which says "Nothing is running yet.") to run your settings as a real page with a live chat. After you change something, the preview says "Settings changed. Restart to see them." and Start becomes Restart.
The bar above the page has:
- Draft: the preview runs your draft agent, meaning your latest save, even if it is not published yet.
- Anonymous: the preview chats as a visitor who has not signed in.
- A width picker: Desktop, Tablet (768px) and Phone (390px). Below 480px a floating panel fills the screen, so the phone width shows that.
- Live update (Live on narrow screens): rebuilds the preview shortly after you stop changing settings. Each rebuild starts a new chat. With an introduction prompt, each rebuild also costs a model call.
In the example below, Atlas runs in Floating layout. The launcher sits in the bottom-right corner of the sample site, and its panel is open with Atlas's welcome message, the sign-in prompt for anonymous visitors, and the three example messages.

Get the code
- The code panel under the preview, The element for your page, shows how many attributes your element has. Show code opens it and Hide code collapses it. It has three views: Element (just the tag), HTML page and React. Only settings that differ from the defaults are included, so change two things and you get a two-attribute element.
- Download gives you HTML page (
qlar-embed.html, opens in any browser) or React component (QlarChat.tsx, the element with its TypeScript declaration and a comment that tells you to load the script inindex.html). - If your agent has page events, the Page events panel under the preview shows each event the running page receives, and both downloads include a
qlarPageEventlistener to start from. - More actions (the ... button next to Download) has Copy settings link, which copies a link that opens the builder with the same settings, and Reset settings, which puts every field back to its default.
Draft preview, published code. The preview runs your draft agent, so changes you saved but have not published show up there. The code and both downloads use your published agent, which is the one your live site should use.
Or copy the basic snippet
Copy basic snippet on the Build your embed card copies the script and an inline chat in a 600px-high box, with your agent ID already filled in:
<script type="module" crossorigin src="https://app-container.qlar.ai/qlar-component.mjs"></script>
<div style="height: 600px">
<qlar-component
data-agent-id="YOUR_AGENT_ID"
></qlar-component>
</div>
Paste it into your page's HTML. Keep the wrapper <div> or give the chat's parent a height some other way. An inline chat takes the size of its parent, and a parent with no height means a chat with no height.
Add it by hand
The Developer guide at the bottom of the Embed page has the same steps, already filled in with your agent ID. Its Install section shows the script, the element, and a complete page. Full docs on qlar.ai at the top links to this page.

1. Load the script
Add the script to your page, usually inside <head>. It registers the <qlar-component> element.
<script type="module" crossorigin src="https://app-container.qlar.ai/qlar-component.mjs"></script>
Load it once per page. You can then place as many <qlar-component> elements as you need.
2. Place the element
Replace YOUR_AGENT_ID with your agent ID. You find it in the Developer guide on the Embed page: in the Install snippet and in the Identity row of the Attribute reference. Copy basic snippet also includes it. It looks like a UUID, for example a1b2c3d4-e5f6-7890-abcd-ef1234567890.
A complete page looks like this:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Kirana Employee Portal</title>
<script type="module" crossorigin src="https://app-container.qlar.ai/qlar-component.mjs"></script>
</head>
<body>
<!-- Give the parent a height so the chat has room to render -->
<div style="width: 400px; height: 600px;">
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-theme="system"
></qlar-component>
</div>
</body>
</html>
Open the page in a browser. The chat appears inside the <div>.
Use it in React
React does not know custom elements by default, so you load the script in index.html and declare the element for TypeScript once.
1. Load the script in index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Kirana Employee Portal</title>
<script type="module" crossorigin src="https://app-container.qlar.ai/qlar-component.mjs"></script>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
2. Declare the element
Edit src/vite-env.d.ts or create src/custom-elements.d.ts:
/// <reference types="vite/client" />
import React from "react";
declare module "react" {
namespace JSX {
interface IntrinsicElements {
"qlar-component": React.DetailedHTMLProps<
React.HTMLAttributes<HTMLElement>,
HTMLElement
> & {
"data-agent-id"?: string;
"data-theme"?: string;
"data-app-mode"?: string;
"data-enable-autofocus"?: string;
"data-thread-ttl"?: string;
"data-mode"?: string;
"data-position"?: string;
"data-offset-x"?: string;
"data-offset-y"?: string;
"data-chat-width"?: string;
"data-chat-height"?: string;
"data-chat-title"?: string;
"data-show-title"?: string;
"data-show-agent-logo"?: string;
"data-intro-message"?: string;
"data-intro-prompt"?: string;
"data-intro-raw-prompt"?: string;
"data-show-examples"?: string;
"data-start-screen"?: string;
"data-loading"?: string;
"data-loading-spinner"?: string;
"data-loading-image"?: string;
"data-wa-handoff"?: string;
"data-show-top-bar"?: string;
"data-show-menu"?: string;
"data-show-new-chat"?: string;
"data-show-theme-toggle"?: string;
"data-show-sign-in"?: string;
"data-light-title-bg"?: string;
"data-light-title-fg"?: string;
"data-dark-title-bg"?: string;
"data-dark-title-fg"?: string;
};
}
}
}
export {};
3. Render the element
The simplest React embed is floating mode. The element opens and closes its own panel, so it needs no wrapper component and no state. Place it anywhere in your tree:
export default function App() {
return (
<>
{/* Your app content */}
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-mode="floating"
data-position="bottom-right"
data-chat-title="Atlas"
></qlar-component>
</>
);
}
For an inline chat, give the parent a height:
export default function Chat() {
return (
<div style={{ height: 600 }}>
<qlar-component data-agent-id="YOUR_AGENT_ID"></qlar-component>
</div>
);
}
Want your own launcher button or panel? Put an inline
<qlar-component>inside your own container and show or hide that container yourself. Floating mode is not needed for this.
Layout: inline or floating
By default the chat is inline: it fills the element it sits in, so the parent decides its size. Give the parent a height, or the chat has none.
<div style="height: 600px">
<qlar-component data-agent-id="YOUR_AGENT_ID"></qlar-component>
</div>
data-mode="floating" switches to a launcher button pinned to a corner of the window. The button opens and closes a chat panel and stays visible while the visitor scrolls. The element takes no space in the page flow, so you can put it anywhere in <body> without a wrapper.
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-mode="floating"
data-position="bottom-right"
data-chat-title="Atlas"
></qlar-component>
Floating panel
data-positionpicks the corner:bottom-right,bottom-left,top-rightortop-left.data-offset-xanddata-offset-yset the button's distance from the window edge.data-chat-widthanddata-chat-heightset the panel size.
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-mode="floating"
data-position="bottom-right"
data-offset-x="24px"
data-offset-y="24px"
data-chat-width="400px"
data-chat-height="600px"
data-chat-title="Atlas"
></qlar-component>
Tip: On screens narrower than 480px, the floating panel fills the whole screen whatever its width and height are. It works on phones with no extra setup.
Theme and colors
data-themeacceptssystem(the default, follows the visitor's device),lightordark.data-show-agent-logo="false"hides the agent logo above the greeting.data-chat-titlesets the floating panel's title (default "Chat").data-show-title="false"hides the panel's header bar (title, expand and close buttons); the launcher button stays visible to close the panel, and the panel moves clear of it. On screens narrower than 480px, where the panel fills the screen, the header bar still shows so visitors can close the panel.data-app-modeacceptsfull-apporchat. Both look the same today. It does not hide the top bar. Usedata-show-top-barfor that.
The floating panel's header bar uses your agent's theme color, about 18% darker, unless you set its colors. Light and dark mode each take their own pair, so the panel can match your site in both:
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-mode="floating"
data-light-title-bg="#0F4C81"
data-light-title-fg="#FFFFFF"
data-dark-title-bg="#14B8A6"
data-dark-title-fg="#0F172A"
></qlar-component>
Loading screen
While the chat loads, it shows the Qlar logo in the middle of its space, breathing with a slow shimmer, about one breath every 4 seconds. There is no "Loading" text, so nothing appears in a language your site doesn't use. data-loading swaps the logo for something else:
| Value | Shows |
|---|---|
logo (default) | The Qlar logo, breathing with a shimmer. |
spinner | A spinner in Qlar indigo. Pick one with data-loading-spinner: ring (default), dual-ring, arc, dots, bars, pulse, ripple, orbit, grid or wave. |
image | Your own image from data-loading-image, shown 90px square and breathing like the logo. |
none | Nothing. The chat's space stays empty until it is ready. |
<!-- Your own logo while the chat loads -->
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-loading="image"
data-loading-image="https://your-site.example/logo.png"
></qlar-component>
data-loading-imagetakes anhttps://URL or adata:image/…URI. A transparent PNG or SVG looks best. If it is missing or fails to load, the Qlar logo shows instead.- An unknown value for
data-loadingordata-loading-spinnerfalls back to the default, so a typo still shows that the chat is coming. - The builder's Look tab shows all ten spinners moving, so you can pick one by eye.
Splash for a direct chat URL or iframe
If your application opens a Qlar chat URL directly or uses it as an iframe's src, add the splash query parameter to choose the initial loading indicator. Use this option in an environment where the splash feature has been released.
| Value | Shows |
|---|---|
spinner | A rotating circular track. |
dots | Three pulsing dots. |
bars | Five animated equalizer bars. |
grid | Nine fading squares. |
orbit | A dot orbiting a central disc. |
Values are case-sensitive. For example, an existing chat URL ending in /YOUR_AGENT_ID/chat?appMode=chat becomes /YOUR_AGENT_ID/chat?appMode=chat&splash=dots. Keep the host, agent ID, route and other query parameters from your working chat URL. Use ?splash=dots if there is no query string yet, or &splash=dots if there is one; place it before any # fragment.
To update an existing iframe without losing its other URL parameters:
const frame = document.querySelector("#qlar-chat"); // Your existing Qlar iframe
const url = new URL(frame.src);
url.searchParams.set("splash", "dots");
frame.src = url.toString();
Set the URL before the chat starts; changing an iframe's src reloads it. No CMS setting is needed.
- Omit
splashto keep the existing loading behavior: the Qlar logo by default, or your existingloading,loadingSpinnerandloadingImageembed options. - An explicit
splash=logo, an emptysplash=, or an unknown value shows the Qlar logo. Any explicitsplashtakes priority over those existing loading options. - For
<qlar-component>, continue using thedata-loadingattributes above.splashis a parameter on the chat URL, not adata-splashattribute or a parameter on your host application's page URL.
Top bar
The top bar holds the conversation list (menu), new chat, the light/dark toggle and sign-in. data-show-top-bar="false" hides the whole bar. This is the only way to hide it.
To keep the bar and hide single items, leave it on and turn off the items you don't want:
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-show-menu="false"
data-show-theme-toggle="false"
data-show-sign-in="false"
></qlar-component>
The per-item attributes apply only while data-show-top-bar is true.
Behavior
Autofocus. By default the message box takes focus when the chat loads and after each answer. If the chat sits partway down a long page, that focus jump looks like the page scrolling on its own. Set data-enable-autofocus="false" to stop it.
Resume window. In floating mode, an anonymous visitor who reloads the page or moves to another page with the chat picks up the same conversation. data-thread-ttl sets how long that works, in milliseconds, counted from the last message. The default is 21600000 (6 hours). After that, a new conversation starts.
<!-- Resume for 1 day instead of 6 hours -->
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-mode="floating"
data-thread-ttl="86400000"
></qlar-component>
- It works in floating mode only. An inline chat starts a new conversation on every page load.
- It applies to anonymous visitors only.
- It lives in the visitor's browser. Nothing is deleted on the server when it runs out.
Sign-in links from WhatsApp
If your agent's WhatsApp channel uses Redirect to web (bridge mode), every WhatsApp message is answered with a one-time sign-in link instead of a reply in WhatsApp. The link can point to a page on your own site that embeds the chat. See WhatsApp → Redirect to web for the channel settings.
The link looks like this. Qlar adds the last two parameters to the target URL you set, keeping any query it already has:
https://portal.kirana.example/help?wa_code=K7PQ2XMA&wa_agent=YOUR_AGENT_ID
Nothing needs to change on your page:
- Picked up automatically. The chat reads
wa_codefrom the page address, signs the visitor in as their WhatsApp account, and removeswa_codeandwa_agentfrom the address bar. Other parameters stay. - The floating panel opens by itself, so the visitor lands in the conversation instead of looking for the launcher.
- What they wrote on WhatsApp is sent as the first message as soon as the chat is ready, so the agent answers it right away.
- Several chats on one page.
wa_agentis the agent's published ID, the same value asdata-agent-id. Only the chat for that agent takes the code. - The guest conversation is not carried over. A floating chat does not resume the visitor's earlier anonymous conversation, so it is never attached to their WhatsApp account.
- Expired or used links show "This link is no longer valid" with a way to continue. The visitor sends another WhatsApp message to get a new link.
To keep a chat out of this, set data-wa-handoff="false". That chat ignores the code and leaves the page address as it is, for example when your own page handles wa_code:
<qlar-component data-agent-id="YOUR_AGENT_ID" data-wa-handoff="false"></qlar-component>
Opening lines from websites
By default every visitor sees your agent's Welcome Message (set in Conversation → Introduction). Your site can replace it per visitor, for example to greet an employee by name or to open with a summary of the purchase request they are looking at.
You may not need a route at all: the Welcome Message itself can greet signed-in visitors by name, greet by time of day, or change with conditions, using variables such as {{user.first_name}} and {{time.greeting}}. See Variables and Conditions. Text your site sends through a route is shown as sent: Qlar does not fill in {{ … }} in it, so your site can use its own templating.
Turn on a route
On Channels → Embed, find the Opening lines from websites card. With every route off, visitors see the Welcome Message from Conversation → Introduction. Each switch opens one route:

| Switch | Attribute | What it does |
|---|---|---|
| Custom text | data-intro-message | Shown exactly as the site sends it. No model call. |
| Custom prompt | data-intro-prompt | Your agent answers the prompt with its persona, tools and knowledge. Visitors see the answer, never the prompt. |
| Prompt without system prompt (marked Needs guardrail) | data-intro-raw-prompt | Answered with no system prompt at all, for turning your site's own data into an opening line, like a purchase request summary. Your agent's persona and guardrails do not apply. |
When you turn on Prompt without system prompt, a Guardrail for this route field appears. It is required. Say what the route is for and tell it to refuse anything else, for example:
You turn Kirana purchase request data into one short opening line in English. Refuse any other request.
The guardrail is the only instruction the model gets on that route. Without it, the route would answer whatever a site sends, so a blank guardrail keeps the route off.
The chip next to the card title shows what is open for the saved agent: Welcome message only, 1 route open, 2 routes open, and so on. It adds incl. no system prompt when the third route is on.
Save, then publish
Click Save all changes, then publish the agent with Publish. Your live site uses the published agent, so a saved route does nothing there until you publish.
Be careful with the third switch. It skips your agent's persona and its guardrails: the model gets your site's text and nothing else. Turn it on only for sites you control. Use Custom prompt when the greeting should sound like your agent.
How the routes behave
- One wins. If a page sets more than one attribute, text wins over prompt, and prompt wins over prompt without system prompt.
- Off means ignored. With a route's switch off, its attribute is ignored and the visitor sees the Welcome Message. Nothing reports an error.
- Billing. The two prompt routes make one model call per conversation, billed as AI usage. Generated opening lines are also capped per agent per hour, so a flood of requests cannot run up an unbounded bill. Past the cap, visitors see the Welcome Message instead.
- Privacy. The attributes go to the chat privately, not through the page URL. A prompt with employee or business data does not end up in the visitor's browser history or in server access logs.
Send it from your code
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-intro-message="Welcome back, Dimas. Purchase request PR-2041 is waiting for the Finance Controller's approval."
></qlar-component>
The attributes are read once, as the chat starts. Calling
setAttributeon an element that is already running does nothing and shows no error. Set the values before the element reaches the page, or replace the element to start again.
Render it with the page. The simplest and safest option. Your server already knows who the visitor is, so it writes the attribute into the HTML it sends:
<!-- server-rendered, e.g. from a template -->
<qlar-component
data-agent-id="YOUR_AGENT_ID"
data-intro-prompt="Greet {{ employee.first_name }} and mention their open purchase request {{ request.id }}."
></qlar-component>
Build the element after your data arrives. When the opening line depends on data you fetch in the browser, don't put the element in your HTML and fill it in later. Create it once the data is there, set the attributes, then add it to the page:
<div id="chat-slot" style="height: 600px"></div>
<script type="module">
const request = await fetch("/api/purchase-requests/latest").then((r) => r.json());
const chat = document.createElement("qlar-component");
chat.setAttribute("data-agent-id", "YOUR_AGENT_ID");
chat.setAttribute(
"data-intro-prompt",
`Greet the employee and summarise this purchase request in one sentence: ${JSON.stringify(request)}`
);
// Attributes first, page second.
document.getElementById("chat-slot").appendChild(chat);
</script>
Start again with a new opening line. To start a fresh conversation with a different opening line, for example when the employee switches to another purchase request, replace the element instead of editing it:
function restartChat(slot, introPrompt) {
slot.replaceChildren();
const chat = document.createElement("qlar-component");
chat.setAttribute("data-agent-id", "YOUR_AGENT_ID");
chat.setAttribute("data-intro-prompt", introPrompt);
slot.appendChild(chat);
}
In React, render nothing until the data is ready, and give the element a key from that data. React then replaces the element instead of updating it:
function RequestChat({ request }: { request?: PurchaseRequest }) {
if (!request) return null;
return (
<div style={{ height: 600 }}>
<qlar-component
key={request.id}
data-agent-id="YOUR_AGENT_ID"
data-intro-prompt={`Greet the employee and summarise this purchase request: ${request.summary}`}
></qlar-component>
</div>
);
}
Test it in the builder
Write and test an opening in the builder on the Opening lines from websites card opens the builder. If you have unsaved changes on the card, you are asked first, because the builder uses your saved routes.
In the builder, go to the Intro tab, choose a route under What your site sends, write the opening line (or use Fill in a sample) and press Start. The preview runs your draft agent, so a route you just saved works there before you publish.
Routes the agent does not allow are greyed out. Turn them on in Opening lines from websites, save, then click Check again in the builder. It reads the switches again without reloading, so you keep your settings.
The two prompt routes call the model each time the preview starts, and that is billed to the agent.
Attribute reference
Only data-agent-id is required. Leave an attribute out and its default applies.
Identity
| Attribute | Default | Description |
|---|---|---|
data-agent-id | (required) | The agent the chat talks to. |
Layout
| Attribute | Default | Description |
|---|---|---|
data-mode | inline | inline fills the parent element. floating renders a button fixed to a window corner that opens and closes a chat panel. |
data-position | bottom-right | Corner for the floating button: bottom-right, bottom-left, top-right, top-left. Floating mode only. |
data-offset-x | 20px | Horizontal distance between the button and the window edge. Any CSS length. Floating mode only. |
data-offset-y | 20px | Vertical distance between the button and the window edge. Any CSS length. Floating mode only. |
data-chat-width | 380px | Width of the floating panel. Any CSS length. Fills the screen below 480px window width. Floating mode only. |
data-chat-height | 580px | Height of the floating panel. Any CSS length. Floating mode only. |
Appearance
| Attribute | Default | Description |
|---|---|---|
data-theme | system | system (follows the device), light or dark. |
data-app-mode | full-app | full-app or chat. Both look the same today. To hide the top bar, use data-show-top-bar. |
data-show-agent-logo | true | Show or hide the agent logo above the greeting. |
data-chat-title | Chat | Title in the floating panel's header bar. Floating mode only. |
data-show-title | true | Show or hide the floating panel's header bar: title, expand and close buttons. When hidden, the launcher button closes the panel. Below 480px window width the header bar always shows. Floating mode only. |
Loading screen
| Attribute | Default | Description |
|---|---|---|
data-loading | logo | What shows while the chat loads: logo, spinner, image or none. See Loading screen. |
data-loading-spinner | ring | With spinner: ring, dual-ring, arc, dots, bars, pulse, ripple, orbit, grid or wave. |
data-loading-image | (not set) | With image: an https:// URL or data:image/… URI. Falls back to the Qlar logo if it fails to load. |
Header colors
| Attribute | Default | Description |
|---|---|---|
data-light-title-bg | (agent theme, ~18% darker) | Header bar background in light mode, as a CSS hex value, e.g. #0F4C81. Floating mode only. |
data-light-title-fg | (not set) | Header bar title text and icon color in light mode, as a CSS hex value. Floating mode only. |
data-dark-title-bg | (agent theme, ~18% darker) | Header bar background in dark mode. Floating mode only. |
data-dark-title-fg | (not set) | Header bar title text and icon color in dark mode. Floating mode only. |
Top bar
| Attribute | Default | Description |
|---|---|---|
data-show-top-bar | true | Master switch for the top bar. false hides every item in it. The attributes below apply only while this is true. |
data-show-menu | true | Show or hide the hamburger menu (conversation list). |
data-show-new-chat | true | Show or hide the new-conversation button. |
data-show-theme-toggle | true | Show or hide the light/dark theme toggle. |
data-show-sign-in | true | Show or hide the sign-in button, or the account menu once signed in. |
Opening line
| Attribute | Default | Description |
|---|---|---|
data-intro-message | (Welcome Message) | Text shown exactly as given. Requires Custom text under Opening lines from websites. |
data-intro-prompt | (none) | A prompt your agent answers. The answer becomes the opening line. Requires Custom prompt. |
data-intro-raw-prompt | (none) | A prompt answered with no system prompt at all. Requires Prompt without system prompt, with a guardrail. |
data-show-examples | true | Show or hide the example messages under the greeting (set in Conversation → Introduction). Needs no switch, and does not affect the follow-up offers the agent makes after answering (Conversation Initiative). |
Behavior
| Attribute | Default | Description |
|---|---|---|
data-start-screen | chat | voice opens the chat straight into a voice call (the agent's /voice screen), when voice conversations are on. The call starts by itself when the browser allows sound, otherwise after one tap. A floating chat loads only when the visitor opens it, so no call starts in the background. A WhatsApp sign-in code always opens text chat. |
data-enable-autofocus | true | Focuses the chat input on load and after each answer. false turns it off and avoids an unexpected scroll to the chat. |
data-thread-ttl | 21600000 | Anonymous visitors in floating mode only. How long, in milliseconds, a conversation can be resumed after the page reloads, counted from the last message. The default is 6 hours. Applies in the visitor's browser only. |
data-wa-handoff | true | Picks up a WhatsApp sign-in code (wa_code) from the page address, signs the visitor in and opens a floating panel. false makes this chat ignore the code. See Sign-in links from WhatsApp. |
Check the result
- Open your page in a browser (a private window works well, so you see what a new visitor sees).
- Check that the chat appears where you placed it, or that the floating button shows in the corner you chose.
- Send a question you already tested in Preview, for example
Who has to approve a project worth $2.5 million?for Atlas. The answer should match what the published agent gives when you click View in the CMS. - If you changed settings since your last publish and the site does not show them yet, publish the agent and reload the page.
If something does not look right, check Troubleshooting below.
Troubleshooting
The chat does not show, or is a thin strip. An inline chat takes its parent's height. Give the parent a height (for example height: 600px), or use data-mode="floating". Also check that the script loads once and that data-agent-id holds your agent ID.
The opening line is ignored and the Welcome Message shows. Check in this order:
- The route's switch is on under Opening lines from websites, and you clicked Save all changes.
- You published the agent after saving. Live sites use the published agent.
- For Prompt without system prompt, the guardrail is filled in.
- The attribute was on the element before it reached the page. Setting it later does nothing.
- Only one attribute is set, or you expect the one that wins (text, then prompt, then prompt without system prompt).
The top bar still shows with data-app-mode="chat". That is expected. App mode does not hide the top bar. Add data-show-top-bar="false".
The conversation does not resume after a reload. Resume works only for anonymous visitors in floating mode, within the resume window (data-thread-ttl, 6 hours by default, counted from the last message). An inline chat always starts fresh.
The page jumps to the chat on load. Autofocus moves focus into the message box. Set data-enable-autofocus="false".
A WhatsApp link opens the page, but the visitor is not signed in. Check that wa_agent in the link equals the chat's data-agent-id (the published agent ID), and that the chat does not set data-wa-handoff="false". A link that was already used, or is older than 30 minutes, shows "This link is no longer valid".
The builder preview works, but the live site does not. The preview runs your draft agent. Your site uses the published agent. Publish the agent to apply your saved changes.
Next steps
- Next in the journey: Connect to Instagram, to answer Instagram direct messages too.
- Not on WhatsApp yet? Connect to WhatsApp so people can reach your agent from their phone.
- Test your agent: use Simulation (in the Qlar CMS) to check your agent's answers at scale.
- Set the Welcome Message: see Introduction.