Skip to main content
It only takes a few minutes to install the Widget on your website. Once installed, you’ll be able to answer Frequently Asked Questions automatically in no-time. You have two ways to install your widget:
  1. For visitors on your website – the widget appears for anyone browsing your site. Conversations will be saved in the browser via a cookie.
  2. For both visitors and logged-in users – the widget is available across your website and inside your platform or app. The widget will show information like customer names and previous conversations across devices.
We recommend installing the Widget for both visitors and logged-in users to give everyone instant access to your team.

​
Installing the widget for visitors on your website

​
Getting your Chat Widget snippet

Let’s first get your chat widget snippet, before we can place it onto your website. Follow the steps below:
1

Open Integrations

Navigate to Integrations in the menu on the left-hand side of your Watermelon dashboard.
Install Widget Integrations
2

Open Chat Widget

Go to the section Channels, click on Chat Widget and select the widget you want to place on your website.
Install Widget Channel
3

Go to placement

In the widget settings, open the Placement tab.
Install Widget Placement
4

Copy your widget code

Under Code, you’ll find your installation snippet. Click copy code in the top-right corner to copy the code to your clipboard.
Install Widget Copy Code

​
Install yourself

Click Copy code and paste it before the </head> tag on every page you want the Widget to appear on your app and website. After adding the code, open your app and website and the Widget will appear. You can also use one of our guides to install the widget in a CMS:
Add your chat widget to your WordPress website so visitors can chat directly with your team or AI Agent. You can install the widget in two ways:
  1. By adding your snippet directly to your theme’s footer
  2. By using a plugin (recommended for most users)

​
Add your chat widget via your theme (Theme File Editor)

1

Open the Theme File Editor

In your WordPress admin panel, go to Tools → Theme File Editor.
Wordpress Start
2

Open the footer file

In the file list, expand Patterns and select Footer-default.php.
Wordpress Patterns Footer
3

Paste your chat widget code

Scroll to the bottom of the file and paste your chat widget snippet.Place it just before the closing </body> tag if present.
Wordpress Add Code
4

Save your changes

Click Update File at the bottom of the code editor to apply your changes.
Wordpress Add Code Save
5

Preview your site

Open your website in a browser (not the editor preview) to confirm your chat widget is now live.
Editing theme files directly requires caution. If you switch or update your theme, your changes may be lost.If you prefer a safer option, use the WPCode plugin instead.
1

Install WPCode

Install and activate the WPCode plugin (formerly Insert Headers and Footers).
Wordpress Wp Code Start
2

Create a new snippet

Go to Code Snippets → + Add Snippet.Hover over Add Your Custom Code (New Snippet) and click Use Snippet.
Wordpress Wp Code Add Custom Code
3

Configure your snippet

  • Give your snippet a title (e.g., “Chat widget”).
  • Set Code Type to JavaScript Snippet.
Paste your widget code in the Code Preview area.
Wordpress Wp Code Create Custom Snippet
4

Choose where to load the snippet

Under Insertion, select where the script should appear:
  • Header (most reliable)
  • Footer (better performance)
  • Or target specific pages using WPCode’s conditional logic
    Wordpress Wp Code Create Insertion Options
You can load the widget only on certain pages or for specific users, thanks to WPCode’s Smart Conditional Logic.
5

Save and activate

Click Save Snippet, then switch the toggle to Active.
Wordpress Wp Code Activate And Save
Your chat widget is now live on your site.

​
Installing the widget with Content Security Policy (CSP)

If your website uses a Content Security Policy (CSP) that restricts external styles, you need to allow Watermelon’s widget styles. The widget loads its CSS from: 
https://chatwidget-css.web.app
Add this domain to your CSP:
  • style-src-elem (recommended), or
  • style-src if you’re not splitting directives
Example 
Content-Security-Policy:
  style-src-elem 'self' https://chatwidget-css.web.app;
Without this, the widget may load without styling or will be blocked entirely.

​
Ask your developer to help (optional)

If you’d prefer someone else from your team to take care of the installation, you can add them to Watermelon so they have direct access to the code. Alternatively, you can share the code and this documentation guide with a developer, they’ll be able to handle it from there.

​
Installing the widget for both visitors and logged-in users

You can install the widget directly using our NPM package, which works with any framework. The package includes a script to embed the widget into your application. Add Watermelon to your application using the following command in your terminal: 
npm install watermelon-widget-injection --legacy-peer-deps
Get the variables from your system API response, localstorage or wherever you’ve saved them and pass them to the inject widget functionality. Example below
user_id is a required field to store conversation history accross devices and browsers
// ----- These are variables comming from your request ---- //
const first = response.me.first_name 
const last = response.me.last_name 
const email = response.me.email 
const phone = response.me.phone_number 
const userId = response.me.id.toString() // Required
To initialize Watermelon, copy and paste the code snippet into every page or a shared component where you want the Widget to appear. Make sure to do this in your client-side code. 
import {injectWidget} from "watermelon-widget-injection"; in the component

// Initialize and assign variables first before passing them to the function

injectWidget(widgetId, settingsId, 'prod', first, last, email, phone, userId)
setTimeout(() => {
  const iframe = document.querySelector('.watermelon-embed-frame') as HTMLIFrameElement;
  iframe.contentWindow.postMessage(
   {
    type: 'login',
    payload: {
     first_name: first,
     last_name: last,
     email: email,
     phone: phone,
     user_id: userId,
    }
   },
   '*' // Security target origin
  );
}, 10000)
The timeout is set to 10 seconds in this example. Replace with the duration that represents how long it takes before the user is logged in, in milliseconds
Click Copy code and paste it before the </body> tag on every page you want the Widget to appear on your app and/or website. Then edit the code to send Watermelon the email address, name, or phone number of the user who is currently logged in. After adding the code, open your app and the Widget will appear.

​
Passing values for custom fields

In addition to the standard user attributes (first name, last name, email, phone and user ID), you can also pass custom fields to Watermelon. These fields allow you to attach additional information about the logged-in user. Custom fields must first be created in your Watermelon dashboard before they can be sent from your application. Once the fields exist, you can include them in the login payload when initializing the widget. Field names within the Watermelon application can be stored with spaces, uppercase and lowercase letters. And in the custom fields page there will also be displayed internal name which is how the name of field needs to be passed in the payload in order to map it correctly.
For instance if the custom field in the Watermelon custom fields page is stored as ‘Company Name’, internal name would result in ‘company_name’
Example: sending custom fields Below is a simple example showing how to pass custom fields along with the standard login payload. In order to pass the custom fields value, they need to be added to the initial postMessage payload and then sent to the iframe using a second postMessage call after the widget is initialized. Field values passed in that payload need to be of string value. If in your system the value is stored as a number or boolean, make sure to convert it to a string before sending it to Watermelon using methods like toString(). 
const iframe = document.querySelector('.watermelon-embed-frame') as HTMLIFrameElement;

const companyName = 'Watermelon'
const yearOfEstablishment = 1998.toString() // example of value stored as a number in your system, but needs to be converted to string before sending to Watermelon
const companyField = 'Support'

const chatWidgetCustomFields = [
				{
				    name: "company_name",
				    value: companyName
				 },
				 {
                 	name: "year_of_establishment",
                 	value: yearOfEstablishment
                 },
				{
				    name: "company_field",
				    value: companyField
				},
			];

iframe.contentWindow.postMessage(
{
  type: 'login',
  payload: {
    first_name: first,
    last_name: last,
    email: email,
    phone: phone,
    user_id: userId,

    // Custom fields
    custom_fields: {
        company_name: chatWidgetCustomFields.companyName
        company_establishment: chatWidgetCustomFields.yearOfEstablishment,
        company_field: chatWidgetCustomFields.companyField

    }
  }
},
'*'
);

​
Shut down your user sessions on user logout

This step should take place either right before or after the logout call — the order doesn’t matter. Two postMessage calls are required:
  1. The first one hides the widget from the top-level iframe.
  2. The second one tells the iframe app to clear everything from local storage and reset its state, such as conversation ID and contact ID.
const iframe = document.querySelector('.watermelon-embed-frame') as HTMLIFrameElement;
window.postMessage(
  {
   type: 'logout',
   payload: {}
  },
  '*'
);
// @ts-ignore
iframe.contentWindow.postMessage(
  {
   type: 'logout'
  },
  '*'
);