> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Web Page
> Configure your agent's web chat page — layout blocks, free-floating page images, appearance (background, theme, typography), SEO, greeting, opening hours, custom dashboard pages, and response presentation.
**Field reference:** [`public_details`](/reference/public_details) (`page_layout`, `page_images`, `response_format`, `presentation_notes`, `palette`) · [`web_channel`](/reference/web_channel) (`page_background`, `theme_mode`, `seo`, `chrome`, `greeting`, `availability`, `font_id`, budget) · [Page layout block types](/sections/page-layout).
The **Web** page (under **CHANNELS** in the sidebar) is where you shape the agent's standalone web chat page at `agentheya.com/agent/{name}` and the custom pages shown on its dashboard: the UI blocks rendered around the chat panel, the json-render dashboard pages your buyers see, and how richly the agent formats its answers.
The agent's *identity* — name, description, instructions, visibility, and legal policies — lives on the [Public Details](/sidebar-menu/details) page.
## Your public link (subscribers)
On the subscriber **Public Details** page, the **Display name** field doubles as the source of your instance's public URL. You type only a display name; the URL **slug** — the path segment after the agent name — is *derived* from it on save (lowercased, spaces and separators collapsed to underscores). A blank display name falls back to your raw account id.
The field is locked until you click **Change Name**. As you type, availability is checked live against the other instances of this agent, and **Save Name** only enables once the derived slug is valid and free. Two rules apply to the derived slug:
* It must be **at least 12 characters** long (and at most 64).
* It must be **unique** within this agent — a clash surfaces *"Clashes with an existing name — pick a different name."*
The input itself accepts letters, digits, spaces, hyphens, and underscores. Changing your display name never touches the underlying agent name.
Once saved, the page shows two **Public URLs**:
| Link | Shape | Notes |
| -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pretty URL** | `…/agent/{agent_name}/{slug}` | What visitors normally see. Uses your derived slug (or your account id when the display name is blank). Changes if you rename. |
| **Permalink** | `…/agent/{agent_id}/{account_id}` | A stable link built from the immutable agent id and your account id. It never changes — even if the agent is renamed or you change your display name — and the router redirects it to the pretty URL. Use it for bookmarks and integrations that must survive renames. |
Each link has a copy button and an open-in-new-tab button.
## Embedding the chat page
Besides sharing the link directly, you can embed the whole chat page inside an existing site with a standard `
```
Adjust width and height to fit your layout — the chat interface is responsive and works on mobile. This embeds the full page you configure here, which is separate from the **embeddable widget** (see below), which has its own customisation surface.
## Web chat page layout
Owner-defined UI blocks rendered on the agent's standalone chat page — pre-chat intake forms, hero banners, link lists, FAQ accordions, suggested-prompt chips, embedded widgets, or fully custom JsonUI. Blocks are **separate from the embeddable widget**, which has its own customisation surface.
Every block declares one of three positions:
| Position | Where it renders |
| ------------ | ----------------------------------------------------------------------------------- |
| `above_chat` | Between the page header and the chat panel. |
| `below_chat` | Under the chat panel, above the legal footer. |
| `sidebar` | A right-hand column alongside the chat (collapses to one column on narrow screens). |
Click **Add block**, pick a type, and fill in its fields — each block gets its own collapsible editor card. **Drag a card anywhere** to reorder blocks (mouse or touch; a plain click still collapses/expands the card). The save bar at the bottom of the page persists the whole layout.
See [Page layout](/sections/page-layout) for the full list of block types and their fields.
### Links in displayed text
Any displayed text — the hero headline and subtitle, FAQ questions **and** answers, block headings, notice titles and bodies, form intros, markdown bodies, and the greeting message — can contain links written as plain HTML anchors:
```html theme={null}
Read our terms before booking.
```
Links are rendered **safely**: only `https://`, `http://`, site-relative `/path`, `mailto:` and `tel:` targets become real links (external ones open in a new tab). Anything else — `javascript:` URIs, anchors carrying extra attributes, any other HTML tag — stays visible as plain text, so page text can never inject scripts. Markdown fields (FAQ answers, notices, markdown blocks) also accept standard markdown `[text](url)` links.
The hero block additionally has an **Image link** field — set it and the hero image itself becomes clickable.
## Page images
Freely-positioned images overlaid on the chat page — a full-page background, logos, badges, or art floating over the page. Add up to 20 images, each from a pasted **URL** or an **uploaded file** (max **5 MB**; PNG, JPG, GIF, WebP, AVIF, **SVG**, BMP, ICO — SVGs are screened for scripts on upload and served sandboxed).
Position images two ways, always in sync:
* **The preview canvas** — a 16:9 stand-in for a visitor's screen showing the page's own tiers (header, layout blocks, chat window). Click an image to select it, drag to move, drag the corner handle to resize, arrow keys to nudge (Shift = 5%).
* **Exact fields** — X/Y/Width/Height as **percentages of the visitor's viewport** (so a design scales to any screen), rotation, and an opacity slider. Leave Height empty to keep the image's own proportions; values below 0 or above 100 let an image bleed off the edge.
Each image also has:
| Setting | What it does |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Depth** | Where the image stacks against the page. The page paints layout blocks at depth `20` and the chat window at `40`; presets cover *Behind the page* (−10), *Over the blocks, under the chat* (30) and *On top of everything* (50), and the exact z field accepts any value from −99 to 55. Dialogs and menus always stay above images. Images at the same depth stack by row order — drag rows to change it. |
| **Placement** | *Free* (position/size it yourself) or *Full-page* — a wallpaper that fills the screen (`object-fit: cover`). |
| **Link URL** | Optional. Set it and the image becomes clickable (its rectangle then sits over the page). Images **without** a link never intercept clicks — the chat stays fully usable underneath them. |
| **Alt text** | Accessibility description; leave empty for decorative images. |
Deleting an image is immediate (confirm dialog) and also removes the uploaded file; everything else saves with the page's save bar.
## Page appearance
The page canvas behind your chat:
* **Page background** — a solid colour or a two-colour gradient (with angle), set separately for **light** and **dark** mode. Cards and text keep their theme colours; this paints the canvas behind them.
* **Colour scheme** — *Visitor's choice* (default; the light/dark toggle is shown), *Always light*, or *Always dark*. Locking a scheme brand-fixes the page: visitors always see it, the toggle disappears, and their preference on the rest of the site is untouched.
* **Typography** — curated system-font presets (Inter, two serifs, geometric, rounded, monospace) applied to the whole page. Nothing extra is downloaded.
## SEO & sharing
How the page looks in search results and link previews (chat apps, social posts). All optional; blanks fall back to the page defaults.
| Field | Used as |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Page title** | Browser tab title, `og:title` (blank = the agent's display name). |
| **Description** | Meta description, `og:description`, `twitter:description`. |
| **Social image URL** | `og:image` / `twitter:image` — an `https://` URL or a site-relative path such as an uploaded page image's `/agent/{name}/page-image/…` URL. Ideal size 1200×630. |
Tags are server-rendered, so crawlers and unfurlers see them without JavaScript.
## Page chrome
Strip parts of the page for a cleaner, kiosk-style chat. Each toggle **saves immediately**:
* **Hide header** — removes the top bar (logo, name, login buttons, theme toggle — pair with a locked colour scheme).
* **Hide footer** — removes the legal links / contact strip.
* **Hide usage bar** — removes the logged-in visitor's daily token readout.
## Greeting message
A welcome bubble shown above the message box before the visitor sends anything — as if the agent spoke first. It disappears once the conversation starts and is **never sent to the AI** (pure presentation). Line breaks are kept, and it may contain safe links (see [Links in displayed text](#links-in-displayed-text)). Max 500 characters.
## Availability
Opening hours for the web chat. In **Scheduled** mode you set per-day open/close times (24h) in a chosen timezone; outside them:
* visitors see your **closed message** as a banner on the page, and
* the chat endpoints reject sends with the same message — you (the owner) can always test.
Overnight windows are supported — set close earlier than open (e.g. `18:00–02:00`). Mark a day **closed** to skip it entirely. *Always open* (the default) disables the schedule. This uses the same pause machinery as the **Budget** card's spend cap (which auto-pauses the web chat when the per-period credit cap is hit).
## Dashboard pages
Custom pages built with json-render, shown on the agent dashboard — your own console and/or each buyer's sidebar.
From this card you can:
* **Create** a page — give it a name and you land straight in the per-page editor, where you build the layout, set its visibility, and can rename or delete it.
* **Enable / disable** a page with the toggle — the change saves immediately.
* **Reorder** pages by dragging a row. The row order is the order pages appear under **SETTINGS** in each buyer's sidebar.
Each row shows who can see the page: **Owner only**, **Owner + buyers**, or **Buyers only** — set in the per-page editor.
See the [Custom dashboard pages guide](/custom-pages) for how a page reads live data, shows values the agent pushes, gives each buyer a private scratchpad, and exposes settings the agent reads.
## Response presentation
How your agent presents answers in chat — how often it uses rich cards & tables, and the brand colours they use. Colours never change *what* the agent says: it picks the meaning (success, warning, …) and your palette decides the look.
### Format
| Preset | Behaviour |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| **Auto** (recommended) | The agent decides per message whether a visual layout helps. |
| **Rich** | The agent leans on cards, tables, stats and alerts whenever a structured view is clearer. |
| **Minimal** | Plain markdown by default; the agent only renders genuinely tabular data. |
| **Text only** | The agent never emits interactive UI, charts or artifacts — text and markdown only. |
### Presentation notes
Optional free-text guidance added to the agent's formatting instructions, beyond the preset — e.g. *"Always summarise metrics as KPI stat cards. Keep tables under 5 columns."* Max 2000 characters.
### Brand colours
Per-agent colours applied to badges, alerts, stats and buttons in chat replies. Five roles — **Accent**, **Success**, **Warning**, **Danger**, **Info** — each with separate **light** and **dark** mode values. Leave a swatch on *default* to inherit the platform colour; **Reset** clears a value you've set.
## Manage via the Management MCP
Everything on this page can be configured programmatically through the [Management MCP](/manage-mcp) — useful for AI agents and CI pipelines. The fields live in two sections:
| Section | Fields |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `public_details` | `page_layout` (blocks incl. `image_href` on hero), `page_images` (position/size %, `z` depth, `mode`, `href`, `opacity`, `rotate_deg`, `alt`), `response_format`, `presentation_notes`, `palette` |
| `web_channel` | `page_background` (light/dark solid or gradient), `theme_mode`, `seo` (title/description/image\_url), `chrome` (hide header/footer/usage bar), `greeting`, `availability` (mode/timezone/hours/closed\_message), `font_id`, plus the spend-cap budget fields |
| | |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Endpoint | `https://manage.agentheya.com/mcp` |
| Tools | `config.get` / `config.set` (empty sections), array patch tools for lists |
| Schemas (HTTP) | [`GET /api/manage-mcp/schema/public_details`](https://agentheya.com/api/manage-mcp/schema/public_details) · [`GET /api/manage-mcp/schema/web_channel`](https://agentheya.com/api/manage-mcp/schema/web_channel) |
For the block/image lists, the array patch tools (`add_section_item`, `update_section_item`, `remove_section_item`, `reorder_section_items`) work on `section: "public_details"` with `array_field: "page_layout"` or `array_field: "page_images"` — see [Page layout — How to configure](/sections/page-layout#how-to-configure). Image **uploads** happen in the dashboard; the MCP can reference already-uploaded files (`file`) or set external URLs (`src`).
When writing `web_channel`, read the current value first and send it back whole — the section also carries the spend-cap budget and the page-chrome flags, and a partial overwrite would reset them.
The **Designer AI chat** (`/ai-helper` on the dashboard) can manage all of this too — ask it to build the page, place images at a given depth, set opening hours, lock the theme, or fill in the SEO fields, and it reads/writes the same sections with the same validation.