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

# Chat widget customization

> Learn how to embed, style, and personalize your chat widget. This guide covers iframe integration, custom buttons, layout adjustments with CSS, and link previews — everything you need to tailor the widget to your website.

## Embed a a widget in an iframe

You can embed the Watermelon chat widget in an iframe to keep it isolated and fully functional within any section of your website.

### **Set widget placement to embedded**

In Watermelon, go to the desired chat widget in apps, once you are in the chat widget go to **Placement** and change your Chat Widget setting to **Embedded**.

<Warning>
  Turn Automatically open the widget to On, this makes sure the embedded widget is open by default.
</Warning>

### **Add an iframe to your page**

Add the following code to your HTML where you want the widget to appear:

```javascript theme={null}
<iframe
  style="border-radius: 15px; width: 100%; height: 700px; border: none;"
  srcdoc='
    <script async type="module" src="<https://chatwidget-prod.web.app/embed/init.iife.js>"
    data-watermelon-widget-id="your-widget-id"
    data-watermelon-settings-id="your-settings-id"></script>
  '>
</iframe>
```

* **srcdoc** defines the chat widget script that will load inside the iframe.
* **width** and **height** control the size—adjust these values to fit your layout.
* Replace your-widget-id and your-settings-id with the IDs found under the chat widget settings under **Placement** in Watermelon.

### **Place the iframe in your page structure, example HTML:**

```html theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Watermelon Chat Widget</title>
</head>
<body>
  <div>
    <!-- Your existing website code -->
    <iframe
      style="border-radius: 15px; width: 100%; height: 700px; border: none;"
      srcdoc='
        <script async type="module" src="<https://chatwidget-prod.web.app/embed/init.iife.js>"
        data-watermelon-widget-id="your-widget-id"
        data-watermelon-settings-id="your-settings-id"></script>
      '>
    </iframe>
  </div>
</body>
</html>
```

### **Test the integration**

Open your page in a browser and check that the Watermelon chat widget loads correctly inside the iframe.

## **Customizing an embedded widget with your own CSS**

When you embed the Watermelon widget using an \<iframe>, it appears at full width and height by default. This means it takes up the entire page and can overlap elements like your header or footer. You can adjust its appearance with your own CSS. Here’s an example:

```javascript theme={null}
<iframe
  style="border-radius: 15px; width: 100%; height: 700px; border: none;"
  srcdoc='
    <script async type="module"
      src="<https://chatwidget-prod.web.app/embed/init.iife.js>"
      data-watermelon-widget-id="your-widget-id"
      data-watermelon-settings-id="your-settings-id"></script>
  '>
</iframe>
```

### **Explanation**

* border-radius: 15px; — rounds the corners of the iframe.
* width: 100%; — makes the widget fit the container width.
* height: 700px; — limits the height so it doesn’t fill the entire screen.
* srcdoc — loads the chat widget script inside the iframe.

<Warning>
  Replace your-widget-id and your-settings-id with your actual values from the chat widget settings → Chat widget → **Placement** in Watermelon.
</Warning>

### **Implementation tips**

* Place the \<iframe> inside a container element that fits your layout.
* For responsive design, use relative units like vh (viewport height) or CSS media queries.
* Always test on different screen sizes and browsers to confirm the layout looks correct.

## **Ensuring the preview image is visible in the Chat Widget**

When the **‘Unfold URLs’** option is enabled, links shared in the chat widget can show a preview, including an image. This image appears only if it’s defined in the meta tags of the linked page. Below you’ll find how to make sure the preview image is displayed correctly.

<Warning>
  **Conditions for displaying a preview image**

  A preview image will only appear when the shared URL includes an image defined in the website’s meta tags. If no image is found, only the link text will be shown in the chat widget.
</Warning>

### **Add a preview image to the meta**

1. **Open your page’s HTML**

   Edit the page via your CMS (for example WordPress, Wix, or Lightspeed) or directly in the HTML code.
2. **Locate the \<head> tag**

   Meta information is always placed between \<head> and \</head>.
3. **Add the Open Graph tag**

   Insert the following code to define the preview image:

   ```javascript theme={null}
   <meta property="og:image" content="URL-to-your-image.jpg" />
   ```

   Replace URL-to-your-image.jpg with the full path to the image you want to display.
4. **Save and publish**

   Save the changes and republish your page. Then share the URL in a chat widget to confirm that the image appears.

### **Troubleshooting**

If the image does not appear after adding the tag, check:

* **Image size** – use at least **1200 × 630 px** for optimal display.
* **File type** – allowed formats: .jpg, .png, or .gif.
* **Cache** – clear your browser or CMS cache to ensure the latest version is loaded.

## **Trigger the chat widget with a custom button**

You can open the chat widget from any button on your website using a few lines of HTML and JavaScript.

1. **Add the button**

   Place a button where you want visitors to open the chat:

   ```javascript theme={null}
   <button id="openChatButton">Open Chat</button>
   ```

   You can adjust the text, style, or position to match your website design.
2. **Add the JavaScript**

   Add this script to your webpage, just before the closing \</body> tag:

   ```javascript theme={null}
   <script>
     document.getElementById('openChatButton').addEventListener('click', function() {
       window['watermelonWidget'].emit('open-widget');
     });
   </script>
   ```

   This script listens for a click on your custom button and triggers the chat widget to open.
3. **Test it**

   Load your page and click the button to verify that the widget opens correctly.
