Page Layout
The Embed page has three blocks, one under the other. Old links with ?tab= in the URL still work: they scroll to the matching block.
| |
|---|
| Build your embed | Opens the builder, or copies the smallest snippet that works. Buttons: Open builder (opens in a new browser tab) and Copy basic snippet. |
| Opening lines from websites | Decides what a website embedding the agent can send to open the chat, in place of the Welcome Message. The only saved setting on this page. |
| Developer guide | Reading for wiring the element into a site by hand. Nothing here is saved. Links to these docs with Full docs on qlar.ai. |
Developer Guide Sections
| |
|---|
| Install | The script tag, the element, and a full page example. |
| In React | Loading the script in index.html, typing the custom element for TypeScript, and using it in a component. |
| Layout | Inline versus floating. |
| Floating panel | Corner, offsets and panel size. |
| Theme and colors | Theme, app mode, agent logo, panel title and header colors. |
| Top bar | The master switch and each item in the bar. |
| Behavior | Autofocus and the resume window. |
| Opening line from code | How to send an opening line from the host page. |
| Attribute reference | Every attribute, grouped as in the tables below. |
Copy Basic Snippet
Copies the script tag and one element inside a <div style="height: 600px">, with only your agent ID set. Everything else uses the defaults: the visitor's theme, the full app, and a focused input. The button shows Copied for two seconds.
Element and Script
| |
|---|
| Script | https://app-container.qlar.ai/qlar-component.mjs, loaded with type="module" crossorigin. |
| Element | <qlar-component>. The script also registers the earlier name, <pusaka-container>, so embeds written with it keep working. |
| Agent Binding | Each element talks to one agent, set with data-agent-id. |
| Inline Mode | The default. The chat fills its parent element, so the parent needs a height. |
| Floating Mode | data-mode="floating". A button fixed to a corner of the window opens and closes a chat panel. No wrapper element is needed, in plain HTML or in React. |
Attributes
Every <qlar-component> attribute, grouped like the attribute reference in the CMS. All are optional except data-agent-id.
Identity
| Attribute | Default | Description |
|---|
data-agent-id | Required | The agent the chat talks to. |
Layout
| Attribute | Default | Description |
|---|
data-mode | inline | floating renders a button fixed to a viewport corner that opens and closes a chat panel. Omitted or inline fills the parent element. |
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 viewport edge. Any CSS length. Floating mode only. |
data-offset-y | 20px | Vertical distance between the button and the viewport edge. Any CSS length. Floating mode only. |
data-chat-width | 380px | Width of the floating panel. Any CSS length. Fills the screen below 480px viewport 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 OS), light or dark. |
data-app-mode | full-app | full-app or chat. Both look the same today. It does not hide the top bar: use data-show-top-bar="false" for that. |
data-show-agent-logo | true | Shows or hides 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 | Shows or hides 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. |
All four take a CSS hex value, such as #5651D4, and apply in floating mode only. When a background is omitted, it is derived from the agent theme color, about 18% darker.
| Attribute | Default | Description |
|---|
data-light-title-bg | Derived | Header bar background in light mode. |
data-light-title-fg | None | Header bar title text and icon color in light mode. |
data-dark-title-bg | Derived | Header bar background in dark mode. |
data-dark-title-fg | None | Header bar title text and icon color in dark mode. |
Top Bar
| Attribute | Default | Description |
|---|
data-show-top-bar | true | Master switch. false hides every item in the bar. The attributes below apply only while this is true. |
data-show-menu | true | Shows or hides the hamburger menu (conversation list). |
data-show-new-chat | true | Shows or hides the new-conversation button. |
data-show-theme-toggle | true | Shows or hides the light/dark theme toggle. |
data-show-sign-in | true | Shows or hides the sign-in button, or the account menu once signed in. |
Opening Line
The first three take effect only when the matching switch under Opening lines from websites is on, saved and published. When a page sets more than one, they win in the order listed.
| Attribute | Default | Description |
|---|
data-intro-message | None | Text shown exactly as given, in place of the Welcome Message. Requires Custom text. |
data-intro-prompt | None | A prompt the agent answers. The answer becomes the opening line. Its persona, tools and knowledge apply, and visitors never see the prompt. Requires Custom prompt. |
data-intro-raw-prompt | None | A prompt answered with no system prompt at all, for turning your own data into an opening line, like an order summary. The agent's persona and guardrails do not apply. Requires Prompt without system prompt, with a guardrail. |
data-show-examples | true | Shows or hides the example messages under the greeting, set under Conversation → Introduction. Needs no switch, and does not affect the follow-up suggestions the agent writes after each answer. |
Behavior
| Attribute | Default | Description |
|---|
data-enable-autofocus | true | Focuses the chat input on load and after each answer. false turns it off. |
data-thread-ttl | 21600000 | How long, in milliseconds, a conversation can be resumed after the host page reloads, counted from the last message. The default is 6 hours. Anonymous visitors in floating mode only. |
data-wa-handoff | true | Picks up a WhatsApp sign-in code (wa_code) from the host page address and signs the visitor in. false makes this chat ignore it. See WhatsApp Bridge Mode below. |
In practice:
| |
|---|
| Autofocus | On by default. Turn it off when the chat sits partway down a long page, where the focus jump looks like the page scrolling on its own. |
| Resume Window | For anonymous visitors in floating mode, a page reload picks up the same conversation until data-thread-ttl runs out. After that, a new conversation starts. The window lives in the visitor's browser only; nothing is deleted on the server. Inline embeds do not resume. |
WhatsApp Bridge Mode
A page that embeds the chat can be the target of WhatsApp → Redirect to web. Qlar adds ?wa_code=…&wa_agent={agent ID} to the page address in the link it sends on WhatsApp.
| |
|---|
| Automatic Pick-up | The chat reads wa_code from the page address, signs the visitor in as their WhatsApp account, and removes wa_code and wa_agent from the address bar. Other parameters stay. No code change is needed on the page. |
| Floating Panel | Opens by itself when a code arrives. |
| First Message | What the visitor wrote on WhatsApp is sent as the first message, so the agent answers it right away. |
| Several Chats | Only the chat whose data-agent-id equals wa_agent takes the code. |
| Guest Conversation | A floating chat does not resume the visitor's earlier anonymous conversation, so it is not attached to the WhatsApp account. |
| Opt-out | data-wa-handoff="false" makes a chat ignore the code and leave the page address unchanged. |
| Invalid Link | A used or expired link shows "This link is no longer valid. Send us another WhatsApp message to get a new link.", with Continue and Sign in. |
Opening Lines From Websites
With every switch off, visitors see the Welcome Message from Conversation → Introduction, whatever the embedding page sends. Saving here does not change the Welcome Message itself.
| |
|---|
| Custom text | The site's text is shown exactly as it sends it (data-intro-message). |
| Custom prompt | The agent answers the site's prompt with its persona, tools and knowledge. Visitors see the answer, never the prompt (data-intro-prompt). |
| Prompt without system prompt | Tagged Needs guardrail. For turning the site's own data into an opening line, like an order summary. The agent's persona and guardrails do not apply (data-intro-raw-prompt). |
| Guardrail for this route | Appears when Prompt without system prompt is on, and is required. Say what the route is for and tell it to refuse anything else. Saving without one shows "Add a guardrail, or turn this route off". A blank guardrail means the route is off. |
| Status Chip | Shows the saved state: Welcome Message only, 1 route open / 2 routes open / 3 routes open, with · incl. no system prompt added when the third switch is on. |
| Save | Stores the switches against the agent. Then publish the agent: live sites use the published agent, so the routes apply only after Publish. |
| Write and test an opening in the builder | Opens the builder in a new browser tab. With unsaved changes, it asks first, because the builder uses the saved routes. |
Sending an Opening Line From Host Code
| |
|---|
| Read Once at Start | The opening-line attributes are read as the chat connects. Setting one on an element that is already running has no effect, and reports no error. |
| Server-Rendered | Writing the attribute into the markup the server sends is the pattern with nothing to time. |
| Built in JavaScript | For data fetched in the browser: create the element, set every attribute, and only then append it to the page. |
| Restarting | To open a new conversation with a different opening line, replace the element rather than editing its attributes. In React, a changing key does this. |
Embed Builder
| |
|---|
| Reached From | Open builder on the Build your embed card, or Write and test an opening in the builder on the Opening lines from websites card. |
| Own Browser Tab | Opens at /widget/builder in a tab of its own, with no CMS sidebar or agent preview panel, so the page shows one conversation. |
| Header | Back to Embed arrow, the title "Embed builder" with the agent name, a Channels › Embed › Builder breadcrumb, More actions, Download and Start (Restart once a preview is running). |
| More Actions | Copy settings link (opens the builder with these settings) and Reset settings (puts every field back to its default). On phones it also holds Download HTML page and Download React component. |
| Download | HTML page saves qlar-embed.html, which opens in any browser. React component saves QlarChat.tsx, to add to your React app. Both use the published agent id. |
| Generated Code | Carries only what differs from the defaults. Attributes that do nothing in the chosen layout are left out. |
| Changed Fields | A dot on a settings tab means it holds changes. The footer switch Show attribute names shows the data-* name beside each field. |
Settings Tabs
| |
|---|
| Layout | How the chat sits on the page: Inline ("Fills the box you place it in.") or Floating ("A button in a corner opens a chat panel."). Floating adds Position (Corner, Horizontal, Vertical) and Panel size (Width, Height). Inline adds Size → Height: the height of the box on the generated page, not an attribute. 100% makes the chat the whole page. |
| Look | Titled Appearance. Theme (System, Light, Dark), What the chat shows (Full app or Chat only; Chat only also turns the top bar off), Show the agent logo above the greeting. Floating adds Show the panel header, Panel title (blank means "Chat") and Panel header colors (Light bar, Light text, Dark bar, Dark text), with a header preview. |
| Top bar | Show the top bar, then Conversation list (menu), New chat button, Light/dark toggle, and Sign-in button and account menu. With the bar off, the items are greyed out, not hidden. |
| Intro | Titled Introduction. Show example messages under the greeting, then What your site sends: Nothing, Introduction text, Introduction prompt, or Introduction prompt, no system prompt. Fill in a sample adds sample text. Routes this agent does not allow are greyed out, with Check again to re-read the saved switches. A warning shows when the third route is on but no guardrail is saved. The two prompt routes cost a model call. |
| Behavior | Focus the chat input on load, and Resume window for anonymous visitors: 30 min, 1 hour, 6 hours · default, 1 day, 7 days, or Custom… in minutes, hours or days. |
Presets
The Preset box sits at the top of the Layout tab. Change opens the list. A preset sets only what it is about and puts every other field back to its default. After an edit the preset shows Modified. Applying a preset, or Reset settings, offers Undo for 6 seconds.
| |
|---|
| 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?". |
Preview
| |
|---|
| Draft Chip | The preview runs your draft agent: your latest save, not yet published. The code and downloads use the published agent. |
| Anonymous Chip | The preview chats as a visitor who has not signed in. |
| Width | Desktop (full width), Tablet (768px) or Phone (390px, where a floating panel fills the screen). Not shown on phones. |
| Live update | Rebuilds the preview shortly after you stop changing settings (Live on phones). Each rebuild starts a new chat, and with an introduction prompt, each one costs a model call. With it off, changed settings show "Settings changed. Restart to see them." ("Settings changed" in the header on phones) until you press Restart. |
| Code | Show code / Hide code opens the drawer under the preview. Views: Element, HTML page, React. |
Settings Link
Copy settings link puts the changed fields in the URL hash (#settings=). Opening that link opens the builder with the same settings. Values that do not fit a field are dropped when the link is read.
On Phones
Below 1200px wide, the running page fills the screen. A bottom navigation bar holds one entry per settings tab plus Code, and each opens a sheet over the page. The sheet opens at half height, switches to full height with its button or a swipe up, and closes with a swipe down or Close. The page stays loaded, so opening a sheet does not end a running conversation.