> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add the MerchantAI Widget to Any Website or Platform

> Add the MerchantAI chat widget to any website by pasting one script tag — no build step or dedicated engineer needed, works on every platform.

The MerchantAI JS widget lets you add an AI support associate to any website by pasting a single `<script>` tag into your HTML. There is no build step, no framework requirement, and no engineer needed. The widget loads asynchronously so it never blocks your page, and every aspect of its appearance is configurable directly from the MerchantAI dashboard without touching your code again.

## Get your widget snippet

<Steps>
  <Step title="Open the Deploy section in your dashboard">
    Log in to the MerchantAI dashboard and navigate to **Deploy → Widget**. Your unique script snippet is shown here, pre-populated with your workspace ID.
  </Step>

  <Step title="Copy the script snippet">
    Click **Copy snippet** to copy the full script tag to your clipboard.
  </Step>

  <Step title="Paste it before the closing body tag">
    Open the HTML template (or theme file) for every page where you want the widget to appear. Paste the snippet immediately before the closing `</body>` tag.
  </Step>

  <Step title="Save and publish — the widget appears automatically">
    The widget loads asynchronously on page load. No additional configuration in your codebase is required. Visitors will see the chat button in the corner of the page as soon as your changes are live.
  </Step>
</Steps>

## Script snippet

Here is what the widget snippet looks like. Replace `YOUR_WORKSPACE_ID` with the value shown in your dashboard (it is pre-filled when you copy from there).

```html theme={null}
<!-- MerchantAI Widget -->
<script
  src="https://widget.merchantai.io/v1/loader.js"
  data-workspace-id="YOUR_WORKSPACE_ID"
  async
></script>
```

The `async` attribute ensures the script is fetched in the background and does not block rendering of the rest of your page content.

## Customising the widget

You control the full appearance of the widget from the **Widget settings** section of your dashboard. None of these changes require you to update the script snippet — you edit once in the dashboard and the widget reflects the change immediately.

<CardGroup cols={2}>
  <Card title="Colours" icon="palette">
    Set a primary colour to match your brand. The widget button, header, and accent elements all inherit this value.
  </Card>

  <Card title="Position" icon="arrows-to-dot">
    Choose **bottom-right** or **bottom-left** to avoid conflicting with other on-page elements like cookie banners or live-chat triggers.
  </Card>

  <Card title="Avatar" icon="circle-user">
    Upload a custom avatar image for your AI associate — a brand logo, illustrated character, or team photo all work well.
  </Card>

  <Card title="Greeting message" icon="message">
    Set the opening message visitors see when they open the widget. Use it to guide them toward the questions you most want the agent to handle.
  </Card>
</CardGroup>

## Works on any platform

Because the widget is a plain HTML script tag, it works on every platform that lets you edit page source or add custom code.

<CardGroup cols={3}>
  <Card title="WordPress" icon="wordpress">
    Add the snippet via a custom HTML block, your theme's `footer.php`, or a plugin like **Insert Headers and Footers**.
  </Card>

  <Card title="Webflow" icon="code">
    Paste the snippet into **Project Settings → Custom Code → Footer Code** to add it site-wide.
  </Card>

  <Card title="Squarespace" icon="square">
    Use **Settings → Advanced → Code Injection → Footer** to embed the snippet on every page.
  </Card>

  <Card title="Custom HTML" icon="file-code">
    Any static site or server-rendered app — paste the snippet before `</body>` in your base layout template.
  </Card>

  <Card title="Any CMS" icon="globe">
    If your CMS lets you inject a script tag into the page footer, MerchantAI will work there too.
  </Card>
</CardGroup>

## Knowledge sources for non-Shopify sites

When you use the JS widget on a website that is not connected to Shopify, your agent draws its knowledge from the sources you configure in the MerchantAI dashboard:

* **Website crawl** — MerchantAI can crawl your published website to index your content automatically.
* **Uploaded files** — Upload PDFs, DOCX files, or plain text documents such as product guides, FAQs, or policies.
* **Q\&A pairs** — Manually add specific question-and-answer pairs for precise control over how common questions are answered.

Shopify-specific workflows such as cart review, checkout links, and order lookup are not available on non-Shopify sites. The agent focuses on answering questions based on the knowledge sources you provide.

<Tip>
  Before adding the snippet to your live site, paste it into a staging or development version of your website first. This lets you verify the widget appears correctly, test a few questions against your knowledge sources, and confirm the position and colours look right — all without affecting real visitors.
</Tip>

<Note>
  The JS widget is available on **all plans, including the Free plan**. You can embed the widget and start handling visitor questions straight away during your free trial.
</Note>