Overlay Messaging is Optimove's channel for delivering personalised pop-up messages across your website and mobile app from a single campaign. Unlike legacy pop-up channels tied to a single platform, Overlay Messaging treats web and mobile as one — a campaign you create once reaches your customer on whichever surface they're active on, without managing separate channels or duplicating your setup.

If you are currently using Webpage Pop-ups or In-App Messaging, Overlay Messaging is designed to be the unified successor to both channels. There is no set timeline for sunsetting Webpage Pop-ups or In-App Messaging, and no immediate action is required — but if you are interested in transitioning, speak to your CSM about what migration would look like for your setup.

Before marketers can use Overlay Messaging, your development team will need to integrate both the Optimove Web SDK and Mobile SDK, as Overlay Messaging is cross-platform and requires both to be active for full coverage. See the Overlay Messaging Developer Documentation for setup instructions.

Prerequisites

Overlay Messaging requires configuration before campaigns can go live. Contact your CSM or CSE to ensure the following are in place:

• Web SDK and Mobile SDK both integrated: Overlay Messaging is a single cross-platform channel. If only one SDK is implemented, messages will only reach customers on that surface.
• Overlay Messaging enabled on your tenant.
• Domain and brand mapping configured: Overlay Messaging requires your domains and brands to be correctly mapped to your tenant before messages can be delivered, for both web and app (native). You manage this on the Domain Management page — see Domain Management.
• Push permission (mobile, triggered campaigns only): for triggered Overlay Messaging on mobile, your customers must have granted push notification permission. Customers who have not granted this will not receive triggered overlays on mobile. Push uses the same integration as mobile push and is requested within your app's own permission flow — it is not handled automatically by the SDK.

How Overlay Messaging works

Sessions

Overlay Messaging delivery is organised around sessions. A session persists for a configurable duration (default: 1 hour; minimum: 15 minutes), and determines when a customer is eligible to receive a new scheduled (session) message.

A session resets automatically when a customer logs in (via the OOTB login event or any event that sets their user ID), which causes the SDK to fetch the next available session message. Your developers can also reset a session programmatically — for example, on logout. A session also restarts when the SDK is first initialised and has never loaded before, or when the configured session duration expires.

Single scheduled message per session

For scheduled campaigns, Overlay Messaging delivers one message per customer per session. At any given moment, only the single most recent eligible scheduled message is shown. If multiple scheduled campaigns are eligible, they are prioritised by execution time, most recent first.

Triggered (immediate) campaigns are not subject to this limit. Multiple triggered messages may be delivered within a single session, based on customer behaviour.

Cross-device deduplication

Message state is synchronised across devices. If a customer dismisses or interacts with a message on one device, that message is permanently deleted and will not appear on any of their other devices.

State synchronises at the start of each overlay session and at least once per hour on mobile.

Message types

Scheduled messages

Scheduled messages are sent as part of standard scheduled campaigns and retrieved by the SDK at the start of a session.

• Messages are shown in most-recent-first order, based on execution time.
• Messages are valid for 1 day (TTL = Time to live) after the campaign execution date and time. If the message is not fetched within 1 day from the execution date and time, it expires and is not shown.
• Expired messages are retained for a maximum of 14 days.

Scheduled message scenarios:

Triggered messages

Triggered messages are sent in response to a customer action or event in real time.

• Triggered messages have a TTL of 2 minutes. If the message is not fetched within 2 minutes of being sent, it expires and is not shown.
• Multiple triggered messages can be displayed within a session — if a customer performs multiple trigger actions (e.g. multiple deposits), each can generate a message shown in sequence. Each message is subject to its own 2-minute TTL independently.
• On mobile, triggered Overlay Messaging requires push permission to have been granted by the user. Customers who have not granted push — or who are otherwise unreachable for push — will not receive triggered overlays on mobile. Scheduled overlays are unaffected. This matches how in-app messaging behaves today: a customer can be opted in to receive overlay/in-app messages but still miss a real-time (triggered) message if they're unreachable for push.

For guidance on setting up triggered campaigns, see Creating Event-Triggered Campaigns.

Setting up triggers for web and mobile

Because Overlay Messaging is cross-platform, triggers must be configured to fire correctly across both web and mobile surfaces.

• Web events are typically reported via the OptiWeb SDK using reportEvent calls on your site.
• Mobile events are reported via the OptiMobile SDK on iOS and Android.

To ensure a triggered Overlay Messaging campaign reaches a customer on whichever surface they're currently active on, the same trigger event must be reportable from both your web integration and your mobile SDK integration. If a trigger is only wired up on web, mobile customers will not receive triggered overlays, and vice versa.

Work with your development team and CSE to confirm that all trigger events intended for use with Overlay Messaging are implemented on both surfaces before going live.

Campaign execution options

Overlay Messaging supports the full standard suite of Optimove campaign execution capabilities.

Definitions:

• Conditional Execution — Adds a real-time eligibility check at the point of sending. Optimove coordinates with your internal systems via API to confirm whether each customer should receive the campaign at execution time. Useful for compliance checks, promotion activation, or any scenario where eligibility may change between campaign setup and send time.
• Delayed Execution — Sends the message after a defined delay from the point the campaign trigger fires. Available within triggered campaign setup. See Creating Event-Triggered Campaigns.
• Uncompleted Sequence (coming soon) — Re-targets customers who entered a campaign flow but did not complete the intended action.
• Server-side Events (coming soon) — Triggers campaign delivery based on events reported server-side, rather than from the SDK.
• Frequency & Scheduling Settings — Controls how often a customer can receive messages and within what time windows campaigns are active.

Creating an Overlay Messaging campaign

Overlay Messaging campaigns are created in Optimove's Campaign Builder. The creation flow follows the same steps as for any other channel. The following articles cover the full process:

• Drafting a Campaign — saving a campaign in progress
• How to Create a Campaign — the core campaign creation walkthrough
• Creating Event-Triggered Campaigns — for real-time triggered delivery
• Using Conditional Campaign Execution — adding eligibility checks at execution time

When selecting the channel during campaign setup, select Overlay Messaging.

Multi-brand campaigns

If you are running a campaign across multiple brands, each brand must be added individually when setting up the campaign in Campaign Builder. A single campaign configuration does not automatically broadcast to all brands — you need to select and configure each brand as part of the campaign setup.

Good to know

How overlays appear

Overlays use a consistent, standardised presentation:

• They appear in the centre of the screen.
• They size automatically — up to 90% of the screen on mobile, and up to 600px wide on desktop — based on your image plus padding. To make an overlay larger or smaller, adjust the image and the padding.
• Custom animations (e.g. slide-in), custom positioning (e.g. side or bottom), explicit size presets (e.g. full-screen or alert), and restyling the close (×) button aren't currently available.

Delivery

• Overlay Messaging delivers to web and app together. A campaign reaches the customer on whichever surface they open first — there's no option to target only the browser or only the app.

Not currently supported

• Server-side events and uncompleted-sequence triggers — planned (see Campaign execution options above).
• Zero-party data collection forms (e.g. surveys, email sign-up).
• Preference Centre topics.

Template editor

Overlay Messaging templates are created using Optimove's visual editor (pop-up mode). An HTML editor option is also available for teams who prefer to work directly in code.

Templates are multi-brand and cross-tenant: a single template can be used across brands and tenants, reducing duplication for clients operating multiple properties.

Personalisation with Liquid

You can personalise message content using Liquid, Optimove's templating language. Liquid is available in the visual and HTML editors alike, allowing you to write personalisation logic directly alongside your content without switching to a separate mode.

Liquid allows you to:

• Insert customer attributes (e.g. first name, loyalty tier, account balance)
• Apply conditional logic to show different content to different customers within a single template
• Use content functions such as upper/lower/title case formatting

For Liquid syntax and usage guidance, refer to the Personalisation Tags and Conditional Language articles on Academy.

Data Connections

Data Connections allow you to pull in dynamic external data at the point of message delivery — for example, a live balance, an active promotion, or a personalised product recommendation. Data Connections are accessed from within the personalisation modal in the template editor.

For an overview of compatibility and setup, see the Data Connections Overview and Channels & Data Connections Compatibility Overview.

Smart preview

Smart preview lets you preview how a message will render for a specific customer record, so you can verify that personalisation tags and conditional logic are resolving as expected before sending.

Send test

You can send a test message from the template editor to preview how it appears on device before going live. Send test supports multi-brand, allowing you to test the same template across different brand configurations in a single step.

A few things to know when testing:

• A send test behaves like a triggered campaign.
• If Overlay Messaging is enabled on both web and mobile, the test appears on whichever surface you open first. To test both, send one test and open it on the web, then send another and open it in the app.
• On web, you need a trigger event in place to surface the test — a page load, a login, or any event the SDK emits (tip: send the test, then refresh the page).
• On mobile, the customer must be opted in to push, because the test works like a triggered message. If a mobile test doesn't appear, check push permission for that customer first.
• Send test uses the hashed customer ID where ID hashing is implemented; Smart Preview always uses the OptimoveId.

Rendering

Web and mobile share a common renderer — what you see in the campaign editor preview accurately reflects how the message will appear on both platforms. On web, the overlay uses Shadow DOM for CSS isolation, meaning your website's styles do not affect the message and the message's styles do not affect your page.

Metrics

Overlay Messaging reports the following metrics, aggregated across web and mobile: