# Website

> Deploy Quickchat AI on your website as a floating Widget, an inline Embed, or a hosted Chat Page. Covers install, access control, appearance, text content, and custom parameters.

There are three ways to put your Quickchat AI Agent on the web — pick whichever fits the surface you want to show:

- **Widget** — the floating chat bubble in the corner of your site. Best for general-purpose support.
- **Embed** — an inline chat window that sits exactly where you want it on a page. Best for embedding the AI inside a specific app screen, help-centre page, or product detail page.
- **Chat Page** — a hosted, full-screen chat experience served by Quickchat (no installation, no code). Best when you want to share a link with someone (e.g., support email, internal Slack, beta testers) without touching their browser.

Install your chosen surface from **Channels → Your Website → Install**. The page has three sub-tabs: **Install** (choose how to add your AI Agent), **Appearance** (visual styling), and **Text Content** (the prompts and labels your visitors see). The **Install** tab opens with a method chooser, keeps availability and access controls in their own section, and shows a copyable **Scenario ID** that plugins and the API need.

## Optional setup tools

- [Compare deployment methods][public-tool-deployment-fit]. Check your declared channels, website access and required features against Quickchat AI setup options. This does not inspect your website or account.

- [Compare a sample page's HTML and Markdown][public-tool-page-surface]. Fetch initial HTML and Markdown content and tool links from a fixed Quickchat AI sample. This does not render JavaScript or inspect arbitrary websites.

## Widget

<div id="widget"></div>

The **Widget** allows you to embed your Quickchat AI Agent directly into your website, providing users with a seamless way to interact with the AI. The Widget is typically displayed as a chat bubble in the bottom-right corner of your webpage. When clicked, it expands into a chat window, enabling users to ask questions, get assistance, or access information.

### How to add the Widget to your website

Open **Channels → Your Website → Install**. The tab leads with **"How do you want to add your AI Agent?"** and lists the install methods, easiest first. Pick the one that matches your site:

- **WordPress** — install our free **[Quickchat AI Agent plugin](/docs/channels/wordpress)**, paste your Scenario ID, and the Widget appears automatically, with no theme code to edit.
- **Shopify** — add the Widget through your store's Theme Editor. See the [Shopify guide](/docs/channels/shopify).
- **Webflow, Wix & others** — copy one snippet and paste it into your site builder's site-wide custom code setting, applied to all pages. Don't use an Embed or HTML element on a page. See [Site builders](#site-builders).
- **Share a link instead** — don't install anything; share your hosted [Chat Page](#chat-page) link.
- **Install manually with code** — copy the raw **Widget** or **Embed** snippet and paste it into your HTML yourself.

Each method opens a focused, step-by-step panel with only the code or ID it needs.

Your **Scenario ID** sits at the top of the Install tab as a copyable field. It's the identifier that plugins and the API need, so copy it from here whenever a setup step asks for it.

#### Install manually with code

If you manage your own HTML, expand **Install manually with code** on the Install tab and:

1. Copy the **Widget** snippet.
2. Open your page's HTML file. On a site builder, use its site-wide code setting instead (see [Site builders](#site-builders)).
3. Paste the snippet just before the closing `</body>` tag on every page where you want the Widget to appear.

[Check a Widget snippet][public-tool-widget-snippet] against the Scenario ID you supply. The check reads the pasted code; it does not fetch your website.

[public-tool-widget-snippet]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/widget-snippet/?placement=docs-website-snippet-v1

#### Site builders

<div id="site-builders"></div>

On Webflow, Wix, Squarespace, Hostinger and similar builders, add the **Widget** once, through the builder's site-wide code setting:

1. Open the setting that adds code to every page. Builders call it **Custom code**, **Code injection**, **Footer code** or **Body end**.
2. Paste the Widget snippet there and apply it to **all pages**. If you can choose where the code goes, pick the footer or the end of the body. The snippet does not work in the head.
3. Publish your site. The chat bubble appears on every page.

:::caution
Don't add the Widget with an **Embed** or **HTML** element placed on a page. Many builders show those elements inside a small, separate frame, and the Widget can't open there. Even where it loads, it would only appear on that one page.
:::

Where the site-wide setting lives:

| Builder | Site-wide code setting |
|---|---|
| Webflow | **Site settings → Custom code → Footer code** |
| Wix | **Settings → Custom Code**, then **All pages** and **Body - end**. Needs a connected domain. |
| Squarespace | **Custom Code → Code Injection → Footer**. Core, Plus, Advanced and some legacy plans. |
| Hostinger Website Builder | **More (⋯) → Integrations → Custom code**. Scripts load at the end of the page automatically. |

Menus can change and may be translated in your builder's language. If your builder or plan has no site-wide code setting, share your [Chat Page](#chat-page) link instead.

#### Need a hand?

Not a developer? The Install tab has two shortcuts under **Need a hand?**:

- **Ask AI for help** — opens the in-app assistant, prefilled with a question about adding the Agent to your website.
- **Email instructions to a developer** — sends a teammate everything they need (the Widget snippet, your Scenario ID, and a link to this guide) so they can install it for you.

For more help, contact us at **contact@quickchat.ai**.

## Chat Page

<div id="chat-page"></div>

**Chat Page** is a hosted, full-screen version of your AI Agent that lives on a Quickchat URL. There's nothing to install — share the link and your visitors can chat with your Agent directly in their browser. Use it when:

- You want a chat experience but don't have a website (or don't want to touch its code).
- You're sharing the AI internally with a small group (beta testers, support team, sales prospects) and need an access-controlled link instead of a public widget.
- You want to send the AI as a follow-up channel in email, Slack, or your CRM.

Configure who can open the Chat Page from **Install → Chat Page Access** (see [Access control](#access-control) below).

## Start a new conversation

<div id="start-a-new-conversation"></div>

To reset the chat and start fresh:

- **Widget or Embed:** Open the chat and click the **pen-in-a-square button** in the top-right corner of the chat window.
- **Chat Page:** Select **New chat** in the sidebar, or use the pen-in-a-square button in the header.

This starts a fresh conversation with your AI Agent. The previous conversation remains in the **Inbox**. Closing and reopening the Widget or refreshing the page can resume the existing conversation. Asking the AI to "reset" or "clear the chat" does not start a new conversation. You do not need to clear browser cookies.

## Access control

<div id="access-control"></div>

The Install tab keeps access controls in a collapsible **Availability and access** section. Expand it to find two controls that apply to your deployment:

### Widget & Embed access

The toggle at the top of **Availability and access**. When **enabled**, the Widget and Embed scripts work normally on visitors' browsers. When **disabled**, the Widget and Embed are unavailable on your site even if the script is still pasted in — useful for taking the AI offline temporarily without removing the snippet, or for restricting public access while you keep the Chat Page open to invited users.

### Chat Page Access

Independent of the Widget & Embed toggle, you can restrict who can open the **Chat Page**:

- **Anyone** — the Chat Page URL is public. Anyone with the link can use it.
- **Invited users only**: People must sign in and have a role on this AI Agent to use the **Chat Page**. Choose **Chat User** for people who only need to chat.
- **Nobody** — the Chat Page is fully disabled.

The **Invite Chat Users** link opens **Settings → Organization → Team Members**. Select **Chat User** in the invitation form to give someone Chat Page access without dashboard access. Invitations require an available seat, and the legacy Basic plan does not allow role selection. See [Team Members and roles](/docs/team-and-roles) for plan limits.

## Customizing

The **Appearance** and **Text Content** sub-tabs let you tailor how the Widget, Embed, and Chat Page look and what copy your visitors see. All three deployment surfaces share these settings — change them once and they apply everywhere your Agent is deployed.

The right pane of the Install/Appearance/Text Content tabs has its own preview controls — toggle between **Widget**, **Embed**, and **Chat Page** previews, and between **Desktop** and **Mobile** viewports, to see your changes before you publish.

### Appearance

Visual styling for the chat surfaces, grouped into Branding, Size & Position, Theme, and Other Settings.

#### Branding

- **AI Agent Avatar** — the Agent's profile picture or logo: a single image used both in the chat header and on the launcher button (max 5 MB). This is one setting, not two: upload one image and it appears in both places (it replaces the old separate "header logo" and "launcher icon"). Every Agent starts with a built-in default avatar. **Reset to default** restores it, and deleting it shows no avatar at all. Available on every plan, including Free.

The **AI Agent Avatar** applies to the Widget, Embed, and Chat Page, but not to Discord, where the bot's avatar comes from its Discord app (see [Discord](/docs/channels/discord#bot-avatar)).

#### Size & Position

- **Launcher size** — **Classic**, **Input Only**, or **Small**. Controls how the chat launcher looks before it's opened.
- **Closing the launcher** — the **Classic** launcher has a small close button in its top-right corner, revealed on hover on desktop and always visible on touch devices. It hides the widget for the current page view only, and the launcher returns on the next page load. The other launcher sizes have no close button.
- **Launcher label** — shown only when **Small** is selected: custom text on the small launcher button (up to 25 characters), e.g. _"Ask AI"_ or _"Chat"_. Leave it empty for an icon-only launcher.
- **Widget position** — bottom-left, bottom-middle, or bottom-right.
- **Chat window dimensions** — width (300–700px) and height (400–1200px) of the chat window.
- **Draggable launcher** — let visitors drag the launcher to a different spot on the page. Useful when it covers important content.

#### Theme

Choose how the chat surfaces are colored:

- **Light** and **Dark** are fixed presets that look the same on every account.
- **Custom** unlocks a full palette of your own. When Custom is selected, color controls appear for the background, header and header text, accent (used for buttons such as the pre-chat start button, suggestion chips, and rating actions), message bubble and its text, AI message text, **link color**, the input field, borders, and more. Each color is checked for WCAG AA contrast against its background and warns you when a pairing is hard to read.

Branded header and accent colors live in the **Custom** theme. Light and Dark stay neutral presets, so switching between them never carries a custom color over.

Under **Transparency**, the **Background** setting chooses how see-through the chat window is. It works with every theme mode, and the theme supplies the tint:

- **Solid**: the chat window has a solid background. This is the default.
- **Glass**: the chat window turns see-through and the website behind it is blurred, like frosted glass. It is tinted white in **Light**, dark in **Dark**, and with your background color in **Custom**, where a header color that differs from the background keeps that color, so your branding still shows. **Glass opacity** sets how strongly the tint covers the page, from the lowest level that keeps the theme's text readable over any website (50% in **Light**, 65% in **Dark**, and based on your colors in **Custom**) up to 95%. If no opacity keeps the text readable with your **Custom** colors, the widget uses a solid background and the settings say why. **Glass** stays selected and applies again once you adjust the text or background colors for enough contrast.

Transparency applies to the Widget, including on phones, and to Embed. The full-page **Chat Page** always has a solid background. Visitors who turned on "Reduce transparency" on their device see the Solid style in Chrome and Edge, the browsers that pass this setting on to websites. In a browser that can't blur the page, Glass stays almost solid so the text remains readable.

When Custom is selected, the **Chat Page** also gets its own sidebar colors: **Sidebar background**, **Sidebar text**, **Sidebar hover**, and **Sidebar hover text**. These apply only to the full-page Chat Page view, not the Widget bubble or Embed. Leave the text colors unset and the Chat Page picks a readable color automatically for the background you choose.

You can also set the **corner radius** (roundness of bubbles, inputs, and buttons) and the **text size**. Both apply in every theme mode.

#### Other Settings

- **Voice Input** — let visitors record a spoken message with the microphone in the chat box. It is transcribed into the input so they can edit it before sending. Recordings stop automatically after two minutes (available on paid plans).
- **File Attachments** — let visitors attach an image or document to their message. On by default; turn it off to remove the attachment button from the chat box.
- **Auto-open Widget** — automatically open the Widget when the page loads.
- **Hide Quickchat AI Branding** — hide the "Powered by Quickchat AI" footer for a fully white-labeled experience (available on plans that include white-labeling).

To let visitors rate their conversations, open **Conversations → Insights → Conversation Rating**. Both its settings and results are on that tab; see [Conversation Rating](/docs/conversations/insights/conversation-rating).

### Text Content

Open **Channels → Your Website → Text Content** to edit the greeting and other visitor-facing text:

- **Header text** — text shown at the top of the chat window.
- **Welcome message** — the first message from the AI Agent at the start of each conversation (e.g., _"Hey, do you need help?"_).
- **Show as a pop-up** — toggle that shows the welcome message as a floating speech bubble next to the launcher (the "teaser" or "launcher message" some people ask about) to grab attention before the visitor clicks. The bubble shows the welcome message text itself, so edit that field to change what it says.
- **Conversation starters** — up to **3** example messages shown to the visitor before they start typing. Clicking one sends it as the first message — useful for nudging visitors towards your AI's strengths (_"How do I install the widget?"_, _"What integrations do you support?"_).
- **Input placeholder** — hint text in the empty message input.
- **Disclaimer text** — text shown behind the conversation, typically informing users they're talking to an AI. We recommend keeping this clear and visible.

The **Pre-chat Screen** section is below these fields on the same **Text Content** tab. Enable it there and edit its header, button, and message text.

The standard website Widget shows a heading, message and start button on this screen. It has no email or phone inputs and cannot require these details before the chat starts. [Smart Data Gathering](/docs/ai-agent/actions/smart-data-gathering) can ask for them during the conversation. Requiring contact details before allowing chat needs a separate website form or custom integration.

### Languages & translations

By default your Text Content is shown to every visitor exactly as you typed it. On paid plans you can add **per-language translations** so visitors see the widget in their own language.

1. Open the **Text Content** sub-tab and click **Translate** in **Other languages**. The **Translate widget text** panel opens, with your primary text alongside each translation as **Default (source)**.
2. Click **Add language** and pick a language. Quickchat AI generates a translation of your current text. Review and edit the fields (header, welcome message, conversation starters, input placeholder, pre-chat screen, disclaimer) for that language. Changes save automatically.
3. Any field you leave blank falls back to your default text, so you only translate what you want to change. If automatic translation fails, you can still enter the text yourself.

The number of languages you can add depends on your plan.

#### How a visitor's language is chosen

For the Widget and Embed, Quickchat picks the language in this order:

1. **An explicit override** you set in the loader: `_quickchat("language", "de")` (call it before `_quickchat("init", ...)`).
2. **Your page's `<html lang>` attribute** — for example `<html lang="de">` serves your German translation. This is the recommended approach: set `lang` correctly on each localized page and the widget follows automatically.
3. **The visitor's browser language**, then your **Default** text if nothing matches.

:::note
If a visitor's language has no translation, they always see your **Default** text. Nothing is ever left blank.
:::

### Advanced Features: Custom Parameters

The Quickchat AI Widget and Embed allow you to pass **custom parameters** on initialization. They can be used to:

- enhance analytics (they are available in the CSV export on the Quickchat platform)
- supply values for API Actions and, where permitted, personalize replies. The AI receives a filtered subset, not every parameter; see [Model context and authorization](/docs/api-reference/conversations/conversation-metadata#model-context)

Here are examples of useful custom parameters:

- `visitor_name`: `Mike`
- `customer_tier`: `VIP`
- `order_id`: `ord_123`

`visitor_name` is a recognized contact key. Custom keys such as `customer_tier` can be stored and used in Actions, but sending them alone does not guarantee that the AI will use them in its reply. Treat browser-supplied values as unverified input, not as authorization to access a customer's account.

In order to add custom parameters like the ones above, include the following like in the script you found under **Your Website > Install**.

Widget and Embed use the same call signature:

```typescript
_quickchat("custom_params", {
  "visitor_name": "Mike",
  "customer_tier": "VIP",
  "order_id": "ord_123",
});
```

These attributes are assigned to every new conversation; we recommend keeping this to a handful of keys.

:::tip
Custom parameters with snake_case names (e.g. `order_id`, `customer_tier`) can be injected directly into API Actions as `{{metadata_order_id}}`, `{{metadata_customer_tier}}`, etc. See [AI Action Variables](/docs/ai-agent/variables#custom-metadata-keys) for details.
:::

Example script:

**widget**

```html
<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>
```

**Embed**

```html
<div id="quickchat-embedded" style="height:600px;overflow:hidden;"></div>
<script>
  (function(e,a,d,i,c,t=a.createElement(d)){e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},t.src=i,t.async=1,a.body.insertAdjacentElement("beforeend",t)})(window,document,"script","https://bubble.quickchat.ai/chat.js","_quickchat");
  _quickchat("containerId", "quickchat-embedded");
  _quickchat("custom_params", {"visitor_name": "Mike", "customer_tier": "VIP", "order_id": "ord_123"});
  _quickchat("init", "abcdefghij");
</script>
```

## Embed

<div id="embed"></div>
<div id="iframe"></div>

**Embed** lets you place the Quickchat AI Agent directly inside a page as an inline chat window, instead of a floating bubble. Use it when you want the chat to sit in a specific spot on the page — a help-centre column, a contact page, an in-app sidebar, etc.

### How to add the Embed

1. **Get the Embed code**

   - Log into the **Quickchat AI App**.
   - Go to **Channels → Your Website** in the left sidebar.
   - Click the **Install** tab, then expand **Install manually with code**.
   - Copy the **Embed snippet** (it includes both the `<div id="quickchat-embedded">` container and the loader script).

2. **Open your website's HTML file, or the page in your site builder.**

3. **Paste the code**
   - Insert the Embed snippet into the `<body>` of your page.
   - Place it at the exact spot where you want the chat window to appear. The `<div>` controls the size — adjust the inline `style="height:600px"` to match the slot in your layout.
   - On a site builder, add a code or HTML element at the spot where the chat window should appear and paste the snippet into it.

:::note
The Embed only works when your builder puts the code directly into the page. Some builders, Wix for example, show HTML elements inside a separate frame, and the Embed can't load inside a frame. If the chat window doesn't appear on your published page, add the [Widget](#site-builders) through the site-wide code setting instead, or share your [Chat Page](#chat-page) link.
:::

[public-tool-deployment-fit]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/deployment-fit/?placement=docs-website-deployment-fit-v1

[public-tool-page-surface]: https://app.quickchat.ai/v1/api_core/public-question/quickchat/tools/page-surface/?placement=docs-website-page-surface-v1
