OSM Templates: Configuration and Customization

This guide explains how to configure MoEngage’s pre-defined On-site Messaging templates and how to customize their HTML code.

Template Overview

MoEngage On-site Messaging campaigns offer various pre-defined templates. The following table describes each template and its common uses.


Template Type	Description
Simple Image Popup	Displays an image in the center of the page over a translucent overlay. Use this template when all message content is part of the image.
Center Popup with one button	Displays an image and a button in the center of the page over a translucent overlay. Use this template to add a call to action (CTA) to your pop-up message.
Sticky Banner with Header, Text, and Button	This sticky banner can appear at the top or bottom of the page. It allows you to add a header, text, button, and a small image.
Lead Gen Template	Use this template to capture information from your website visitors, such as email addresses or mobile numbers. The captured information is saved in MoEngage user profiles.
Sticky Banner with Image	This sticky banner can appear at the top or bottom of the page. Use it to display a simple image banner.
Survey Popup	Use this center pop-up template to display Typeform surveys through MoEngage.
Survey Sticky Banner	Use this sticky side banner template to display Typeform surveys non-intrusively in a corner position on your website (e.g., bottom-left, bottom-right).
Side Banner with Image	Use this side banner template to convey information non-intrusively by placing simple images in a corner position on your website (e.g., bottom-left, bottom-right).
Sticky Header with Text and Button	This sticky banner can appear at the top or bottom of the page. Use it to display text messages with a call to action (CTA).
Side Banner with Image and Button	This side banner template allows you to add an image and a button. You can place it non-intrusively in a corner position on your website.
Simple Sticky Header	This sticky banner can appear at the top or bottom of the page. Use it to display a simple text message.

Images

Upload high-quality images under 2 MB for On-site Messaging campaigns. Larger image files can cause delays in message display, especially for users on slower internet connections.

Image Aspect Ratios

The following table lists recommended aspect ratios for images in each On-site Messaging template. You can adjust image dimensions and styles in the code editor.


Template Name	Recommended Aspect Ratio (width : height)
Simple Image Popup	Message size adjusts to fit most image sizes. Recommended aspect ratios include 1:1, 2:3, or 3:2. Use images at least 400x400 pixels to prevent distortion. Popular dimensions are 600x600, 400x600, and 600x400 pixels.
Center Popup with one button	Message size adjusts to fit most image sizes. Recommended aspect ratios include 1:1, 2:3, or 3:2. Use images at least 450x450 pixels to prevent distortion. Popular dimensions are 600x600, 400x600, and 600x400 pixels.
Sticky Banner with Header, Text, and Button	This template includes a small icon image. The recommended aspect ratio is 5:3. Popular dimensions are 150x90 and 250x150 pixels.
Lead Gen Template	To add a background image to this template, go to Container > Background > Image. Use images with dimensions of 400x500 pixels.
Sticky Banner with Image	Use wider images that occupy most of the desktop web width. Popular dimensions are 1024x80 and 1024x50 pixels. Create separate campaigns for desktop and mobile web when using this template.
Survey Popup	Add only a Typeform survey URL here.
Survey Sticky Banner	Add only a Typeform survey URL here.
Side Banner with Image	Use images with an aspect ratio of 3:4 or 3:5 and at least 300x400 pixels to prevent distortion on larger devices. Create separate campaigns for desktop and mobile web when using this template.
Sticky Header with Text and Button	Adding an image is not recommended for this template.
Side Banner with Image and Button	Use images with an aspect ratio of 3:4 or 3:5 and at least 300x400 pixels to prevent distortion on larger devices. Create separate campaigns for desktop and mobile web when using this template.
Simple Sticky Header	Adding an image is not recommended for this template.

Supported Image Types

On-site Messaging templates support .png, .jpeg, and .gif image formats.

Template Responsiveness

If you use large images with uncommon aspect ratios, create separate campaigns for desktop and mobile web. This ensures proper display across all devices.

Configure Background Color

You can add a background color to your on-site messages. You can also remove it for a transparent message. Define a background color by navigating to Container > Background, and then select one of the following options:

Solid: To add a background color to your template.
Transparent: To make the message background transparent.
Image: To add an image to your template background. This is not generally recommended.

Screenshot of background color options in MoEngage platform.

Customize Templates in Code View

You can edit the HTML code of any existing MoEngage template using the code view. Click the Code View button, as shown in the following image.

Screenshot of the Code View button in MoEngage.

After you edit the HTML, save your changes to preview them. If you completely replace the MoEngage template HTML, the UI Editor will not be available for customizing your template. When you build custom HTML templates, consider the following guidelines for tracking clicks and closing templates:

For close button: Add the moe-inapp-close CSS class to your template. The MoEngage SDK closes the template only when this class is present. Do not use custom JavaScript functions to close templates, as this can cause inconsistent behavior.
For tracking clicks: Add the moe-inapp-click CSS class to your template. This class is essential for MoEngage to track clicks and attribute them to your campaign.
To close the template and redirect users after a call to action (CTA) click or link, add both the moe-inapp-close and moe-inapp-click classes to the HTML template.

Lead Gen Template

The Lead Gen template enables you to capture information from your website visitors, such as email addresses, mobile numbers, or other preferences. This data is saved directly to your MoEngage user profiles for re-engagement.

Popular Use Cases

Use the Lead Gen template for the following common scenarios:

Capture email addresses from website visitors for future email campaigns.
Collect mobile numbers to send SMS messages later.
Record user names for personalized communication.
Gather user interests, such as preferred brands or products.

Create a Lead Gen Campaign

To create a Lead Gen campaign in MoEngage:

On the template selection page, select the Lead Gen template.

Screenshot showing Lead Gen template selection.

Configure your On-site Messaging campaign. For details, see Create On-site Messaging Campaigns.
To capture user input, map the input field from the Lead Gen template to a user attribute. In the second step of campaign creation, click the input widget on the template, and then configure the user attribute where this input will be saved.

Screenshot showing how to map input widget to user attributes.

To hide an input field, select the input widget and choose to hide it.

Screenshot showing how to hide an input widget.

View Captured Data

After users submit the Lead Gen template, MoEngage automatically tracks and saves the data. This data is visible in the user profile.

MoEngage also tracks the MOE_RESPONSE_SUBMITTED event for every submission from a Lead Gen template. This data appears in the user profile, as shown in the following image.

By default, MoEngage captures the First Name and Email Address user attributes. You can add more input fields by modifying the template content.

Example: Add a Phone Number Field

To add an input field for the phone number after the Email Address field, use the following code: JavaScript

<input
   placeholder="Phone Number"
   class="input-container moe-element"
   data-id="INPUT3"
   id="TEXT_INPUT_3"
   data-user="u_mb"
   />
<label class="moe-error-text invisible">This field is required</label>

To make the phone number field mandatory, add required to the input tag.

Example: Display an Error Message

To display an error message if a mandatory field is left blank, use the following JavaScript: JavaScript

<label class="moe-error-text invisible">any error message</label>

Example: Add Custom Validation

The Lead Gen template validates email addresses by default. To add custom validation to existing or new fields, modify the <input> tag for that field and add the following attribute: JavaScript

data-input-validation-type="any name"

Then, add your custom validation logic to the isFormDataValid() method. For example, the following code validates an Indian mobile number: JavaScript

//Mobile number validation
function isMobileNumberValid(mobile) {
  const mobileRegex = /^[789]\d{9}$/;  return mobileRegex.test(mobile);
}

Call the isMobileNumberValid() method within isFormDataValid() to validate mobile numbers. The SMS Sign-Up template in MoEngage On-site Messaging allows you to collect consent from users for SMS notifications. For more information about North America compliance, see SMS for North America Region. MoEngage offers two SMS Sign-Up templates:

Fullscreen: SMS Sign-up with image
Popup: SMS Sign-up without image

Prerequisites

Before you begin, be aware of SMS compliance for the North American region. For details, see SMS Regulations in the US.

During On-site Messaging campaign creation, select an SMS Sign-Up template.

Configure your On-site Messaging campaign. For details, see Create On-site Messaging Campaigns.

Configure the template for web and mobile platforms as needed.
Set up the button, image, and text content.
Configure the legal text. MoEngage provides the following default text: By signing up for text messages, you agree to receive recurring automated promotional and personalized text messages (cart reminders) at the phone number provided. Consent is not a condition to purchase. Msg & data rates may apply. Msg frequency varies. Reply HELP for help and STOP to cancel.
Set up your Terms of Service as required.
Set up your Privacy Policy as required.

For Web

When you use templates for desktop or web:

Provide a valid mobile number.
Click the button to confirm your subscription for notifications.

For Mobile

When you use templates for mobile: Configure the button to get consent by adding the following URL in the Action field of the button: sms:+11234567890?&body=START

Parameter	Description
sms	Provide the mobile number to receive consent and notifications.
body	Add the Opt-In keyword. For details about keywords, see Configure Subscription & Keywords.

View Captured Data

You can view the captured data in MoEngage user attributes. MoEngage tracks the MOE_RESPONSE_SUBMITTED event for every submission from an SMS Sign-Up On-site Message. The user profile displays the attribute and its status.

Guide

OSM Templates (HTML Editor)

OSM Templates: Configuration and Customization

Template Overview

Images

Image Aspect Ratios

Supported Image Types

Template Responsiveness

Configure Background Color

Customize Templates in Code View

Lead Gen Template

Popular Use Cases

Create a Lead Gen Campaign

View Captured Data

Example: Add a Phone Number Field

Example: Display an Error Message

Example: Add Custom Validation

Prerequisites

For Web

For Mobile

View Captured Data

​OSM Templates: Configuration and Customization

​Template Overview

​Images

​Image Aspect Ratios

​Supported Image Types

​Template Responsiveness

​Configure Background Color

​Customize Templates in Code View

​Lead Gen Template

​Popular Use Cases

​Create a Lead Gen Campaign

​View Captured Data

​Example: Add a Phone Number Field

​Example: Display an Error Message

​Example: Add Custom Validation

​SMS Sign-Up Template

​Prerequisites

​Create an SMS Sign-Up Campaign

​Configure SMS Sign-Up Templates

For Web

For Mobile

​View Captured Data

OSM Templates: Configuration and Customization

Template Overview

Images

Image Aspect Ratios

Supported Image Types

Template Responsiveness

Configure Background Color

Customize Templates in Code View

Lead Gen Template

Popular Use Cases

Create a Lead Gen Campaign

View Captured Data

Example: Add a Phone Number Field

Example: Display an Error Message

Example: Add Custom Validation

SMS Sign-Up Template

Prerequisites

Create an SMS Sign-Up Campaign

Configure SMS Sign-Up Templates

View Captured Data