# Documentation Access to Agents
Source: https://moengage.com/docs/documentation-access-to-agents
Access MoEngage documentation in formats suited for AI agents, LLMs, and automation tools.
Use the options below to give AI coding assistants and language models access to MoEngage documentation with less overhead than loading full HTML pages.
## Quick start
* **AI coding assistants (Claude Code, Cursor, etc):** Use the [MoEngage Docs MCP server](https://www.moengage.com/docs/mcp) for the best experience. It lets your assistant search and fetch documentation from within the IDE.
* **Chat interfaces (ChatGPT, Claude.ai):** Add `.md` to any docs page URL and share it in your conversation to get plain markdown instead of the full site.
* **Project rules and custom instructions:** Add MoEngage's [llms.txt](https://www.moengage.com/docs/llms.txt) URL to your AI tool’s rules so it has an index of relevant MoEngage pages.
* **Agent capabilities:** Use the [skill.md](https://www.moengage.com/docs/skill.md) URL or `npx skills add https://www.moengage.com/docs` so agents know what they can do with MoEngage and what inputs or constraints apply.
## MCP server
The [MoEngage Docs MCP server](https://www.moengage.com/docs/mcp) gives AI agents and coding assistants direct access to MoEngage documentation and references through the Model Context Protocol. Use it to bring MoEngage knowledge into tools like Claude, Cursor, and other MCP-compatible clients.
The MoEngage Docs MCP (Model Context Protocol) server connects your AI agents to MoEngage’s docs and developer resources. Configure the MoEngage Docs MCP server in your IDE or AI chat to get in-context help for your MoEngage integration.
> [!NOTE]
>
> For more on the Model Context Protocol, see the [MCP documentation](https://modelcontextprotocol.io/introduction).
If your AI agent supports MCP, you can add the MoEngage Docs MCP server so it has access to MoEngage’s APIs and SDKs. The MoEngage Docs MCP server lets you:
* Get quick answers about MoEngage APIs, features, and implementation
* Search documentation without leaving your editor
* Find code samples and recommended patterns for typical use cases
* Debug issues using docs and SDK references
* Write code that integrates your app with MoEngage
* Report incorrect or outdated documentation to the MoEngage docs team
## Installation
To set up the MoEngage Docs MCP server, use the contextual menu on any page and click **Connect**.

Alternatively, you can pick your IDE or AI chat provider and follow the steps below.
> [accordion] Cursor
>
> 1. Open **Cursor** and open the `.cursor` directory in your project root. Create it if it doesn’t exist. This is where Cursor’s project configuration lives.
> 2. Open the `mcp.json` file in `.cursor`. Create it if it doesn’t exist. This file holds MCP server configuration for the project.
> 3. Add the following to `mcp.json`:
>
> ```json mcp.json theme={null}
> {
> "mcpServers": {
> "MoEngage Docs": {
> "url": "https://www.moengage.com/docs/mcp"
> }
> }
> }
> ```
> 4. Save the file.
> 5. Restart Cursor.
> [accordion] Claude Desktop (Local)
>
> > [!NOTE]
> >
> > Claude Desktop uses `npm` to run the MoEngage Docs MCP server. You need **Node.js** installed. See [Node.js downloads](https://nodejs.org/en/download/) for details.
>
> 1. Open **Claude Desktop**.
> 2. Go to **File > Settings** (Windows) or **Settings** (macOS).
> 3. Open the **Developer** tab.
> 4. Click **Edit Config**.
> 5. Open `claude_desktop_config.json`. This file controls MCP servers for Claude Desktop.
> 6. Add the following to `claude_desktop_config.json`:
>
> ```json claude_desktop_config.json theme={null}
> {
> "mcpServers": {
> "moengage-docs": {
> "command": "npx",
> "args": ["-y", "mcp-remote", "https://www.moengage.com/docs/mcp"]
> }
> }
> }
> ```
> 7. Save the file.
> 8. Restart Claude Desktop.
> [accordion] Claude Desktop (Remote)
>
> > [!NOTE]
> >
> > Remote MCP in Claude Desktop is currently in beta.
>
> ### Enterprise and team plans
>
> 1. Open **Claude Desktop**.
> 2. Go to **Admin settings > Connectors**.
> 3. Scroll to the bottom of the section.
> 4. Click **Add custom connector**.
> 5. Fill in:
> * **Name**: MoEngage Docs MCP
> * **Remote MCP server URL**: `https://www.moengage.com/docs/mcp`
> 6. Click **Add**.
>
> ### Pro and max plans
>
> 1. Open **Claude Desktop**.
> 2. Go to **Settings > Connectors**.
> 3. Scroll to the bottom of the section.
> 4. Click **Add custom connector**.
> 5. Fill in:
> * **Name**: MoEngage Docs MCP
> * **Remote MCP server URL**: `https://www.moengage.com/docs/mcp`
> 6. Click **Add**.
> [accordion] Claude Code
>
> Run the following command in your terminal:
>
> ```bash theme={null}
> claude mcp add --transport http MoEngage-docs https://www.moengage.com/docs/mcp
> ```
> [accordion] VS Code
>
> 1. Create a `.vscode/mcp.json` file with the following content:
>
> ```json mcp.json theme={null}
> {
> "servers": {
> "MoEngage Docs": {
> "type": "http",
> "url": "https://www.moengage.com/docs/mcp"
> }
> }
> }
> ```
> 2. Save the file.
> 3. Restart VS Code.
## Usage (Tools)
The MoEngage Docs MCP exposes the following tools:
* **`search_mo_engage`** — Searches MoEngage’s documentation and knowledge base. Use it for broad or conceptual queries such as “how to authenticate” or “rate limiting”. Results include contextual content with titles and links to the relevant docs.
* **`query_docs_filesystem_mo_engage`** — Runs read-only, shell-like commands (`rg`, `grep`, `find`, `tree`, `ls`, `cat`, `head`, `jq`, and other text utilities) against a virtualized filesystem that contains the MoEngage documentation pages and OpenAPI specs. Use it for exact keyword or regex matches, exploring the docs structure, or reading the full content of a page by its path. Nothing runs on your machine or network — the filesystem is an in-memory sandbox backed by documentation content.
* **`submit_feedback`** — Reports a problem with a documentation page to the MoEngage docs team. Use it when a page is incorrect, outdated, confusing, or incomplete, or when an example is broken.
A typical agent workflow starts with `search_mo_engage` for conceptual questions, then uses `query_docs_filesystem_mo_engage` to read the full page (append `.mdx` to the path returned by search) or to run precise regex searches.
## Example Prompts
After you connect the MCP server, ask your AI assistant questions in plain language. The assistant searches MoEngage documentation and answers with citations, so you don't have to switch to the docs site.
> [tab] Marketers and Product Teams
>
> Use a chat client such as Claude Desktop to get answers about campaigns, segments, and analytics:
>
> * "How do I set up a push campaign with send time optimization?"
> * "What is the difference between event-triggered campaigns and Flows? When should I use each?"
> * "How do I create a segment of users who purchased in the last 30 days but haven't opened the app since?"
> * "How are conversion goals attributed in campaign reports?"
> * "Walk me through setting up a WhatsApp campaign, including the prerequisites."
> [tab] Developers
>
> Use an IDE assistant such as Claude Code or Cursor to get integration help in context:
>
> * "Integrate MoEngage push notifications into my Android app. Follow the current SDK setup steps."
> * "My events aren't showing up in MoEngage. Check the Web SDK docs and help me debug the tracking calls."
> * "Write a request for the MoEngage Track User API with the required headers and payload."
> * "Which iOS SDK version added support for the notification service extension, and what changed?"
> * "Compare the React Native and Flutter SDK setup steps for in-app messages."
## Per-page markdown
Append `.md` to any docs page URL to get a markdown version of that page. You get content only, without HTML, nav, or scripts, which uses fewer tokens than the full page.
For example, for the [API Reference introduction](/docs/api/introduction) in markdown, use:
```txt theme={null}
https://www.moengage.com/docs/api/introduction.md
```
## Site-wide endpoints
These endpoints follow the [llms.txt standard](https://llmstxt.org/). You can use these endpoints for markdown-formatted content.
| Endpoint | Description | Size |
| - | - | - |
| [`/llms.txt`](https://www.moengage.com/docs/llms.txt) | Page index with short descriptions for the whole site | Varies |
| [`/llms-full.txt`](https://www.moengage.com/docs/llms-full.txt) | Full content of all pages. Prefer section-level endpoints when possible | Large |
## skill.md
The `skill.md` file describes what AI agents can do with MoEngage in a structured, machine-readable format. It makes capabilities, required inputs, and constraints explicit so agents can use your product more reliably.
**URL:** [https://www.moengage.com/docs/skill.md](https://www.moengage.com/docs/skill.md)
The file follows the [skill.md specification](https://agentskills.io/specification) and is kept in sync with the documentation so agents stay aligned with current MoEngage features and APIs.
> [!TIP]
>
> `llms.txt` and `skill.md` both help agents use MoEngage documentation, but they do different things.
>
> * **`llms.txt`** is a directory: it lists documentation pages with descriptions so agents know where to look.
> * **`skill.md`** is a capability summary: it describes what agents can accomplish with your product, what inputs they need, and what constraints apply.
### Using skill.md with agents
Agents can load MoEngage’s capabilities into their context with the [skills CLI](https://www.npmjs.com/package/skills):
```bash theme={null}
npx skills add https://www.moengage.com/docs
```
This adds MoEngage’s skill description to the agent so it can take actions on behalf of users (e.g. answering integration questions or suggesting API usage).
> [!TIP]
>
> Use the `skill.md` URL or the command above in your own AI setup so you get better, more accurate assistance when working with MoEngage.
### What’s in skill.md
The MoEngage `skill.md` file is generated from the documentation and typically includes:
* **Metadata** — Product name, description, and version.
* **Capabilities** — What agents can do with MoEngage (e.g. campaigns, segments, SDK integration).
* **Skills** — Concrete actions grouped by area (APIs, SDKs, data, etc.).
* **Workflows** — Step-by-step procedures for common tasks.
* **Integration** — Supported tools and services.
* **Context** — High-level overview of MoEngage documentation and concepts.
For the exact schema and fields, see the [agentskills.io specification](https://agentskills.io/specification).
# MoEngage Documentation
Source: https://moengage.com/docs/index
Explore MoEngage documentation: User Guide, Developer Guide, API reference, SDKs, and AI agent access.
Merlin AI
## Say what you need. **Merlin AI drafts, builds, and explains.**
Previous capability
Next capability
There's more beyond the prompt box.
Predictions, campaign decisioning, send-time optimization, and A/B testing.
Explore the guide
[Open](/docs/user-guide/ai-and-intelligence/overview)
**Learn the**
**Integrate the**
### Work with **agents**
[claude](https://claude.ai/directory/moengage-mcp)
[openai](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server#personal-setup-per-user)
**Connect your**
**Pick up**
## Can't find what you need? **Ask us.**
Search the docs
[Contact Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard)
# Data Centers in MoEngage
Source: https://moengage.com/docs/user-guide/data/key-concepts/data-centers-in-moengage
MoEngage operates multiple global data centers. Find out which one your account uses and how it determines your SDK and API endpoint URLs.
MoEngage maintains multiple data centers, and you will be part of a specific data center when you sign up with us. We will provide you with the dashboard access URL, SDK, and REST API endpoints based on the data center.
Before you sign up, you can go ahead and consult your MoEngage Onboarding Manager to understand which Data Center will suit your needs. Once you have signed up, you can identify your Data Center from the Dashboard URL.
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.To learn more about different MoEngage data centers.
# List of Data Centers
The following table describes the data center name, URL, and the REST API hostname associated with the data center.
| Data Center Name | Dashboard URL | REST API Host |
| - | - | - |
| DC-01 | [https://dashboard-01.moengage.com](https://dashboard-01.moengage.com) | [https://api-01.moengage.com](https://api-01.moengage.com) |
| DC-02 | [https://dashboard-02.moengage.com ](https://dashboard-02.moengage.com) | [https://api-02.moengage.com](https://api-02.moengage.com) |
| DC-03 | [https://dashboard-03.moengage.com ](https://dashboard-03.moengage.com) | [https://api-03.moengage.com](https://api-03.moengage.com) |
| DC-04 | [https://dashboard-04.moengage.com](https://dashboard-04.moengage.com) | [https://api-04.moengage.com](https://api-04.moengage.com) |
| DC-05 | [https://dashboard-05.moengage.com](https://dashboard-05.moengage.com) | [https://api-05.moengage.com](https://api-05.moengage.com) |
| DC-06 | [https://dashboard-06.moengage.com](https://dashboard-06.moengage.com) | [https://api-06.moengage.com](https://api-06.moengage.com) |
> [!NOTE]
>
> Once captured in a workspace, data cannot be migrated across a new workspace to ensure data resides in the correct data center.
# Significance of having different data centers
Hosting multiple instances of our application and distributing the signups across multiple data centers helps us optimize our services by distributing the amount of data in each data center. Also, there could be compliance requirements to host your user data in a specific geography.
You can only sign up for your MoEngage account in any one of the data centers, and the user data you track with MoEngage will get saved in the same data center.
# Signing up for region-specific data centers
When you sign up with MoEngage, you can sign up with any of our data centers.
> [!NOTE]
>
> We recommend that you let us select a data center for you if there are no specific requirements around saving data in specific geographies so that we can provide optimized services to you throughout your engagement with us.
If you have data privacy or residency requirements that require you to store your user's data in a specific geographical region, please sign-up as per the below recommendations:
| Region Where Data Should Reside | Data Center to Choose | Status |
| - | - | - |
| US | DC-01, DC-04 | Both data centers are actively onboarding |
| EU | DC-02 | Actively onboarding |
| India | DC-03 | Actively onboarding |
| Singapore | DC-05 | Unavailable for new onboarding |
| Indonesia | DC-06 | Actively onboarding |
If there are no requirements to save your user's data in a specific region, then signing up with any data center has no impact. All our data centers are identical and support similar functionalities, SLAs, and latencies.
# Re-direction of data to different data centers from SDK
When you use MoEngage SDK for tracking your mobile app/website user data, integrate as per your data center and the corresponding integration steps as mentioned in the SDK documentation below:
[Android](https://www.moengage.com/docs/developer-guide/android-sdk/sdk-integration/basic-integration) | [iOS](https://www.moengage.com/docs/developer-guide/ios-sdk/sdk-integration/basic/sdk-integration) | [Web](https://www.moengage.com/docs/developer-guide/web-sdk/web-sdk-integration/basic-integration/web-sdk-integration)
The table below lists the mapping between the different data centers, dashboard URLs, and the data center keys that you should pass when integrating the respective SDKs.
| Data Center | Dashboard URL | Android / iOS | Web |
| - | - | - | - |
| Data Center 1 | [https://dashboard-01.moengage.com/](https://dashboard-01.moengage.com) | DATA_CENTER_01 | DC_1 |
| Data Center 2 | [https://dashboard-02.moengage.com/](https://dashboard-02.moengage.com) | DATA_CENTER_02 | DC_2 |
| Data Center 3 | [https://dashboard-03.moengage.com/](https://dashboard-03.moengage.com) | DATA_CENTER_03 | DC_3 |
| Data Center 4 | [https://dashboard-04.moengage.com/](https://dashboard-04.moengage.com) | DATA_CENTER_04 | DC_4 |
| Data Center 5 | [https://dashboard-05.moengage.com/](https://dashboard-05.moengage.com) | DATA_CENTER_05 | DC_5 |
| Data Center 6 | [https://dashboard-06.moengage.com/](https://dashboard-06.moengage.com) | DATA_CENTER_06 | DC_6 |
## Identifying the REST API Endpoint for your data center
When you send data to MoEngage through our REST APIs, you need to use the API Endpoints as per the below table.
| Data Center | Dashboard URL | REST API Host |
| - | - | - |
| Data Center 1 | [https://dashboard-01.moengage.com/](https://dashboard-01.moengage.com) | [https://api-01.moengage.com/v1/](https://api-01.moengage.com/v1/) |
| Data Center 2 | [https://dashboard-02.moengage.com/](https://dashboard-02.moengage.com) | [https://api-02.moengage.com/v1/](https://api-02.moengage.com/v1/) |
| Data Center 3 | [https://dashboard-03.moengage.com/](https://dashboard-03.moengage.com) | [https://api-03.moengage.com/v1/](https://api-03.moengage.com/v1/) |
| Data Center 4 | [https://dashboard-04.moengage.com/](https://dashboard-04.moengage.com) | [https://api-04.moengage.com/v1/](https://api-04.moengage.com/v1/) |
| Data Center 5 | [https://dashboard-05.moengage.com/](https://dashboard-05.moengage.com) | [https://api-05.moengage.com/v1/](https://api-05.moengage.com/v1/) |
| Data Center 6 | [https://dashboard-06.moengage.com/](https://dashboard-06.moengage.com) | [https://api-06.moengage.com/v1/](https://api-06.moengage.com/v1/) |
> [!NOTE]
>
> Please use the same REST API as the registered data center. For example, when registering an app on any data center (say DC-01), you must integrate the REST API for DC-01.
# Event Naming Conventions
Source: https://moengage.com/docs/user-guide/data/key-concepts/event-naming-conventions
Follow best practices for naming events in MoEngage to keep tracking consistent and clear. Covers naming patterns, formatting, and examples.
# Overview
When it comes to naming events, it's beneficial to follow some conventions to ensure consistency and clarity across your tracking implementation. Clear and intuitive event names help in effectively communicating the purpose of the event being tracked when working collaboratively or analyzing event data at a later stage. By using human-readable event names, you can ensure that the events are self-explanatory and do not require additional explanation or deciphering.
# Best Practices
Here are some event naming conventions to consider:
* **Use clear and descriptive names**: Choose event names that accurately describe the user action being tracked. Make sure the name concisely communicates what happened, without being overly technical or ambiguous.
* **Be consistent**: Establish a set of naming conventions for events and stick to them throughout your tracking implementation.
* **Use lowercase and underscores or dashes**: Most operating systems are case-sensitive; always use lowercase for event names and separate multiple words with underscores (\_) or dashes (-) for better readability. For example, "video_playback_started" or "checkout_completed".
* **Use verbs for action-based events**: Start event names with verbs to indicate actions. For example, "user_signed_in", "item_added_to_cart", or "form_submitted".
* **Include relevant object or context information**: If an event involves a specific object or context, include it in the event name. For example, "product_purchased" or "article_shared".
* **Avoid using abbreviations or acronyms**: While abbreviations might save characters, they can also introduce confusion. It's generally better to use complete words that are easily understood by all team members.
* **Keep event names concise**: Try to keep event names as short as possible while still maintaining clarity. Long event names can be unwieldy and difficult to work with.
You can adjust the above conventions to fit your specific needs and requirements. The key is to choose a convention that aligns with your team's understanding and enables easy interpretation of the event data.
# Recommendations
* We recommend naming an event with a minimum of **5** characters.

User/Event property values are limited to **512** characters in length.
* Non-ASCII characters need to be escaped.
* Do not start your user or event properties with "moe". MoEngage may not track event names starting with "moe".\
**Example**:
* moe_addtocart
* addToCart
* AddToCart
* Add_to_cart
* Add-to-Cart
* Whenever possible, use the same names across your mobile apps and websites for consistency.
* Group similar events with a common prefix. For example, "booking_initiated", "booking-dates-selected", "BookingRoomSelected", and "Booking_completed".
* Use an underscore or a hyphen between the words instead of spaces. Space-filled attributes cannot be read and may cause your use case to fail.
* Creating every user action as an event will make it harder to find meaningful answers in a pool of events. Employ more general events rather than specific ones. For example, instead of three individual events such as "video_start", "video_pause", and "video_end", use a "video_watched" event with "Duration" as a property value.
* Do not capture screen loads or unloads, button clicks, or form submissions. Instead, record user actions that are in line with your business objectives.
* Do not capture page views as events, or page URLs as event properties. You can get better insights into how people use your product than by the pages they visit.
* For objects datatype attributes, please maintain a different name for the object attribute and the attributes or keys inside the object.
# Prohibited Characters
Do not use any of the following special characters or symbols in your event names:
* \$ dollar sign
* . dot
* \< left angle bracket
* \+ plus sign
* % percent
* \> right angle bracket
* \< left angle bracket
* % percent
* \> right angle bracket
* ! exclamation point
* \` backtick
* & ampersand
* \* asterisk
* \# pound
* \| pipe
* \{ left curly bracket
* ? question mark
* " double quotes
* \= equal sign
* } right curly bracket
* / forward slash
* : colon
* emojis
* \ backslash
* blank spaces
* @ at sign
* ' single quotes
This list is meant to help you avoid common errors while naming events. If you have any questions, reach out to the support team.
# Reserved Keywords
* MoEngage standard events are usually tracked as 'moe\_\*eventname'.\*As mentioned earlier, avoid naming your events starting with *moe.*
* Refer to the [list](/docs/user-guide/data/event-data/derived-events-and-attributes) of standard/derived events tracked by MoEngage and avoid duplication in your custom events
# Overview - Data
Source: https://moengage.com/docs/user-guide/data/key-concepts/overview-data
Start here to understand data in MoEngage — user properties, events, and the different ways to integrate and manage your tracking data.

**Data**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3388003-data)
Data is any information that you wish to store, analyze and track. When you onboard with MoEngage, one of the first things to do would be to integrate your data into MoEngage through various options. This data typically consists of user properties and events used to create segments and run analytics and campaigns.
## Types of Data
* **User** - User data contains information about the user and is available in the User Profile for any user in the system. For every user, the following information is available in MoEngage - MoEngage derived attributes or standard attributes and any custom user properties that can be sent to MoEngage. MoEngage generates derived attributes based on user behavior. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile) and [Derived User Properties](/docs/user-guide/data/user-data/derived-user-attributes).
* **Device**- A user can have multiple devices associated with them, and this is stored in MoEngage as Device Data. Device-specific attributes such as the advertising identifier (the unique user ID associated with a mobile device to help advertisers personalize their offerings) are available in the User Profile.
* **Event**- An event is an occurrence tied to user behavior or action. For example, logging in, logging out, viewing a web page, adding an item to a cart, and so on. Event data contains information about such events. Events are classified as follows:
* **Derived Events** - MoEngage generates a list of standard events based on user actions and behavior called derived events. For more information, refer to [Derived Events](/docs/user-guide/data/event-data/derived-events-and-attributes).
* **Custom Events** - You can define the events that are specific to your business and track them with MoEngage.
* **Auxiliary**- Auxiliary data is temporary data that you can import to MoEngage. For more information, refer to [Auxiliary Data](/docs/user-guide/data/imports/file-based-imports/auxiliary-data).
## Data Operations
The following operations can be performed with Data:
* **Create and Update** - Data can be created and updated in MoEngage using the following:
| Type | SDK | S2S APIs and Bulk Upload APIs | File Imports (CSV, S3, and SFTP) | Partner Integrations (CDPs and CRMs) |
| - | - | - | - | - |
| User | Create, Update | Create, Update | Create, Update | Create, Update |
| Device | Create, Update | Not Supported | Not Supported | Not Supported |
| Event | Create | Create | Create | Create |
* **Delete** - Data can be deleted from MoEngage using the GDPR/CCPA API. For more information, refer to [Erase API](https://www.moengage.com/docs/api/gdpr-ccpa/gdpr-ccpa-overview).
## Data Management
MoEngage equips you with a Data Management Dashboard to help you manage your data effectively. You can:
* Block or hide unnecessary events, event properties, and user properties
* View all the event and user properties integrated with MoEngage
* Add meaningful display names for attributes (event and user) to help your marketers understand their purpose
* Specify allowed data types for attributes - this will help show the relevant operators pertaining to the permitted data types during segmentation and analytics.
For more information, refer to [Data Management](/docs/user-guide/settings/data-management/overview-data-management).
## Data Exports
All user events and campaign events that have been received or generated by MoEngage can be exported to Partner tools using:
* [Data Warehouse Exports](/docs/user-guide/data/exports/events/data-warehouse/s3-exports) (AWS, GCP, Redshift, BigQuery)
* [MoEngage Streams](https://www.moengage.com/docs/api/data/moengage-streams) to Partner tools.
The exported data can be analyzed further to glean insights into user behavior, preferences, and what have you.
# Dashboard Overview
Source: https://moengage.com/docs/user-guide/getting-started/initial-setup/dashboard-overview
Get started with the MoEngage dashboard. Access user segments, targeted campaigns, analytics, and insights all from one central interface.
From the MoEngage dashboard, you can create user segments, send targeted campaigns for your app or website, and access analytics including uninstalls, acquisitions, retention cohorts, campaign performance, and conversion data.

# Navigating the Dashboard
The left navigation sidebar gives you access to the main sections of MoEngage:
* **Campaigns & Channels** — Create and manage campaigns across push, email, SMS, in-app, and other channels.
* **Flows** — Build automated multi-step journeys for your users.
* **Analyze** — Access analytics, cohorts, funnels, and campaign performance reports.
* **Segment** — Create and manage user segments.
* **Settings** — Configure your workspace, channels, integrations, and team access.
At the top right you'll find:
* Your **profile icon** — Access My profile, switch appearance, and manage your workspace settings.
* The **workspace switcher** — Switch between workspaces or add a new one.
* **Need help** — Access documentation, videos, and support.
# First-Time Setup
The first time when you log in to MoEngage, the Dashboard is available as a Test environment. You can integrate MoEngage with your app or web and get user or event data.
Make your environment Live after integration or tracking of events is complete and your app is released or your website is live.
# Live and Test Environments
Every MoEngage workspace has two environments: **Test** and **Live**. You switch between them using the toggle on the top navigation bar.

Each environment has its own Workspace ID, available under **Settings** > **Account** > **General settings**. The two IDs are similar but not identical. Copy the Workspace ID from the environment you are working in. All other settings are independent between the two environments.
| | Test | Live |
| - | - | - |
| **Purpose** | Integration, debugging, and QA | Production user data and campaigns |
| **Data routing** | SDK sends data when build is DEBUG | SDK sends data when build is RELEASE |
| **Team permissions** | All team members have full feature access | Restricted by role to prevent accidental changes |
| **Data processing** | Faster — helps speed up initial integration testing | Standard |
> [!NOTE]
>
> Apart from Team management, Billing, and your Profile settings, all other settings are separate for the Test and Live environments and available in the sidebar.
When you begin integrating any MoEngage SDKs, all your testing of user data or events data is visible in the Test environment. This enables you to test your integration and verify data before you go live or release your app or web.
# Workspaces
A workspace is the core unit in MoEngage — it holds your campaigns, user data, analytics, and settings for a single app or business unit. You can have multiple workspaces under one login.
## Switch Between Workspaces
Click the workspace arrow in the top navigation bar to see all workspaces you have access to, then click a workspace name to switch to it.

> [!NOTE]
>
> * You'll only see workspaces you've been invited to. If you're invited to only one workspace, the switcher won't appear.
> * Switching workspaces may log you out if the two workspaces use different login methods or have different 2-step verification settings. For more information, refer to [Automatic Logout](/docs/user-guide/settings/account/security/automatic-logout).
## Add a New Workspace
1. Click the workspace arrow and then click **+ Workspace**.
2. Enter a workspace name and click **Add**.
> [!NOTE]
>
> Workspace names cannot be changed after creation. Workspaces cannot be deleted.
For workspace configuration — time zone, conversion goals, API keys, and more — refer to [Workspace Settings](/docs/user-guide/settings/account/general-settings/workspace-settings).
# Configure Workspace Language
The MoEngage workspace language is set to English by default, but you can change it to any language supported by MoEngage.
> [!NOTE]
>
> MoEngage currently supports Japanese and Brazilian Portuguese.
> [!NOTE]
>
> This is an Early Access feature. To enable it for your workspace, contact your CSM or [raise a support ticket](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
Perform the following steps to configure the workspace language:
1. Navigate to **My profile** > **Preferences** > **Language preferences**. 
2. In the **Workspace language** list, select your preferred language. 
Your workspace switches to the selected language.
# Set Up the Dashboard
Configure your workspace by clicking **Settings** in the left navigation sidebar.

## Account
* [**General Settings**](/docs/user-guide/settings/account/general-settings/workspace-settings) — Configure workspace ID, time zone, conversion goals, locales, and workspace classification.
* [**API Keys**](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard) — Manage Data API keys and other API credentials.
* [**Team Management**](/docs/user-guide/settings/account/team-management/manage-members) — Invite team members and manage access roles.
* [**Audit Logs**](/docs/user-guide/settings/account/audit-logs/audit-logs) — View a log of all actions taken in your workspace.
* [**Security**](/docs/user-guide/settings/account/security/overview) — Configure login methods, 2-step verification, SSO, and more.
* [**Billing**](/docs/user-guide/settings/account/billing/usage-details) — Add payment methods, access billing history, and view usage details across workspaces.
## Analytics & Segmentation
* [**Query Settings**](/docs/user-guide/settings/analytics-and-segmentation/query-settings) — Control user merging, event deduplication, and real-time delete and merge propagation for Analytics and Segmentation queries.
* [**Acquisition Tracking**](/docs/user-guide/settings/analytics-and-segmentation/acquisition-tracking) — Set up install attribution and measure campaign effectiveness.
* [**Uninstall Tracking**](/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking) — Detect app uninstalls and gain insights into user churn.
## Data
* [**Data Management**](/docs/user-guide/settings/data-management/overview-data-management) — View tracked events and user properties, monitor quotas, and manage auto-blocked data.
* [**Computed Traits**](/docs/user-guide/data/computed-traits/computed-traits-overview) — Create dynamic user properties auto-calculated from event data.
## Channels
* [**Push**](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/configure-mobile-push) — Configure mobile push notification credentials and delivery settings.
* [**Email**](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/email-onboarding) — Configure email sender details, SMTP settings, and authentication.
* [**SMS**](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/other-settings/configure-sms-mms-and-rcs-general-settings) — Configure SMS connectors and general delivery settings.
* [**WhatsApp**](/docs/user-guide/campaigns-and-channels/whatsapp/getting-started-with-whatsapp/configure-whatsapp) — Configure your WhatsApp business account and message templates.
* [**Delivery Controls**](/docs/user-guide/settings/channels/delivery-controls/frequency-capping) — Set frequency capping, DND, push throttling, and campaign audience limits across channels.
* [**Preference Management**](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/preference-management-for-push-notifications) — Manage channel-level opt-outs to prevent sending campaigns to unsubscribed users.
## Advanced Settings
* **Accessibility Controls** — Configure accessibility features for your MoEngage workspace.
* [**Control Groups**](/docs/user-guide/settings/advanced-settings/global-control-group) — Set up a global control group to measure the true impact of your campaigns.
* [**Tags**](/docs/user-guide/settings/advanced-settings/manage-tags) — Create and manage tags to organize campaigns and content.
* [**Locales**](/docs/user-guide/settings/advanced-settings/locales) — Configure language and regional settings for content personalization.
* [**Content API**](/docs/user-guide/settings/advanced-settings/add-a-content-api) — Connect external content APIs for dynamic, real-time personalization.
* [**Custom Domain**](/docs/user-guide/settings/advanced-settings/configure-custom-domain-link-branding) — Set a branded domain for campaign links and tracking URLs.
* [**Authorization Configuration**](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20) — Configure OAuth 2.0 access tokens for custom connectors and Content API integrations.
* [**UTM Tracking**](/docs/user-guide/settings/advanced-settings/configure-general-utm-parameters-at-account-level) — Set default UTM parameters to track campaign traffic in external analytics tools.
* [**Conversion And Attribution**](/docs/user-guide/settings/advanced-settings/campaign-attribution-settings) — Configure conversion windows and attribution rules for your campaigns.
## Reports and Alerts
* [**Alert Management**](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/overview-alert-management) — Set up alerts for token expirations, campaign failures, and performance drops.
* [**Dashboard Subscriptions**](/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions) — Schedule and receive automated dashboard reports via email.
* [**Proactive Insights**](/docs/user-guide/settings/reports-and-alerts/proactive-insights-settings) — Configure RFM insights, confidence intervals, and analysis preferences for Proactive Insights.
## Miscellaneous
* [**Inform**](/docs/user-guide/settings/miscellaneous/settings-inform) — Configure API credentials and user property preferences for MoEngage Inform.
* [**Push**](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/configure-mobile-push) — Configure mobile push notification credentials and delivery settings.
* [**Email**](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/email-onboarding) — Configure email sender details, SMTP settings, and authentication.
* [**SMS**](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/other-settings/configure-sms-mms-and-rcs-general-settings) — Configure SMS connectors and general delivery settings.
* [**WhatsApp**](/docs/user-guide/campaigns-and-channels/whatsapp/getting-started-with-whatsapp/configure-whatsapp) — Configure your WhatsApp business account and message templates.
* [**Delivery Controls**](/docs/user-guide/settings/channels/delivery-controls/frequency-capping) — Set frequency capping, DND, push throttling, and campaign audience limits across channels.
* [**Preference Management**](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/preference-management-for-push-notifications) — Manage channel-level opt-outs to prevent sending campaigns to unsubscribed users.
## Offer Decisioning
* [**Offering Attributes**](/docs/user-guide/decisioning/offer-decisioning/create-offering-attribute) — Define and manage attributes used to personalize offers across campaigns.
# Next Steps
Your dashboard is now fully set up to start creating segments and launching targeted campaigns. For more information, refer to [creating user segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments) and [campaigns](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels).
# Log In to MoEngage
Source: https://moengage.com/docs/user-guide/getting-started/initial-setup/log-in-to-moengage
Log in to your MoEngage workspace using a password, Google Sign-In, or SSO. Covers dashboard authentication via last-used workspace or login-to-a-different-workspace flows, MCP authentication, 2-step verification setup, email OTP verification, account lockout, and access recovery in case of issues with password and 2-step verification configuration.
MoEngage separates authentication (who you are) from authorization (which workspaces you can access). An access issue with one workspace, such as a revoked SSO account or a workspace-level policy change, does not affect your other workspaces.
Choose your login path:
* **Log in directly** to your last-used workspace.
* **Verify your identity once** and select from any workspace you're authorized to access.
> [!TIP]
>
> **Prerequisites**
>
> * **First login (as an invited user)**: Complete a one-time setup before you log in for the first time after being invited to a workspace. For more information, refer to [Finish Your Workspace Setup as an Invited User](/docs/user-guide/getting-started/initial-setup/sign-up-with-moengage-or-create-a-new-account-in-moengage#finish-your-workspace-setup-as-an-invited-user).
> * **Subsequent logins**: Keep your workspace login page URL handy. To find your login URL, refer to [Find Your Login Page](#find-your-login-page) below.
> * **2-step verification**: If your workspace requires 2-step verification, set it up on your device before you log in. For more information, refer to [Set Up 2-Step Verification on Your Device](#set-up-2-step-verification-on-your-device).
## Find Your Login Page
Each workspace resides in a specific data center (for example, DC-01 at `dashboard-01.moengage.com`). Use the global login page to find your login URL:
**1. Open the global login page**
Go to [dashboard.moengage.com](https://dashboard.moengage.com/v4/#/auth).

**2. Enter your work email**
In the **Work email** box, type your email address.
**3. Continue to your data center**
Click **Continue**. MoEngage redirects you to your last-used workspace's login page on the correct data center.

> [!NOTE]
>
> Your email address is pre-filled on the login page for verification.
> [!NOTE]
>
> If your last-used workspace has Single Sign-On (SSO) enabled, MoEngage redirects you automatically to that data center's Login with Single Sign-On page.
>
> 
To log in to a different workspace, click **Login to a different workspace** on either page. Refer to [Log Into a Different Workspace](#log-into-a-different-workspace) for the complete flow.
> [!NOTE]
>
> If you land on the wrong data center's login page, click **Find your data centre** to return to the global login page and re-enter your email address.
Bookmark your login URL for faster access in the future. For more information on data centers, refer to [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
## Log In to Your Last-Used Workspace
Log in to your last-used workspace from its data center login page. When you log in for the first time, MoEngage redirects you to your invited workspace.
Your Admin configures which login method your workspace uses:
* Password
* Google
* SSO
> [tab] Password
>
> > [!NOTE]
> >
> > If your Admin set the login method to **Password or Google sign in**, you can log in with either your email and password or the **Google** button.
>
> 1. In a web browser, go to the URL of your MoEngage workspace. The login page appears. 
> 2. In the **Work email** box, type your email address.
> 3. In the **Password** box, type your password.
> 4. Click **Login**. 2-step verification is mandatory when you log in with a password. Refer to [Complete 2-Step Verification](#complete-2-step-verification) below.
> [tab] Google
>
> > [!NOTE]
> >
> > If your Admin set the login method to **Google Sign In only**, log in using the **Google** option.
>
> 1. In a web browser, go to the URL of your MoEngage workspace. The login page appears. 
> 2. Click **Google**.
> 3. On the **Choose an account** page, choose your Google account. 
> 4. On the **Sign in to moengage.com** page, click **Continue**.  2-step verification is mandatory when you log in with Google. Refer to [Complete 2-Step Verification](#complete-2-step-verification) below.
> [tab] SSO
>
> > [!NOTE]
> >
> > If your Admin set the login method to **Single Sign On (SSO) only**, log in using SSO.
>
> 1. In a web browser, go to the URL of your MoEngage workspace. The login page appears.
> 2. Click **SSO**.  The **Login using SSO** page appears, with your email pre-filled if you entered it on the previous screen.
> 3. In the **Work Email** box, type your email address.
> 4. Click **Continue**.  MoEngage redirects you to your organization's Identity Provider (IdP) for authentication.
> 5. Log in to the SSO IdP using your credentials.
> 6. Upon successful authentication, MoEngage redirects you to the dashboard. If 2-step verification is enabled for your workspace, refer to [Complete 2-Step Verification](#complete-2-step-verification) below.
## Log Into a Different Workspace
Use this flow to log in to any workspace you're authorized to use. Identity verification happens first (before workspace access checks), so an access issue with one workspace does not affect the others.
**1. Choose a different workspace**
On the login page (or at [dashboard.moengage.com](https://dashboard.moengage.com/v4/#/auth)), click **Login to a different workspace**.
**2. Enter your email**
In the **Work email** box, type your email address. If you entered it on the previous page, it's pre-filled.
**3. Verify your identity**
Click **Continue**. The **User authentication** page appears.

> [!NOTE]
>
> User authentication uses your 2-step verification code to verify your identity before showing your workspaces. For setup details, refer to [Set Up 2-Step Verification on Your Device](#set-up-2-step-verification-on-your-device).
Open your authenticator app, find the 6-digit code for your MoEngage account, and type it in the verification box.
**4. Select a workspace and environment**
Click **Continue**. The workspace list appears, titled **Login to a different workspace**. Choose the workspace and environment you want to access. Each entry shows:
* Workspace name
* Whether it's your last-used workspace
* Login method
* Environment (Live or Test)

**5. Complete workspace authentication**
Complete authentication using the login method configured for the selected workspace:
* **Password**: Enter your password and click **Login**.
* **Google Sign-In**: Click **Google** and choose your Google account.
* **SSO**: Click **SSO** to be redirected to your organization's Identity Provider (IdP).
MoEngage logs you in to the selected workspace.
## Log In via MCP Connection
Connect AI assistants (such as Claude and ChatGPT) via the MoEngage MCP (Model Context Protocol) server to work with your campaigns and data through natural-language conversation. The login flow authenticates the MCP connection rather than the dashboard, and has its own session behavior.
For the full login flow, session details, and setup, see [MoEngage MCP Server and Connector](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server#authentication).
## Complete 2-Step Verification
When 2-step verification is enabled, MoEngage shows the 2-Step Verification page after you authenticate.
> [!WARNING]
>
> For security reasons, 2-step verification is mandatory and cannot be disabled for any workspace whose login method is set to **Password or Google sign in** or **Google Sign In only**. Every user in such a workspace must complete 2-step verification at each login. For more information on login methods, refer to [Set Up the Login Method](/docs/user-guide/settings/account/security/set-up-the-login-method).
**On first setup:** MoEngage prompts you to configure 2-step verification. Refer to [Set Up 2-Step Verification on Your Device](#set-up-2-step-verification-on-your-device).
**On subsequent logins:** Enter your 6-digit code from your authenticator app: 
1. Open the authenticator app on your device and find the 6-digit code for your MoEngage workspace.
2. On the 2-Step Verification page, type the code in the **Verification code** boxes.
3. Click **Continue**. MoEngage logs you in to the dashboard.
> [!TIP]
>
> For assistance with 2-step verification, such as setting up a new device or obtaining additional recovery codes, refer to [Troubleshooting](#troubleshooting).
> [!NOTE]
>
> In the [Log Into a Different Workspace](#log-into-a-different-workspace) flow, the equivalent step is called **User authentication** and happens before workspace selection, not after.
## Set Up 2-Step Verification on Your Device
2-step verification requires a code from an authenticator app. Your app generates a new 6-digit code every 30 seconds. Set it up once and use it at every login.
> [!TIP]
>
> **Prerequisites**
>
> You need an authenticator app on your phone (for example, Google Authenticator).
>
> * Google Authenticator: [Google Play](https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2\&hl=en_IN\&gl=US) | [App Store](https://apps.apple.com/us/app/google-authenticator/id388497605)
> * Twilio Authy: [Google Play](https://play.google.com/store/apps/details?id=com.authy.authy) | [App Store](https://apps.apple.com/us/app/twilio-authy/id494168017)
> [accordion] When is 2-step verification required and how it works
>
> Setup occurs in these scenarios:
>
> * Admin signs up for MoEngage or creates a new workspace (enabled by default).
> * You're invited to a workspace with 2-step verification enabled. A prompt appears after [finishing your workspace setup](/docs/user-guide/getting-started/initial-setup/sign-up-with-moengage-or-create-a-new-account-in-moengage#finish-your-workspace-setup-as-an-invited-user).
> * Admin enables 2-step verification after you've logged in. You're logged out automatically and prompted on your next login.
> * You enable it for your own account in **My Profile**.
>
> 2-step verification works at two levels: workspace and user.
>
> * **Workspace level**: Whether 2-step verification applies to everyone in a workspace depends on the workspace's login method. If the login method is **Password or Google sign in** or **Google Sign In only**, 2-step verification is mandatory for every user for security reasons, and your Admin cannot disable it. Only workspaces that use **Single Sign On (SSO) only** can have it turned off, from [Settings > Security > 2-step verification](/docs/user-guide/settings/account/security/2-step-verification-or-two-factor-authentication-2fa).
> * **User level**: If your workspace uses SSO and your Admin hasn't enforced 2-step verification, you can still enable it for your own account from **My Profile**.
>
> Each workspace has its own 2-step verification configuration, so it can be enforced in one workspace and turned off in another.
### Configuration Steps
1. On the 2-Step Verification page, click **Setup device Authentication**. The Set your device authentication page appears.

2. Open your authenticator app and tap the **+** icon.

The Add an authentication code screen appears.

3. Add MoEngage to your authenticator app, use either option to add MoEngage:
> [tab] QR code
>
> 1. Tap **Scan a QR code**.
>
> 
> 2. Scan the QR code shown on the **Set your device authentication** page. Your authenticator app adds MoEngage and begins generating 6-digit codes.
> [tab] Setup key
>
> 1. Tap **Enter a setup key**.
>
> 
> 2. On the **Enter account details** screen, fill in the following fields:
>
> | Field | Required | Description |
> | - | - | - |
> | Account name | Optional | Type your account name. |
> | Your key | Yes | Type the 32-digit secret key shown on the **Set your device authentication** page.  |
> | Type of key | Optional | **Time based** (OTP from current time) or **Counter based** (OTP from incrementing counter). |
> |  | | |
> 3. Tap **Add**. Your authenticator app adds MoEngage and begins generating 6-digit codes.
>
> 
4. In the **Enter the 6 digit verification code** box, type the current code from your authenticator app.
> [!NOTE]
>
> Each code is valid for 30 seconds. After that, your authenticator app generates a new code.

5. Click **Continue**. 2-step verification is now configured on your device.
6. Click **Download recovery codes** to save your backup codes as a CSV file. For more information, refer to [Recovery Codes](#recovery-codes).

7. Click **Login**. The **[Login page](#log-in-to-your-last-used-workspace)** appears.
## Recovery Codes
Recovery codes are 10 one-time-use backup codes you can use if your primary 2-step verification device is temporarily unavailable. MoEngage generates them when you first set up or reset 2-step verification.
* Store in a secure location.
* Each code is single-use only.
* To get new codes, see **Reset 2-step verification** under [Troubleshooting](#troubleshooting).
## One-Time Password (OTP) Verification
To protect your account security, MoEngage may prompt you to enter a One-Time Password (OTP) instead of the code from your authenticator app when it detects unrecognized sign-in activity, such as logging in from a new device, a different location, an unfamiliar IP address, or an unusual time. MoEngage sends the verification code immediately to your registered email address.

## Troubleshooting
> [!NOTE]
>
> You can click **Contact support** on the login page to raise a support ticket directly.
> [accordion] Correct codes are being rejected
>
> Make sure both your login device and the device with your authenticator app are set to the same timezone. Codes are time-based and expire after 30 seconds.
> [accordion] Login page won't load or behaves unexpectedly
>
> Clear your browser's cookies and cache, then try again.
> [accordion] Browser Extensions Cause Errors while Resetting Password or 2-Step Verification
>
> Browser extensions, such as password managers, ad blockers, and form-fill extensions, can interfere with the **Reset Password** and **2-Step Verification** pages. Disable them or use a private/incognito browser window, then try again.
> [accordion] This Workspace Has Been Blocked
>
> You see the error "This workspace has been blocked. Please contact our support team for assistance." MoEngage blocks a workspace when there are pending dues on the account. Contact the MoEngage Support team to resolve pending dues and unblock the workspace.
> [accordion] No DBs Associated With Email
>
> You see the error "No DBs associated with email." This occurs when your access to MoEngage has been revoked. Contact your administrator so they can grant you access again.
> [accordion] Changing Your Login Email Address
>
> MoEngage does not support changing the email address on an existing account. To use a new email address:
>
> 1. Ask your Admin to [invite the new email address](/docs/user-guide/settings/account/team-management/manage-members#invite-members) to the workspace.
> 2. If you no longer need access from the previous email address, ask your Admin to [revoke its access](/docs/user-guide/settings/account/team-management/manage-members#revoke-a-member’s-access).
> [accordion] Not sure you're on the right login page
>
> Verify you're using the correct login URL for your workspace. Each workspace is hosted on a specific data center. For more information, refer to [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
> [accordion] Didn't receive a reset email
>
> Check that your organization hasn't blocked the MoEngage domain.
> [accordion] Forgot Your Password
>
> **1. Request a password reset**
>
> On your workspace login page, click **Forgot Password?**. 
>
> **2. Enter your email**
>
> Type your MoEngage email and click **Send Link**. 
>
> **3. Open the reset link**
>
> Click the reset link in your email. 
>
> **4. Create a new password**
>
> Your password must contain:
>
> * 8–20 characters
> * At least one uppercase letter
> * At least one number
> * At least one special character: `! @ # $ % ^ & * ( ) _ ? / , < > ; : { } | ~`
>
> 
>
> Click **Reset Password**. [Log in](#log-in-to-your-last-used-workspace) with your new password.
> [accordion] Reset 2-Step verification if you reinstalled/changed the authenticator application or lost/changed your device
>
> Reset 2-step verification to set up a new authenticator device (if you changed or replaced your device) or to generate a new set of recovery codes after using your existing ones.
>
> > [!TIP]
> >
> > **Prerequisite:** You must have previously set up 2-step verification on your device.
>
> 1. Try to [log in to your workspace](#log-in-to-your-last-used-workspace) using your credentials.
> 2. On the \*\* Reset 2-Step Verification\*\* page, enter your work email id and click **Send link**. 
> 3. MoEngage sends a reset link to your email address.
> 4. Open the email from MoEngage and click **here to reset your 2FA credentials**.  You land on the Login to your accounts page in a new browser tab. 
> 5. Log in using your credentials. MoEngage takes you to the 2-Step Verification page.
> 6. Click **Setup your device**. The Set up your device authentication page appears. 
> Add MoEngage to your authenticator app using either a QR code or a setup key. Refer to [Configuration Steps](#configuration-steps) for details on both options.
> 7. In the **Enter the 6 digit verification code** box, type the code from your authenticator app.
> > [!NOTE]
> >
> > Each code is valid for 30 seconds.
> 8. Click **Confirm**. 2-step verification is now reset on your device. Use the verification code from this new authenticator instance for all future logins.
> 9. Click **Download recovery codes** to save a new set of backup codes as a CSV file.  Your previous recovery codes no longer work.
> 10. Click **Login**.
> [accordion] No access to the authenticator application? Log in using a recovery code
>
> Use a recovery code if your primary 2-step verification device is temporarily unavailable.
>
> > [!TIP]
> >
> > You must have previously downloaded recovery codes. Refer to [Recovery Codes](#recovery-codes) for details.
>
> **1. Log in with your credentials**
>
> [Log in to your workspace](#log-in-to-your-last-used-workspace) with your credentials.
>
> **2. Switch to recovery code**
>
> On the 2-Step Verification page, click **Enter recovery code**. 
>
> **3. Enter your code**
>
> Type one of your saved recovery codes. \[!NOTE] Each code is single-use only.
>
> **4. Verify**
>
> Click **Continue**.  You're logged in.
>
> > [!TIP]
> >
> > If you have used all your recovery codes, see **Reset 2-step verification** above to generate a new set.
> [accordion] Not able to connect via MCP
>
> If you cannot connect via MCP, reset your password, then reconnect. See **Forgot Your Password** above.
> [accordion] Account Lockout
>
> MoEngage locks your account as a security measure when your login attempts seem suspicious.
>
> > [!WARNING]
> >
> > If you (as a user or an Admin) enter incorrect login credentials or email OTP four times, MoEngage locks your account.
>
> * **As a user**: Wait 3 hours (180 minutes), then log in using your correct credentials. Alternatively, contact your MoEngage Admin to unblock your account faster.
> * **As an Admin**: Wait 3 hours (180 minutes), then log in using your correct credentials.
>
> **To unblock a user's account as an Admin:**
>
> 1. On the left navigation menu in the MoEngage dashboard, click **Settings > Account > Team management**. 
> 2. On the Team management page, click the **Members** tab.
> 3. In the **Search member(s)** box, type the email address of the user whose account is blocked. 
> 4. Under the **Action** column, click the ellipsis icon and click **Unblock**. Only accounts with Blocked status show the **Unblock** option. 
>
> MoEngage unblocks the account, and the user can log in using their correct credentials.
> [accordion] Contact Support
>
> If none of the solutions above resolve your issue, contact the MoEngage Support team. For more information, refer to [Raise a Support Ticket Through MoEngage Dashboard](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
# Set Up Your Profile
Source: https://moengage.com/docs/user-guide/getting-started/initial-setup/manage-your-profile
Configure your MoEngage profile — update your personal details, manage 2-step verification, set your workspace language, and choose your theme.
MoEngage allows you to manage your profile for each workspace in the MoEngage dashboard. The **My Profile** section has the following tabs:
* [General](/docs/user-guide/getting-started/initial-setup/manage-your-profile#general)
* [Security](/docs/user-guide/getting-started/initial-setup/manage-your-profile#security)
* [Preferences](/docs/user-guide/getting-started/initial-setup/manage-your-profile#preferences)
* [Appearance](/docs/user-guide/getting-started/initial-setup/manage-your-profile#appearance)
# General
Under the **General** tab, you can edit your personal information for the current workspace.
1. In the upper-right corner, click your profile icon and then click **My Profile**. 
2. On the **My profile** page, the **General** tab is selected by default.
3. Click **Edit** in the upper-right corner. 
4. Add your profile picture:
1. Hover over your profile icon and click the edit icon. 
2. Click **Update**.
3. Select your profile picture and click **Open**.
> [!NOTE]
>
> MoEngage supports only the .jpeg, .jpg, and .png files.
5. Edit the following details:
| Field | Description |
| - | - |
| Name | Enter your name. |
| Email Id | This field is read-only. |
| Role | This field is read-only. |
| Active Since | This field is read-only. |
| Job title | Enter your job title. |
| Department | Enter your department name. |
| Phone number | Select your country code and enter your phone number. |
| Date of birth | Select your date of birth using the date picker. |
6. Click **Save**. Your personal information is updated.
# Security
The **Security** tab provides tools for enhancing security for the current workspace.
1. In the upper-right corner, click your profile icon and then click **My Profile**. 
2. On the **My profile** page, click **Security**. 
3. You can perform the following tasks:
* [Change your password](#change-your-password)
* [Manage 2-step verification](#manage-2-step-verification)
* [Log out of your active devices](#log-out-of-your-active-devices)
## Change Your Password
To change your password, perform the following steps:
1. On the **Security** tab, click **Change password** in the upper-right corner of the **Password** section. 
2. Enter the following details:
| Field | Description |
| - | - |
| Old password | Enter the old or existing password. |
| New password | Enter the new password. Ensure the password meets the following criteria:
Contains 8 to 20 characters.
Contains one capital letter.
Contains one number.
Contains one special character among !@#\$%^&\*()\_?/,`<>`;:`{}` \~ and no space.
|
| Retype new password | Retype the new password. |
3. Click **Save**. Your password is updated.
## Manage 2-Step Verification
MoEngage allows you to secure your MoEngage workspace with 2-step verification. This helps you reduce the risk of unauthorized access due to compromised passwords. Your Admin can enable it for all users at the workspace level. For more information, refer to [2-Step Verification or Two-Factor Authentication (2FA)](/docs/user-guide/settings/account/security/2-step-verification-or-two-factor-authentication-2fa). However, you can manage it at the user level.
### Set Up 2-Step Verification
> [!NOTE]
>
> The **Setup device** option appears when both of the following criteria are met:
>
> * If your Admin has disabled 2-step verification at the workspace level.
> * You log in to your workspace for the first time.
1. On the My profile page, click **Security**. 
2. Click **Setup device** adjacent to **2-step verification**.  The Set up your device authentication pop-up window appears. 
3. Open the authenticator app now (for example, Google Authenticator) and tap the **+** icon.

The Add an authentication code screen appears.

4. Use one of the following authentication options:
* **Using a QR code**
1. Tap **Scan a QR code**. The Scan code screen appears.

2. Scan the QR code on the Set up your device authentication pop-up window in the MoEngage dashboard. An authentication is added to your device. Your authentication app generates a 6-digit code.
* **Using a setup key**
1. Tap **Enter a setup key**.

2. On the **Enter account details** screen, enter the following details :
| Fields | Required | Description |
| - | - | - |
| Account name | Optional | Type your account name. |
| Your key | Yes | Type the 32-digit secret key displayed on the Set up your device authentication pop-up window in the MoEngage dashboard.  |
| Type of key | Optional | This is the type of your key. Supported values are:
**Time based**: The OTP is generated based on the current time.
**Counter based**: The OTP is generated based on an incrementing counter.
Select an option. In the following example, *Time based* is selected. |

3. Tap **Add**.
4. An authentication is added to your device with the name you entered in the **Account name** box. Your authentication app generates a 6-digit code.

5. In the **Enter the 6-digit verification code below** box, type the 6-digit authentication code generated by your authentication app.
> [!NOTE]
>
> Each authentication code your authentication app generates is valid only for 30 seconds. After that, your authentication app generates a new code.

6. Click **Submit**.\
You have successfully configured 2-step verification on your device for your MoEngage workspace.
### Enable 2-Step Verification
> [!NOTE]
>
> The **Enable device** option appears only if your admin has disabled 2FA at the workspace level and you have not enabled it for your workspace.
To enable 2FA for the current workspace, perform the following steps:
1. On the **My profile** page, click **Security**. 
2. Click the ellipse icon adjacent to **2 step verification** and then click **Enable device**.  The Enable device pop-up window appears, prompting you for confirmation to enable 2FA for your workspace.
3. Click **Enable**. \
The 2FA is now successfully enabled for your workspace.
After you enable 2FA for your workspace, you will be automatically logged out of the MoEngage dashboard. When you log in to the MoEngage dashboard again, you must set up 2-step verification on your device. For more information, refer to [Set Up 2-Step Verification on Your Device](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#set-up-2-step-verification-on-your-device).
### Remove 2-Step Verification
> [!NOTE]
>
> The **Remove device** option is visible only when both of the following criteria are met:
>
> * You have enabled 2FA for your workspace.
> * Your admin disables it at the workspace level.
To remove 2FA for the current workspace, perform the following steps:
1. On the **My profile** page, click **Security**. 
2. Click the ellipse icon adjacent to **2 step verification** and then click **Remove** **device**.  The Remove device pop-up window appears, prompting you for confirmation to remove 2FA for your workspace.
3. Click **Remove**. \
The 2FA is now successfully removed from your workspace.
### Change 2-Step Verification
You may want to set up 2FA for the current workspace on a new device, for example, when you purchase a new phone.
> [!NOTE]
>
> The **Change device** option is visible when you have enabled or disabled 2FA for your workspace.
To change the 2-step verification for your workspace, perform the following steps:
1. On the **My profile** page, click **Security**. 
2. Click the ellipse icon adjacent to **2 step verification** and then click **Change device**. 
3. The Change device pop-up window appears. 
4. Enter the 6-digit code generated by your current device's authenticator app.
5. Click **Next**.
6. The **Set up your device authentication** pop-up window appears. 
7. From your device's authenticator app (for example, Google Authenticator):
1. Tap the **+** icon.

The Add an authentication code screen appears.

2. Use one of the following authentication options:
* **Using a QR code**
1. Tap **Scan a QR code**. The Scan code screen appears.

2. Scan the QR code on the **Set your device authentication** page. An authentication is added to your device. Your authentication app generates a 6-digit code.
* **Using a setup key**
1. Tap **Enter a setup key**.

2. On the **Enter account details** screen, enter the following details:
| Fields | Required | Description |
| - | - | - |
| Account name | Optional | Type your account name. |
| Your key | Yes | Type the 32-digit secret key displayed on the **Set up your device authentication** page.  |
| Type of key | Optional | This is the type of your key. Supported values are:
**Time based**: The OTP is generated based on the current time.
**Counter based**: The OTP is generated based on an incrementing counter.
Select an option. In the following example, *Time based* is selected. |

3. Tap **Add**.
4. An authentication is added to your device with the name you entered in the **Account name** box.\
Your device receives a new authentication, which appears below the previous authentication.

In the future, you must use the verification code from the new instance only.
8. Enter the 6-digit code generated by your authenticator app. 
9. Click **Submit**.
## Log Out of Your Active Devices
Under **Active devices**, you can see all the devices you have used to access this workspace. Perform the following steps to log out of a device:
1. Click the logout icon adjacent to the active device from which you want to log out. Your device is successfully logged out. 
2. Click the ellipsis icon and then click **Logout of all devices** to log out of all your active devices.  The Logout pop-up window will appear, prompting you to confirm.
3. Click **Logout**. 
# Preferences
Under the **Preferences** tab, you can select your preferred language for the MoEngage workspace and suggest new languages for future support.
## Select Your Workspace Language
Your MoEngage workspace language is set to English by default, but you can change it to any language supported by MoEngage.
> [!NOTE]
>
> MoEngage currently supports Japanese and Brazilian Portuguese.
> [!NOTE]
>
> This is an Early Access feature. To enable it for your workspace, contact your CSM or [raise a support ticket](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
Perform the following steps to select the workspace language:
1. On the **My profile** page, click the **Preferences** tab. The Language preferences page appears.
2. In the **Workspace language** list, select your preferred language. 
Your workspace switches to the language you selected.
## Suggest a Language
You can suggest a language if you do not find your preferred language in the **Workspace language** list. Perform the following steps to suggest a language:
1. Click **Suggest a language**. The Suggest a language dialog box appears. 
2. In the **Select preferred language** list, select the language you want MoEngage to support.
3. Click **Done**.
You will receive a notification after MoEngage starts supporting your preferred language.
# Appearance
You can personalize your MoEngage UI by choosing a workspace theme that suits your environment. MoEngage offers light and dark modes to reduce eye strain and improve readability based on your preference.
To change your workspace theme, perform one of the following steps:
1. Use one of the following options:
* In the upper-right corner, click your profile icon and then click **Appearance**.

* Click **My profile**.

* On the **My profile** page, click the **Appearance** tab.

2. In the **Default theme** section, select one of the following options:
* **Default**: Applies the standard MoEngage light theme.

* **Dark**: Applies a high-contrast dark theme for low-light environments.

* **Sync with browser (Light/Dark)**: Automatically adjusts the theme to match your system or browser settings.

> [!NOTE]
>
> You can also quickly toggle between light and dark modes by clicking the icon located in the top navigation bar next to the notification bell.
>
> * Moon icon to switch to the dark mode:
>
> 
> * Sun icon to switch to the light mode:
>
> 
# Sign Up with MoEngage
Source: https://moengage.com/docs/user-guide/getting-started/initial-setup/sign-up-with-moengage-or-create-a-new-account-in-moengage
Create your first MoEngage workspace with a password or Google account, or finish setting up your workspace as an invited user.
Signing up with MoEngage creates your first workspace. You must complete this one-time step based on your organization's requirements.
> [!TIP]
>
> **Prerequisite**
>
> You must have a valid subscription code to sign up on MoEngage. Contact your sales representative to obtain your subscription code.
## Create a Workspace
1. Visit the following URL:
```auto theme={null}
https://dashboard-0X.moengage.com/v4/#/auth/signup
```
The `X` in the URL refers to the MoEngage data center (DC). You can find your DC number by referring to the [data center and API endpoint mapping](/docs/user-guide/data/key-concepts/data-centers-in-moengage). The Create your account page appears. If you have questions about your data centre, contact your sales representative. 
2. Create your workspace using one of the following methods:
* [Using a password](#using-a-password)
* [Using your Google account](#using-your-google-account)
### Using a Password
1. In the **Company name (Workspace name)** box, type your company name. This will also be the name of your workspace in the MoEngage dashboard.
2. In the **Work email** box, type your work email.
3. In the **Password** box, type your password. Ensure the password meets the following criteria:
* Contains 8 to 20 characters.
* Contains one capital letter.
* Contains one number.
* Contains one special character from: `! @ # $ % ^ & * ( ) _ ? / , < > ; : { } | ~` with no spaces.
4. In the **Subscription code** box, type your subscription code.
5. Select the **I agree to the Terms of use and Privacy policy** check box.
6. Click **Get Started**.

MoEngage sends a verification email to your registered email address.

> [!NOTE]
>
> If you haven't received the verification email, click **Resend verification email**.
7. Open the email from MoEngage and click the activation link.

After verification, you are directed to the login page.

### Using Your Google Account
1. Click **Continue with Google**. 
2. On the **Sign in with Google** page, choose your Google account. 
3. On the Sign in to moengage.com page, click **Continue**.  The **Finish signing up** page appears. 
4. In the **Company name (Workspace name)** box, type your company name or workspace name.
5. In the **Subscription code** box, type your subscription code.
6. Click **Continue**.

Your workspace is created. You are directed to the login page.

> [!NOTE]
>
> MoEngage enables 2-step verification by default to protect your workspace from unauthorized access. When you log in for the first time, MoEngage prompts you to set up 2-step verification on your device. For more information, refer to [Set Up 2-Step Verification on Your Device](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#set-up-2-step-verification-on-your-device).
## Finish Your Workspace Setup as an Invited User
If someone invited you to a MoEngage workspace, you must complete a one-time setup before logging in for the first time.
> [!TIP]
>
> **Prerequisites**
>
> After having been invited to a workspace, you will receive a welcome email from **Moengage Alerts** ([alerts@moengage.com](mailto:alerts@moengage.com)) with the following subject line:
>
> `` has invited you to join MoEngage for ``
>
> 
>
> If you haven't received this email, contact your company's MoEngage Admin or Manager. Roles with the **Create & Manage** [permission](/docs/user-guide/settings/account/team-management/access-roles#permissions) under the **Team Members** component can send invitations. For more information, refer to [Invite a Member](/docs/user-guide/settings/account/team-management/manage-members).
1. Open the email you received from **Moengage Alerts**.
2. Click the **click here** link.  You are taken to the Finish account setup page. 
3. Complete your workspace setup using one of the following methods:
* [Set up a password](#set-up-a-password)
* [Sign in with Google](#sign-in-with-google)
### Set Up a Password
1. On the Finish account setup page, your email address is automatically populated in the **Email** box. 
2. In the **Password** box, enter a new password. Ensure the password meets the following criteria:
* Contains 8 to 20 characters.
* Contains one capital letter.
* Contains one number.
* Contains one special character from: `! @ # $ % ^ & * ( ) _ ? / , < > ; : { } | ~` with no spaces.
3. Click the **Terms of use** link and read the terms.
4. Click the **Privacy policy** link and read the policy.
5. Select the **I agree to the Terms of use and Privacy policy** check box.
6. Click **Set Password and Login**. Your workspace setup is complete. You are directed to the Login to your accounts page. 
> [!NOTE]
>
> Bookmark your MoEngage login page for faster future access. If you forget your login URL, you can find it on the [MoEngage global login page](https://dashboard.moengage.com/). For more information, refer to [Find Your Login Page](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#find-your-login-page).
7. [Log in to your workspace](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
### Sign In with Google
1. On the Finish account setup page, click **Continue with Google**. 
2. On the Choose an account page, choose your Google account. 
3. On the You're signing back in to moengage.com page, click **Continue**.  Your workspace setup is complete. You are directed to the Login to your accounts page. 
> [!NOTE]
>
> Bookmark your MoEngage login page for faster future access. If you forget your login URL, you can find it on the [MoEngage global login page](https://dashboard.moengage.com/). For more information, refer to [Find Your Login Page](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#find-your-login-page).
4. [Log in to your workspace](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
## Next Steps
Set it up based on your business requirements:
* [Complete integrations](/docs/developer-guide/introduction)
* [Invite members](/docs/user-guide/settings/account/team-management/manage-members)
* [Configure settings for your workspace](/docs/user-guide/settings)
* [Create campaigns](/docs/user-guide/campaigns-and-channels)
* Download the **MoEngage Go** mobile app to view and manage campaigns: [iOS (App Store)](https://apps.apple.com/us/app/moengage-go/id6755712030?utm_source=help_docs\&utm_medium=referral\&utm_campaign=app_download) | [Android (Google Play)](https://play.google.com/store/apps/details?id=com.moengage.go\&utm_source=help_docs\&utm_medium=referral\&utm_campaign=app_download)
# Android Native Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/android-native-integration-validation
Validate your MoEngage Android SDK integration directly from the dashboard. Test feature implementations like push notifications and fix issues faster.
# Overview
The *Integration Validation* feature simplifies the integration of the MoEngage Android SDK with your intended application by providing an interface to validate Android SDK feature implementations directly via the MoEngage dashboard.\
Developers often encounter challenges in implementing Android SDK features due to complex steps or misinterpretations of requirements. For instance, while configuring push notifications, they might overlook a few critical settings, such as rich notifications.\
This feature enables developers and marketers to test and validate implementations independently, ensuring accuracy and reducing dependency on support teams. It enhances the integration process, minimizes errors, and ensures seamless marketing communications and user engagement.
# Scope
The integration validation feature helps validate the following features:
* Data Tracking
* Push Notifications
* Push Templates
With integration validation, you cannot validate the following features:
* In-App Messaging
* Cards
* Push
* Location Triggered Push
* Push Notification Centre
* Push Amplification
* HMS Push
* Data
* Custom attribute: Validation of the name, syntax, and data type of attribute names and their values is outside the scope.
* Custom events: Validation of the name, syntax, and data type of the event names, event property names, and their values is outside the scope.
> [!TIP]
>
> **Prerequisites**
>
> The integration validation feature supports all SDK versions released after 13.4.00.
# Register a Device for Integration Validation
Perform the following steps to register your device for integration validation:
1. In the left navigation menu on the MoEngage dashboard, click **Test & Debug**, and then click **Integration validation**. 
2. On the **Integration Validation** page, scan the QR code using any QR reader app on your mobile device to register your device.
3. Select **Click here** on the landing page to proceed and you can select your application from the suggested apps.
> [!NOTE]
>
> * To see your preferred application, ensure it has the correct SDK version, that is, versions including and above 13.4.00.
> * The MoEngage system displays the **system Debugger** page, and the app is in debugger mode and ready to be validated.
#### Debugger Mode Error Paths
Following are the reasons you are unable to see the **system Debugger** page on your preferred app:
* You have scanned the wrong dashboard.
* You have scanned the test environment of the dashboard.
* You have set an incorrect app ID or data center (DC). For more information, see [here](/docs/developer-guide/unity-sdk/sdk-integration/sdk-initialization/sdk-initialization).
4. After you register your device, the MoEngage system loads the **Session Logs** on the MoEngage dashboard. 
5. You can open your intended app and refresh the session logs by clicking the refresh icon . Here, you can view the information associated with your session. The *SDK Logger* feature allows you to view the raw data associated with the sessions. For more information, see [here](/docs/developer-guide/android-sdk/troubleshooting-and-faqs/how-to-use-the-moengage-sdk-logger). 
| Field | Description |
| - | - |
| Session Details | Specifies the device ID, the starting date, and the time of the session. |
| Device Name | Specifies the device name. |
| Status | Specifies the status of the session: **_Live_**: The session is live, and you can view the time left before the session expires. It allows you to validate the integration. **_Timed out_**: The session is expired. You can view the session details but can not perform any validating actions for the same |
> [!NOTE]
>
> If you have just installed the application, the MoEngage system requires a buffer period of approximately 5 minutes to retrieve user device details.
6. You can click the relevant session to open the associated **session** page. 
# Integration Validation Session
1. On the **session** page, you can view the user details associated with the live session by clicking **User Info.** This redirects you to the **User Profile** page. 
2. Click **Activity Info** to get a detailed overview of all events the current user has performed. 
> [!NOTE]
>
> The **User Info** and **Activity Info** tabs provide details about the current session user, not the dashboard user.
3. On the **session** page, you will get the following information: 
> [tab] Device Info
>
> | Field | Description |
> | - | - |
> | OS Version | Specifies the operating system version of the device. |
> | API level | Specifies the Android API level of the device. |
> | Model Name | Specifies the model name of the user device. |
> | Manufacturer | Specifies the device's manufacturer. |
> | Google Advertising Identifier (GAID) | Specifies the unique identifier for advertising on the device. For more information, see [here](/docs/user-guide/data/privacy/android-advertising-id-tracking). |
> | Device Density | Specifies the screen density of the device. |
> | Device Width | Specifies the width of the device screen in pixels. |
> | Device Height | Specifies the height of the device screen in pixels. |
> | Network Type | Specifies the type of network the device is connected to (for example, Wi-Fi, mobile data). |
> | Device Timezone | Specifies the timezone set on the device. |
> | App version | Specifies the version of the app installed on the device. |
> | FCM Push token | Specifies the Firebase Cloud Messaging (FCM) token for push notifications. For more information, see [here](/docs/developer-guide/android-sdk/push/basic/fcm-authentication). |
> | Push permission | Specifies whether push notification permissions are enabled on the device. |
> [tab] SDK Config
>
> | Field | Description |
> | - | - |
> | SmallIcon | Specifies whether the small icon displayed in the notification bar is configured. |
> | largeIcon | Specifies whether the larger icon displayed within the expanded notification view is configured. |
> | notificationcolor | Specifies whether the color is configured for the notification icon or background. |
> | isMultipleIntegrationInDrawerEnabled | Specifies whether multiple integrations are enabled in the drawer. |
> | IsBuildingBackStackEnabled | Specifies whether the back stack is built for navigation. |
> | isLargeIconDisplayEnabled | Specifies whether the large icon is displayed in the notification. |
> [tab] Modules Integrated
>
> You can view all modules that are integrated as part of this implementation in the **Modules integrated** section.
>
> | Modules | Version |
> | - | - |
> | moe-android-sdk | 13.05.01 |
> | core | 7.5.0 |
> | cards-core | 2.3.1 |
> | cards-ui | 2.4.1 |
> | encrypted-storage | 2.1.0 |
> | geofence | 4.2.1 |
> | pushbase | 8.3.0 |
> | rich-notifications | 5.1.0 |
> | pushkit | 5.1.1 |
> | moe-push-firebase | 7.2.0 |
> | inapp | 8.7.0 |
> | inbox-core | 3.2.1 |
> | inbox-ui | 3.2.1 |
> | integration-verifier | 5.3.1 |
> | pushAmp | 5.2.1 |
> | realtime-trigger | 3.4.1 |
> | sdk-debugger | 1.2.0 |
> | security | 3.2.0 |
> | trigger-evaluator | 1.3.0 |
> | richNotification | 5.1.1 |
# Validation Steps
> [!NOTE]
>
> The *Not Received* status might be due to insufficient log generation. In such cases, try performing the action again or switching the app between background and foreground modes. If the status remains *Not Received*, it indicates a validation failure. Refer to the step-specific error paths for resolution.
You can view the following statuses to track the progress of each validation step:
| Status | Description |
| - | - |
| Not started | Indicates that the validation for this step is not initiated. |
| Processing | Indicates that an action is performed on the app to track the steps. Wait for the timer to complete so you can view the outcome. |
| Validated | Indicates that the validation for this step is complete. |
| Not received | Indicates that the expected data or response is not received. |
| Failed | Indicates that the validation for this step is unsuccessful. For your reference, this article lists all possible error paths for each validation step. |
## Data Tracking
Data Tracking consists of five validation steps where you can validate the custom attribute and custom events in your intended app. To validate data tracking, expand the **Data tracking** drop-down list and do the following:

### Custom Attribute
Custom Attribute helps you verify the tracking of custom attributes, such as confirming your preferred language, address, and membership status. Custom Attribute also ensures that the MoEngage system captures user-defined data points accurately.
To validate the custom attribute, perform the following steps:
1. Open the intended app and set a custom attribute on the app.
2. After you have setup the custom attribute, click **Yes, I performed the action**.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. After the verification is completed, the status changes from *Not Validated* to *Validated*.
4. If there’s any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Custom Attribute validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Not Received | If you have not performed the required action in the application, complete the action to enable tracking. | Verify your implementation of custom attributes. For details on tracking custom attributes, see [here](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes). |
| | If you have performed the action and the status is not updated, custom attribute tracking might not be integrated. | |
### Custom Event
Custom Event helps you verify the tracking of user-defined interactions, such as button clicks or video plays, are recorded accurately. For example, Ensuring a *Product Added to Cart* event is tracked with the correct product ID.
To validate the custom attribute, perform the following steps:
1. Open the intended app and set a custom event on the app.
2. After you have setup the custom attribute, click **Yes, I performed the action**.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. After the verification is completed, the status changes from *Not Validated* to *Validated*.
4. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred:
#### Custom Event Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Custom event is not tracked (Android Native). | Ensure that the *TrackEvent* method is called with the custom event. |
| Failed | Custom event is not tracked. | The *TrackEvent* method is called before SDK initialization. Initialize the SDK first. |
### GAID Tracking
GAID Tracking helps ensure the unique advertising identifier is captured and transmitted accurately for targeted advertising or analytics. GAID Tracking involves inspecting device logs and validating integrations with advertising platforms.\
The status is automatically displayed as Validated for GAID Tracking based on the device settings.
#### GAID Tracking Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Not Received | The Google Ads library is missing. | Add the Google Ads library to the integration. For more information, see [here](/docs/developer-guide/android-sdk/data-tracking/basic/enable-advertising-identifier-tracking). |
| | The `enableAdIdTracking()` method was not called. | Add the method call to enable AD ID tracking. For more information, see [here](/docs/developer-guide/android-sdk/data-tracking/basic/enable-advertising-identifier-tracking). |
### Login
Login helps ensure user authentication events are accurately recorded in logs or analytics systems. Login includes validating event triggers, user data, and session creation.
To validate the login, perform the following steps:
1. Login to the intended app.
2. After you have logged in, click **Yes, I performed the action**.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. After the verification is completed, the status changes from *Not Validated* to *Validated*.
4. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Login Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Login method was not called. | Call `setUniqueId` in the code. For more information, refer to [Track User Attributes.](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes) |
### Logout
Logout helps ensure that user sign-out events are logged correctly and sessions are invalidated. Logout involves testing log entries, session cleanup, and API responses.
To validate the logout, perform the following steps:
1. Log out of the intended app.
2. After you have logged out, click **Yes, I performed the action**.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. After verification is completed, the status changes from *Not Validated* to *Validated*.
4. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Logout Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Logout method was not called. | Ensure the logout method is invoked. For more information, refer to [Track User Attributes.](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes) |
## Push
Push consists of two sections:
* Basic Push
* Push Templates
## Basic Push
Basic Push consists of six validation steps where you can validate the configuration of small app icon, large app icon, push permission, and notification in various app states. To validate Push, expand the **Basic** **Push** drop-down list and do the following:

### Small App Icon
Small app icon helps you verify that the small app icon is displayed correctly within the notification area across various devices. For example, small app icon ensures that the icon appears crisp, aligns with branding guidelines, and scales appropriately without distortion.\
The status is automatically displayed as *Validated* for small app icon based on the device configurations.
#### Small App Icon Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | small app icon is not configured. | Add *NotificationConfig* during SDK initialization and include a small icon. For more information, refer to [Push Configuration](/docs/developer-guide/android-sdk/push/basic/push-configuration). |
| Failed | small app icon is not visible as expected. | Add a new small icon that adheres to the small icon guidelines. For more information, refer to [Push Configuration](/docs/developer-guide/android-sdk/push/basic/push-configuration). |
### Large App Icon
Large app icon helps you verify that the large app icon is displayed as intended when the notification is expanded. For example, ensuring the icon enhances the notification's visual appeal while maintaining clarity and adhering to size requirements.\
The status is automatically displayed as *Validated* for large app icon based on the device configurations.
#### Large App Icon Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Large app icon is not configured. | Add *NotificationConfig* during SDK initialization and include a large icon in the parameter. For more information, refer to [Push Configuration.](/docs/developer-guide/android-sdk/push/basic/push-configuration) |
### Push Permission
Push permission helps you verify that the app requests push notification permissions from the user in a seamless and user-friendly manner. For example, ensuring the permission prompt is triggered appropriately and aligns with the app’s flow.
To validate the push permission, perform the following steps:
1. Open the app and perform the action to trigger the notification runtime permission and accept the request.
2. After you have accepted the request, click **Yes, I performed the action**.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. After the verification is completed, the status changes from *Not Validated* to *Validated*.
4. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Push Permission Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Failed to ask permission from the user. Dialog didn’t show up. | Ask for push permission from the user at runtime. For more information, refer to [Notification Runtime Permissions](/docs/developer-guide/android-sdk/push/basic/notification-runtime-permissions). |
| Failed | Dialog was shown, but push permission is still not updated. | Inform the SDK whether the user granted/denied permission. For more information, refer to [Notification Runtime Permissions](/docs/developer-guide/android-sdk/push/basic/notification-runtime-permissions). |
| Failed | User denied the push permission dialog; the dialog no longer shows up. | Redirect the user to the settings page to request permission manually. For more information, refer to [Notification Runtime Permissions](/docs/developer-guide/android-sdk/push/basic/notification-runtime-permissions). |
### Test Push with App in Foreground
Test push with app in foreground helps you verify that push notifications are received and rendered properly when the app is open and in use. For example, ensure notifications do not disrupt user activity while displaying them subtly but noticeably.
To validate the push notification with the app in the foreground, perform the following steps:
1. Open the intended app in the foreground state.
2. Click **Send test push** on the dashboard.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. Click **Confirm app in foreground** to validate the step if the app was in the foreground when the notification was received. If not, click **Reset** to start validating again.
4. After the verification is completed, the status changes from *Not Validated* to *Validated*.
5. If there’s an error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Test Push with the App in Foreground Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Push notification not shown. | No Firebase service is added to handle the MoEngage payload. Add the MoEngage Service file. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | The custom service file didn’t pass the payload to the SDK. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | App created the notification but didn’t inform the SDK. For more information, refer to [Push Display Handled by Application.](/docs/developer-guide/android-sdk/push/advanced/push-display-handled-by-application) |
### Test Push with App in Background
Test push with app in background helps verify that push notifications are delivered and displayed correctly when the app runs in the background. For example, test push with app in background ensures that the notification appears in the notification center with accurate content and icons.
To validate the push notification with the app in the foreground, perform the following steps:
1. Open the intended app in the background state.
2. Click **Send test push** on the dashboard.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. Click **Confirm app in background** to validate the step if the app was in the background when the notification was received. If not, click **Reset** to start validating again.
4. After the verification is completed, the status changes from *Not Validated* to *Validated*.
5. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Test Push with the App in Background Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Push notification not shown. | No Firebase service is added to handle the MoEngage payload. Add the MoEngage Service file. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | The custom service file didn’t pass the payload to the SDK. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | App created the notification but didn’t inform the SDK. For more information, refer to [Push Display Handled by Application](/docs/developer-guide/android-sdk/push/advanced/push-display-handled-by-application). |
### Test Push with App in Killed State
Test push with app in killed state helps you verify that push notifications are successfully delivered even when the app is closed or not running. For example, ensuring that the notification alerts the app correctly when interacted with, providing a seamless user experience.
To validate the push with the app in the killed state, perform the following steps:
1. Kill the app by swiping it away from the open applications list on your device.
2. Click **Send test push** on the dashboard.\
There is a 60-second waiting period, where the MoEngage system verifies the action in the backend.
3. Click **Confirm app in killed state** to validate the step if the app was in the killed state when the notification was received. If not, click **Reset** to start validating again.
4. After the verification is completed, the status changes from *Not Validated* to *Validated*.
5. If there is any error in the implementation, the status changes from *Not Validated* to *Not Received*. In that case, the following errors might have occurred.
#### Test Push with the App in Killed State Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Push notification not shown. | No Firebase service is added to handle MoEngage payload. Add the MoEngage Service file. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | Custom service file didn’t pass the payload to the SDK. For more information, refer to [Push token registration and display](/docs/developer-guide/android-sdk/push/basic/push-token-registration-and-display). |
| Failed | Push notification not shown. | App created the notification but didn’t inform the SDK. For more information, refer to [Push Display Handled by Application](/docs/developer-guide/android-sdk/push/advanced/push-display-handled-by-application). |
| Failed | Push notification not shown. | Initialize the SDK in the *onCreate()* method of the application class. For more information, refer to [SDK initialization](/docs/developer-guide/android-sdk/sdk-integration/basic-integration/sdk-initialization). |
| Failed | Push notification not shown. | Third-party library failed to pass the payload to the SDK. Check if the library works as expected in a killed state. |
## Push Templates
Push Templates consists of two validation steps where you can validate the exact alarm permission and integration of the push template. To validate Push Templates, expand the dropdown and do the following:

### Test Push Templates
Test push templates helps you validate the structure and content of push notification templates before deployment. For example, Test push templates ensures that all required fields are correctly configured, reducing errors and improving the user engagement experience.
To validate the push templates, perform the following steps:
1. If validated, click **Send test push** to initiate the notification.
2. After the notification is sent, wait 60 seconds for interactions to be tracked.
3. On receiving the notification in the app:
* If you see an image banner template, click **Yes, notification has image banner** to validate.
* If you see a basic template, click **No, notification has basic template**.
#### Test Push Templates Validation Error Paths
| **Status** | **Condition** | **Next Action** |
| - | - | - |
| Failed | Basic push notifications are showing. | Push Templates Library is not integrated with the app. For more information, refer to [Push Templates.](/docs/developer-guide/android-sdk/push/optional/push-templates) |
| Failed | Basic push notifications are showing. | If Library is added, check for network issues; change the network and retry. |
| Failed | Push notification has white/black system boundaries on some devices, fully covered on others. | This is an expected behavior change from Android 12. |
### Timer Exact Alarm Permission Set or Not
Timer exact alarm permission validation helps you verify whether the timer's exact alarm functionality is configured. For example, ensuring precise triggering of alarms in time-sensitive scenarios, enhancing user reliability and scheduling accuracy.
To validate the Timer exact alarm permission, perform the following steps:
1. Integration status is automatically validated.
2. If validated, click **Send test push**. The notification will be attempted.
3. If successfully attempted, wait 60 seconds for interaction tracking.
4. Check if the notification displays the Timer with the Progress Bar template:
* If yes, click **Yes, notification has Timer with progress bar**.
* If no, and the basic template is shown, click **No, notification has basic template**.
#### Timer Exact Alarm Permission Set Validation Error Paths
| Status | Condition | Next Action |
| - | - | - |
| Failed | Progress bar not showing in push notification | Forgot to add the permission. For more information, refer to [Push Templates](/docs/developer-guide/android-sdk/push/optional/push-templates) |
| Failed | Progress bar not showing in push notification | Enable the permission at runtime by the user. For more information, see [Push Templates](/docs/developer-guide/android-sdk/push/optional/push-templates). |
# Android Push Notifications Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/android-push-notifications-integration-validation
Step-by-step guide to validate Android push notification integration with MoEngage SDK. Verify push token generation and test notification delivery.
This article explains Android Push Notifications Integration validation manually in a stepwise manner.
# What is to be Validated?
To make sure Push notifications are working properly on the device.
# How to validate?
1. Push Token Generation
* On [your profile](/docs/user-guide/data/user-data/user-profile) page, the Android push icon has to be green.

2. Push notification received on the device
* Create a general Push campaign on the Dashboard for your device
* Test the notification from the test option at the 2nd stage of creation.

* If you get a successful response, create the campaign. If failed, check for the failure reasons.
* Check for the two icons to be visible on the push notification on your device
3. Notification Redirection
The following default click actions are supported during campaign creation as shown in the image below:
* Navigate to a screen
* Deeplinking
* Rich landing

**Navigate to Screen**
While creating the campaign, select the navigate to Screen option and select a screen from the dropdown. On receiving the notification, click on it and the screen selected in the dropdown should open on the app.

**Deeplinking**
While creating the campaign, select the deeplinking option, and add the URL. On clicking the notification, the user has to be redirected to the exact portion of the app intended. (Add the KV pairs if any)

**Rich Landing**
While creating the campaign, select the Rich landing option, and add the URL. On clicking the notification, the user has to be redirected to the web.

4. Notification stats
* Once the campaign is sent out, the campaign stats should show the impressions and clicks.

# Summary of Success Criteria
1. Push token has to be generated for the users
2. Notification should be displayed correctly including the small and large icons
3. The redirection(3 different types) should work as expected
4. The Impressions and clicks have to be captured.
5. In case of rich notifications(if present), check for the image rendering, notification sound, buttons, and their redirections, etc.
# Potential Issues and Solutions
1. If tokens are not generated correctly, the reachable user base will be less than the actual users. To fix the Token issue, please check the [Android](/docs/developer-guide/android-sdk/push/basic/push-configuration) docs.
2. Incorrect Redirection will lead to confusion/miss in opportunities
3. If the clicks and impressions are not recorded, we cannot understand the impact of the campaign. To fix the Impression or click tracking-related issue, please check the [Android](/docs/developer-guide/android-sdk/push/basic/push-configuration) docs.
# In-App Notifications Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/in-app-notifications-integration-validation
Validate your MoEngage in-app notification integration step by step. Test campaign display, CTA buttons, and click actions to ensure proper delivery.
This article explains InApp Notifications Integration validation manually in a stepwise manner.
# What is to be validated?
To check if the In-app campaigns are displayed on the app and the CTA buttons are working as expected.
# How to validate?
* Create an in-app campaign for your ID and on-screen launch.
* Send a test campaign to your device and check for the in-app notification display (on sending a test you will receive a push notification on the device and on clicking this a random page opens on the app and the in-app is displayed). If failed, check for the failure reasons.
* Complete the campaign creation, and turn off the delivery control. The in-app should start reflecting on your app in 15-30 mins.
* While creating an in-app, add the redirection by selecting the navigation under add action.
* Select the navigate to Screen option and select a screen from the dropdown. On receiving the notification, click on it and the screen selected in the dropdown should open on the app. Add the KV pairs if any. (For IOS you can Paste the screen name)
* Select the deeplinking option, and add the URL. On clicking the notification, the user has to be redirected to the exact portion of the app intended. (Add the KV pairs if any)
* Select the Richlanding option, and add the URL. On clicking the notification, the user has to be redirected to the web.
* Once the campaign is sent out, the campaign stats should show the impressions and clicks.
# Success Criteria
* In-App notification has to be displayed on the device
* The intended redirection has to be achieved
* Once the campaign is live, the notification impressions and clicks should be recorded.
# Potential Issues and Solutions
If InApp is not working, targeting users will not be possible other than through the push channel. To fix this InApp-related issue, please check the [Android](/docs/developer-guide/android-sdk/in-app-messages/in-app-nativ) and [iOS](/docs/developer-guide/ios-sdk/in-app-messages/in-app-nativ) docs.
# Install/Uninstall/Reinstall Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/installuninstallreinstall-integration-validation
Test and validate install, uninstall, update, and reinstall event tracking across Android and iOS with MoEngage SDK. Ensure proper lifecycle events.
This help article covers specific **User Actions Testing** related information like Install/Update/Uninstall/Reinstall across Android and iOS platforms.
# What do we want to validate?
Ensuring that Install, Update, Uninstall, and Reinstall are tracked properly. INSTALL and UPDATE events aren't automatically tracked by our SDKs. Depending on the SDK integration, you will have to pass this information to our SDK.
# How to validate?
First, we should get the app build for Android/iOS after it is integrated with MoEngage SDK.
* Once we install the app build on our device and then open the app, it should track the **INSTALL** event in the [user profile](/docs/user-guide/data/user-data/user-profile).

* In case you have a newer version available and you install that app builds on top of the existing app on the device, it should track the **UPDATE** event in the user profile.

* In case you remove the app from the device or uninstall it, it should track **UNINSTALL**(via silent push or sending/testing push campaign). For more details, please refer to this [Uninstall tracking](/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking).

* After you have uninstalled the app and installed it again on the same device, it should track the **REINSTALL** event in the user profile.

# Success Criteria
We should be able to track INSTALL, UPDATE, UNINSTALL, and REINSTALL correctly on the user profile as an event as it decides the reachability of the user via push.

* If the user has still the app installed then the **Install status** of the user property will be **true**. 
# Potential Issues and Solutions
* If Install/Update is not correctly tracked, we will not be able to create campaigns to target users on install to register drop use cases, updating apps from one version to another. To fix the INSTALL/UPDATE issue, please check [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-install-or-update) and [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/install-update-differentiation) as per the platform.
* If Uninstall tracking is not implemented correctly, this can lead to issues in push delivery like more stale users in the system but not reachable. To fix UNINSTALL tracking issue, please check this [link](/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking).
# iOS Push Notifications Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/ios-push-notifications-integration-validation
Validate iOS push notification integration with MoEngage SDK step by step. Check push token generation, test delivery, and troubleshoot common issues.
This article explains iOS Push Notifications Integration validation manually in a stepwise manner.
# What is to be validated?
To make sure Push notifications are working properly on the device. Please ensure that the .pem/.p8 files are [uploaded to the MoEngage Dashboard](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/configure-mobile-push) before proceeding with the validation.
# How to validate?
## 1. Push Token Generation
* On [your profile](/docs/user-guide/data/user-data/user-profile) page, the IOS push icon has to be green.

2. Push notification received on the device
* Create a general Push campaign on the Dashboard for your device.
* Test the notification from the test option at the 3rd stage of creation.
* If you get a successful response, create a campaign. If the test has failed, check for the failure reasons.

* Check for the icon to be visible on the push notification on your device.
3. Notification Redirection
The following default click actions are supported during campaign creation as shown in the image below:
* Navigate to a screen
* Deeplinking
* Rich landing

**Navigate to a screen**
While creating the campaign, select the navigate to Screen option and paste a screen name in the box. On receiving the notification, click on it and the screen selected in the dropdown should open on the app.

**Deeplinking**
While creating the campaign, select the deeplinking option and add the URL. On clicking the notification, the user has to be redirected to the exact portion of the app intended.

**Rich landing**
While creating the campaign, select the Rich landing option, and add the URL. Click the notification, the user has to be redirected to the web to the provided URL.

4. Notification stats
* Once the campaign is sent out, the campaign stats should show the impressions and clicks.

# Success Criteria
1. A push token has to be generated for the users.
2. Notifications should be displayed correctly.
3. The redirection(3 different types) should work as expected.
4. The Impressions and clicks have to be captured.
5. In case of rich notifications(if present), check for the image rendering, notification sound, buttons, their redirections, and so on.
# Potential issues and Solutions
1. A push token has to be generated for the users. To fix Push Token-related issues, please check [iOS](/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial) docs.
2. Notification should be displayed correctly.
3. The redirection(3 different types) should work as expected.
4. The Impressions and clicks have to be captured. To fix the Impression, or click-related issue, please check [iOS](/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial) docs.
5. In case of rich notifications(if present), check for the image rendering, notification sound, buttons, their redirections, and so on. To fix the Rich Push-related issue, please check the [iOS](/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial) docs.
6. Note - By default iOS impression tracking was not present in the earlier version but from iOS 10, this can be integrated using [Notification Service extension](/docs/developer-guide/ios-sdk/push/basic/ios-push-integration-tutorial) capabilities.
# Push Templates Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/push-templates-integration-validation
Test and validate push notification templates including basic, stylised, and carousel formats across Android and iOS devices with MoEngage SDK.
This helpful article covers specific Push Templates Testing across Android and iOS platforms.
# What we want to Validate
Ensuring if we are getting Basic, Stylised, and Carousel push notifications on the device.
# How to do validation
* First, we should get the app build for Android/iOS after it is integrated with MoEngage SDK.
* Once we install the app build on our device then open the app and do browse it once.
* Now we should go to the MoEngage dashboard and create push campaigns as in the below screenshot.

* In the next step of push campaign creation, enter your campaign details and then choose your content. You will find three options Basic Notification, Stylised Push Notification, and Simple Image Carousel Push Notification as in the below screenshot.

* **Basic Push Notification** - It is a basic push notification layout with no design but key parameters for push like Message Title, Message Body, and summary. You can fill in these details and test the push received on the device.

* **Stylised Push Notification** - It is stylised push notification layout with advanced design options with the same key parameters for push like Message Title, Body, and Summary. You can fill in these details and test the push received on the device.

* **Image Carousel Push Notification** - It is stylised image carousel push notification layout with advanced design options and also extra key parameters for push like Message Title, Body and Summary, and action slides for multiple images. You can fill in these details and test the push received on the device.

## Success Criteria
**Basic Push Notification** - It should display as in the below screenshot.

**Stylized Push Notification** - It should display as in the below screenshot.

**Image Carousel Push Notification** - It should display as in the below screenshot.

# Potential Issues and Solutions
If the Push Templates feature is not implemented then the Stylised Push and Carousel push with image cannot be used for campaigns. To fix Push Templates-related issues, please check [Android](/docs/developer-guide/android-sdk/push/optional/push-templates) and [iOS](/docs/developer-guide/ios-sdk/push/optional/push-templates) docs.
# User Property/Profile Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/user-attributeprofile-integration-validation
Verify that user properties like login ID, email, and phone number are tracked correctly in MoEngage across Android, iOS, and web platforms.
This help article covers User Profile Testing for Login/Logout/User Properties-related information across Android, iOS, and website platforms.
# What do we want to Validate?
Ensuring that Login ID, Email, Phone, and any other User Properties are tracked correctly
# How to validate?
* First, we should get the app build for Android/iOS or Website after it is integrated with MoEngage SDK.
* Once we install the app built on our device or open the website, we should log in with personal information like Email Address, Phone Number, Social Login, and so on according to the app/website design.
* After your login is successful, the App/Website should capture data and your user profile will be created on MoEngage Dashboard.
* After successful login, we can search on the MoEngage segmentation dashboard using the Email, Phone, or ID as tracked by the app/website as below and if the user is created, the result will display the count as 1. [User profiles](/docs/user-guide/data/user-data/user-profile) can be seen by clicking on the person icon inside the Sample Users section as shown below.


* We should be verifying ID, Email, Phone and other User Properties are correctly mapped on the MoEngage dashboard as described. Few user properties are tracked by MoEngage SDK as standard user properties and they are shown under **Tracked Standard Attribute**.

* If any custom user properties are tracked, these can be found as described. In addition to standard user properties which are not tracked by MoEngage SDK, these are shown under **Tracked Custom Attribute**.

# Success Criteria
* ID is one of the most important data points in the MoEngage system. For any user, tracking user properties are important but ID is compulsory for any registered users. If ID is not specified for a user as unique then further user merging and profile management across Android, iOS, Web or any analytics system tracking will not be synchronized to a single profile. If the Login ID is set correctly on the login of the app/website, the user profile will display as described. Similarly, all other user properties should be tracked. To fix Login ID-related or user properties issues, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking)

* If the app has a Logout feature and it is implemented correctly then click the Logout button, it is tracked successfully and should display as described along with platform names like Android, iOS, or web. To fix the log-out issue, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking).

# Potential Issues and Solutions
* If the Login ID is not correctly set while logging in to the app/website, it can lead to corrupted user data.\
To fix the Login ID-related issue, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking).
* If Login ID, Email, Phone, or any other user properties are not correctly tracked in the user profile it can lead to data corruption for Push, SMS, and Email Channel communication along with performance statistics can be problematic. To fix User properties-related issues, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking).
* If User Logout is not tracked at the time of user logging out then data can be corrupted. To fix the Logout issue, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking).
# User Events Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/user-events-integration-validation
Validate that user events, event properties, and data types are tracked correctly in MoEngage. Check event tracking from app activity to your dashboard.
User events integration is one of the most important parts of the entire integration. To ensure that the events are flowing correctly to MoEngage, we can follow the steps below.
# What is to be validated?
* Events Tracking is working as expected.
* All the attributes are being tracked
* The data types of the attributes are correct
# How to Validate?
## Check Event Tracking
* On the app, perform the events that need to be tracked on MoEngage
* Open the [user profile](/docs/user-guide/data/user-data/user-profile) on the MoEngage Dashboard and go to the Activity info
* You should be able to see all the events performed in this section.

## Check the Event properties
* Click an event on the activity info page. This will expand the event and display the event properties.
* Check for all the attributes that need to be passed with the event
* Event Source has to be SDK, Platform has to be the type of device where the event is performed and type has to be tracked user events.

## Check the attribute data types
* String data type attributes should have string-related operators like is, contains, starts with, etc
* Date attributes should have operators like on, in between, before after, etc
* Number attributes should have operators like equal to, greater than, in between, etc

# Potential Issues and Solutions
* Unique Event Name - It is most important to track unique names for events across platforms.
* Event properties Data Type - It is also important to maintain datatype consistent across platforms.
* Without the proper event tracking the user behavior cannot be identified, and automated campaigns cannot be created. To fix events-related issues, refer to [Android](/docs/developer-guide/android-sdk/data-tracking/basic/track-events), [iOS](/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-events), and [Web](/docs/developer-guide/web-sdk/data-tracking/web-sdk-events-tracking) docs.
# Web Push Notifications Integration Validation
Source: https://moengage.com/docs/user-guide/getting-started/integration-validation/web-push-notifications-integration-validation
Validate web push notification integration with MoEngage step by step. Test push token generation, notification delivery, and click tracking on browsers.
This article explains Web Push Notifications Integration validation manually in a stepwise manner.
# What is to be Validated?
To make sure Push notifications are working properly.
# Validation Procedure
1. Push Token Generation
* On [your profile](/docs/user-guide/data/user-data/user-profile) page, the Web push icon has to be green.

* You can also check this by installing the MoEngage extension on your browser. [Link](https://chrome.google.com/webstore/detail/moengage-sdk/dhggnkfnnoebbfofpimfehcklnekmbgi)
.png?fit=max\&auto=format\&n=ug1DZn3QSotOzs8r\&q=85\&s=31b9da4a3a506533a257266d399dc73d)
2. Push notification received on the device
* Create a general Push campaign on the Dashboard for your device
* Test the notification from the test option at the 3rd stage of creation.
* If you get a successful response, create a campaign. In the case of failure, check for the failure reasons.
.png?fit=max\&auto=format\&n=ug1DZn3QSotOzs8r\&q=85\&s=759d302a4fad80380a9fde7f496c262e)
3. Notification Redirection
* Provide the redirection URL while creating the campaign. And once the message is received click on it and check if it is redirecting you to the URL

4. Notification stats
* Once the campaign is sent out, the campaign stats should show the impressions and clicks.
.png?fit=max\&auto=format\&n=ug1DZn3QSotOzs8r\&q=85\&s=f7845710816472431dbe7f14ea28d06f)
# Success Criteria
1. Push token has to be generated for the users
2. Notification should be displayed correctly
3. The redirection should work as expected
4. The Impressions and clicks have to be captured.
# Potential issues and Solutions
1. If tokens are not generated correctly, the reachable user base will be less than the actual users. To fix issues related to tokens, please check the [Web](/docs/developer-guide/web-sdk/web-push/web-push-overview) SDK docs.
2. Incorrect Redirection will lead to confusion/miss in opportunities.
3. If the clicks and impressions are not recorded, we cannot understand the impact of the campaign. To fix impressions and click tracking issues, please check the [Web](/docs/developer-guide/web-sdk/web-push/web-push-overview) SDK docs.
# Custom Proxy Sub Domains
Source: https://moengage.com/docs/user-guide/getting-started/integration/custom-proxy-sub-domains
Configure custom proxy subdomains to bypass ad blockers and ensure reliable MoEngage data tracking. Set up DNS delegation for first-party traffic.
To bypass ad blockers and ensure consistent data tracking, MoEngage utilizes a DNS delegation process. This involves carving out a specific subdomain of your primary domain and authorizing MoEngage to manage the DNS records for that subdomain. This approach ensures reliable data capturing and campaign delivery by appearing as first-party traffic.
## Recommendations for Choosing a Subdomain
To maximize the effectiveness of this feature and avoid being flagged by ad-blocking lists, follow these recommendations when selecting your subdomain:
* **Avoid Tracking Keywords:** Do not use names like *track*, *ads*, or *moengage*. Many ad blockers use keyword-based filtering.
* **Use Neutral Terms:** Consider using random strings or unrelated dictionary words (e.g., `cn.example.com`, `data.example.com`, or `mx-events.example.com`).
* **Keep it Short:** Aim for a length of 5–8 characters to maintain efficient URL structures.
## The Onboarding Process
Setting up DNS delegation is a collaborative process between your technical team and MoEngage Support.
1. **Select your subdomain:** Choose a subdomain based on the recommendations above (for example, `xyz.example.com`).
2. **Inform MoEngage:** Share the chosen subdomain with your MoEngage account team or [raise a support ticket](/docs/user-guide/contact-support/raise-a-support-ticket-from-the-moengage-login-page).
3. **Receive Name Servers:** The MoEngage SRE team will create a DNS Zone and provide you with a list of Name Server (NS) records.
4. **Update Parent Domain:** Add the provided NS records to your parent domain's DNS configuration. This action delegates control of the subdomain to MoEngage for traffic routing.
5. **Verification:** MoEngage will monitor the delegation status. Once verified, the necessary infrastructure endpoints will be mapped to your custom subdomain.
6. **Configure the SDK:** After successful delegation and verification, update your SDK initialization logic to use the custom proxy domain. Refer to the specific implementation guides below:
* [Android SDK](https://www.moengage.com/docs/developer-guide/android-sdk/sdk-integration/advanced-or-optional/custom-proxy-domain-android)
* [iOS SDK](https://www.moengage.com/docs/developer-guide/ios-sdk/sdk-integration/advanced/custom-proxy-domain-ios)
* [Web SDK](https://www.moengage.com/docs/developer-guide/web-sdk/web-sdk-integration/advanced-integration/custom-proxy-domain-web)
> [!NOTE]
>
> **Note on Propagation**
>
> DNS changes can take between 24 to 72 hours to propagate globally. You can verify the status of your NS records using online tools like DNSChecker.
## Specific Provider Instructions
Most major DNS providers support subdomain delegation via NS records. Refer to your provider's documentation for specific instructions on "NS Record Management" or "Subdomain Delegation":
* [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/subdomains-outside-cloudflare/)
* [AWS Route53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingDevelopingManagingDNS.html)
* [Akamai](https://techdocs.akamai.com/cloud-computing/docs/ns-records)
* [IBM NS1](https://www.ibm.com/docs/en/ns1-connect?topic=zones-subdelegations-child#subdelegations_child_zones__title__2)
# Default Android SDK
Source: https://moengage.com/docs/user-guide/getting-started/integration/default-android-sdk
Review the default events, user properties, and device information automatically collected by the MoEngage Android SDK during integration.
This article lists all information that MoEngage Android SDK collects by default.
## Default Events
MoEngage Android SDK collects the following events:
| **Event Name** | **Description** |
| - | - |
| User Logout | Tracked when a user logs out of the app or website, or when the user does reset. |
| Viewed Web Page | Tracked when a user visits a web page. Select the page URL as an event property to find the number of users visiting a particular page or use it to set up a "Drop-off capture" Event-Triggered Web Push. |
| Notification Received Android | Tracked when a user receives a notification on the Android device. |
| Notification Clicked Android | Tracked when a user clicks the notification on the Android device. |
| In-App Shown Android | Tracked when an In-App message is shown to the user on the Android device. |
| In-App Clicked Android | Tracked when a user clicks an In-App message on an Android device. |
| In-App Closed Android | Tracked when a user dismisses an In-App message by clicking the close button on an Android device. |
| In-App Rating Done | Tracked when a user submits a rating through an In-App campaign. |
## Default User Properties
MoEngage SDK provides helper methods or APIs for tracking the commonly used or tracked user properties. You must use the helper methods for tracking these attributes. The following is the list of attributes for helper methods:
* User ID
* First Name
* Last Name
* Full Name
* Email ID
* Mobile Number
* Gender
* Location
For information on using the helper methods, refer to [Track User Attributes](https://www.moengage.com/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes).
## Device Information
MoEngage Android SDK collects the following device attributes:
| **Identifier** | **Optional** |
| - | - |
| OS Version | No |
| API level | No |
| Model Name | No |
| Product Name | Yes |
| Manufacturer | Yes |
| Google Advertising Identifier (GAID) | Yes |
| GAID tracking status | Yes |
| Carrier | Yes |
| Device Density | Yes |
| Device Width | Yes |
| Device Height | Yes |
| Android Id | Yes |
| Network Type | No |
| Device Timezone | No |
> [!NOTE]
>
> * The MoEngage SDK tracks certain device data, some of which are optional. By default, these optional attributes are disabled or 'opted-out'. To enable these optional attributes, call the corresponding methods in the MoEngage SDK.
> * Device information is collected but not available for analysis as of now on the MoEngage Dashboard.
For information about MoEngage-generated events and attributes, refer to [Derived Events and Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes).
# Default iOS SDK
Source: https://moengage.com/docs/user-guide/getting-started/integration/default-ios-sdk
See the complete list of default events, user properties, and device data collected automatically by the MoEngage iOS SDK after integration.
This article lists all the information that MoEngage iOS SDK collects by default.
## Default Events
MoEngage iOS SDK collects the following events:
| Event Name | Description |
| - | - |
| INSTALL/UPDATE | Tracked on calling the appStatus(\_:) method of SDK. |
| REINSTALL | Tracked on reinstalling the app. |
| MO_PUSH_PREFERENCE_CHANGED | Tracked on change of App Push Permission settings in iOS. |
| NOTIFICATION_RECEIVED_IOS_MOE | Tracked on receiving the notification. |
| NOTIFICATION_CLICKED_IOS_MOE | Tracked on clicking the notification. |
| NOTIFICATION_DISMISSED_IOS_MOE | Tracked on dismissing the notification. |
| MOE_GEOFENCE_HIT | Tracked on triggering a Geofence. |
| MOE_IN_APP_SHOWN | Tracked when In-App is shown. |
| MOE_IN_APP_CLICKED | Tracked when In-App is clicked. |
| MOE_IN_APP_DISMISSED | Tracked when In-App is dismissed by the Close button. |
| MOE_IN_APP_AUTO_DISMISS | Tracked when In-App is automatically dismissed without user action. |
| MOE_APP_RATED | Tracked when a user gives a rating through In-App campaign. |
| DT_CAMPAIGN_SCHEDULED | Tracked when a real-time trigger campaign is scheduled to be shown later. |
| DT_CAMPAIGN_SCHEDULE_FAILED | Tracked when an error occurs while scheduling a real-time trigger campaign. |
| MOE_APP_EXIT | Tracked when the app goes to the background. |
| MOE_LOGOUT | Tracked when the resetUser method of SDK is called. |
## Default User Properties
MoEngage iOS SDK collects the following user properties. For information on passing this information to MoEngage, refer to [Tracking User Properties](https://www.moengage.com/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes).
| **User Property Name** | **Description** |
| - | - |
| USER_ATTRIBUTE_UNIQUE_ID | Unique ID for a user |
| USER_ATTRIBUTE_USER_NAME | Full name of the user |
| USER_ATTRIBUTE_USER_FIRST_NAME | First name of the user |
| USER_ATTRIBUTE_USER_LAST_NAME | Last name of the user |
| USER_ATTRIBUTE_USER_EMAIL | The email address of a user |
| USER_ATTRIBUTE_USER_MOBILE | Mobile number of the user |
| USER_ATTRIBUTE_USER_GENDER | Gender of the user |
| USER_ATTRIBUTE_USER_BDAY | Birth date of the user (tracked when setUserDateOfBirth() is called with an NSDate instance of the user’s DOB) |
| USER_ATTRIBUTE_USER_LOCATION | Latitude and longitude of the user |
| ADVERTISING_IDENTIFIER | IDFA of the device |
| USER_PUSH_PREFERENCE | User Push preference tracked using the SDK method trackUserPushPreference(\_:forAppID:) |
| gdpr_push_opt_out | GDPR Push opt-out status (true or false) |
## Device Information
MoEngage iOS SDK collects the following device attributes:
| **Identifier** | **Information** | Optional |
| - | - | - |
| ADVERTISING_IDENTIFIER | IDFA (an alphanumeric string unique to each device used only for serving advertisements) - [Reference link](https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier "https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier") | Yes |
| device_IDFV | identifierForVendor (an alphanumeric string that uniquely identifies a device to the app’s vendor) - [Reference link](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor "https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor") | Yes |
| device_tz | Device timezone | No |
| model | Device model type (for example, "iPhone" or "iPad") | No |
| model_name | Specific device model name (for example, "iPhone 7" or "iPhone X") | No |
| os_ver | Current iOS version of the device | No |
| moe_push_opted | Current Push preference set in the device settings (true or false) | No |
> [!NOTE]
>
> Only ADVERTISING IDENTIFIER is available on the dashboard for segmentation and analytics usage as of now. IDFA and IDFV will not be collected if data tracking is opted out with GDPR opt-out methods.
For the list of all MoEngage-generated events and attributes, refer to [Derived Events and Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes).
# Default Web SDK
Source: https://moengage.com/docs/user-guide/getting-started/integration/default-web-sdk
Explore the default events, user properties, and device information collected by the MoEngage Web SDK. Includes event properties and tracking details.
This document lists all the information which is collected by default with Web SDK.
# Default Events
Following are the events collected by MoEngage Web SDK
| **Event Name** | **Description** |
| - | - |
| Unsubscribed from Web Push | When the user Unsubscribe from the Web Push |
| Viewed Web Page | Tracked when a user visits a page |
| Viewed Web Push Soft-ask | Tracked when the soft ask is shown to the user |
| Closed Web Push Soft-ask | When soft ask is closed or denied by the user |
| Accepted Web Push Soft-ask | When soft ask is allowed by the user |
| Subscribed to Web Push | Web push subscription is successful. Received the push token. |
| Displayed Web Push Subscription | When hard ask is shown to the user |
| Allowed Web Push Subscription | When hard ask is allowed to the user |
| Dismissed Web Push Subscription | When hard ask is closed to the user |
| Denied Web Push Subscription | When hard ask is denied to the user |
| Onsite Message Template clicked | On clicking the Onsite Messaging template |
| Onsite Message Template shown | On a load of Onsite Messaging template |
| Onsite Message Template closed | On closing the Onsite Messaging template |
| Onsite Message Template auto dismiss | When the Onsite Messaging template closes by itself after the time duration given while creating the campaign |
| Web Personalization clicked | On clicking the Web Personalization (should be called by the client like data.click()) |
| Web Personalization shown | On showing the Web Personalization (should be called by the client like data.imp()) |
| Web Personalization delivered | When the Web Personalization call is successfully delivered. |
| Notification Received Web | Tracked when a user receives a notification on the browser |
| Notification Clicked Web | Tracked when a user clicks the notification on the browser |
# Event Property Info
Following are the device attributes collected by MoEngage Web SDK
| **Attribute Name** | **Description** |
| - | - |
| URL | Current URL of the page |
| moe_logged_in_status | Boolean value states whether the user is logged in or not |
| moe_first_visit | Boolean value states whether the user is visiting the page first time or not |
# Default User Properties
The following are the user properties that can be collected by MoEngage Web SDK.
1. First Name
2. Last Name
3. Full Name
4. Email Id
5. Mobile Number
6. Gender
7. Birth Date
Click [here](https://www.moengage.com/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking) for information on passing this information to MoEngage.
# Device Info
Following are the device attributes collected by MoEngage Web SDK
| **Identifier** | **Information** |
| - | - |
| os | Web / MWeb |
| os_platform | User Agent. Information about the browser |
| os_ver | Browser Name |
| model | Browser Name |
| device_ts | Device Timestamp |
| device_tz | Device Timezone |
| push_id | Push token generated by SDK |
> [!NOTE]
>
> Device information is collected but not available for analysis as of now on the MoEngage dashboard.
Click [here](/docs/user-guide/data/event-data/derived-events-and-attributes) for information on the list of all MoEngage-generated events and attributes.
# Integration Checklist
Source: https://moengage.com/docs/user-guide/getting-started/integration/integration-checklist
Follow this MoEngage integration checklist to track user attributes, events, and SDK features. Ensure your app or website setup covers all essentials.
To make sure that you extract maximum benefit for your app/website from MoEngage, we list some of the essential building blocks to be used during integrations that can enable a world of features for you to use and enrich the experience of your customers through the right engagement campaigns. To integrate the SDKs, see the [SDK Integration Guide](/docs/developer-guide/introduction).
**Track all User Properties, Events and Event Properties**
It is recommended to track all the user properties, events & event properties exhaustively so that all your use-cases get covered and you can make effective use of our powerful segmentation features.
**Also, track Conversion goals and Attributes**
Conversion goal help in attributing the success of a campaign to a particular goal such as Purchasing an item, booking a ticket etc. As part of tracking events and their attributes, it is recommended to consider and track such events as potential conversion goals for monitoring campaign performance. Along with conversion goal events, their attributes can help in quantifying the goal achievement such as total revenue earned, total bookings done etc. You can then understand which campaigns are doing better in terms of conversion goal events and understand consumer behaviour better.
**Set up Push Notifications**
Push notifications need platform-specific setup in addition to the base SDK integration. Configure push for each platform your app or website supports: [Android](/docs/developer-guide/android-sdk/push/basic/push-configuration), [iOS](/docs/developer-guide/ios-sdk/push/basic/push-notifications), and [Web](/docs/developer-guide/web-sdk/web-push/configure-and-integrate-web-push). If you use a cross-platform framework such as React Native or Flutter, follow the push setup in that framework's SDK guide.
**Enable Deep-linking and define Screen Names**
You should also enable deep-linking and define all the activities or screen names at the time of integration. This would help you take the users to specific screens when a user clicks on the notification.
**Enable Transaction APIs**
You should integrate Transactional APIs to enable push for server events from your server. [*Read more about Transactional APIs in our docs here*](https://www.moengage.com/docs/api/inform/inform-overview).
**Enable Data APIs**
In case you want to pass additional data about your users to MoEngage, you should get Server Server Communication integration implemented. [*Read more about Data APIs in our docs here*](https://www.moengage.com/docs/api/data/data-overview).
**Create a Notification centre in your app/website**
To let your customer view the history of any promotions and notifications, it is recommended to get the notification Centre implemented, which acts as an inbox for all your notifications.
**Configure your email connector**
You must get your email connector integrated along with SMTP settings to enable you to send email campaigns
**Implement Nudge in-app notification**
Nudges are tiny embedded units which do not block the user’s flow. They have advanced segmentation capabilities and can be useful to show messages in a non-intrusive way to the users. Great for showing recommendations and announcements. **You can use nudges only when App open is used as a Trigger condition for InApp campaigns.**
*You are now fully set up to access the MoEngage Dashboard to create powerful segments and target these segments with smart engagement campaigns.*
# Reinstall Tracking
Source: https://moengage.com/docs/user-guide/getting-started/integration/reinstall-tracking
Track app reinstalls in MoEngage to distinguish returning users from new installs. Prevent duplicate onboarding campaigns and improve activation flows.
Many times, it is important for you to know the users who have reinstalled the app so that you can treat them separately in your user flows and other marketing segments and communications.
We have seen a lot of our users give out first-purchase discount coupons. Because of the inability to differentiate between Install and Reinstall, the onboarding / first purchase campaigns are sent to the same user after every reinstall by the user. To prevent this from happening, we now allow our users to track reinstalls for their users which makes their first purchase/activation campaigns more effective.
MoEngage tracks the reinstalls happening on your iOS and Android apps automatically.
## Reinstall Tracking on iOS
MoEngage iOS SDK can detect when a reinstall happens on any specific device for a particular app basis two distinct anonymous ids that are saved locally on the device and changed when a reinstall happens. When a reinstall is detected, MoEngage iOS SDK will track an event - "REINSTALL" and this can be used to exclude users who reinstalled the app from your campaigns.
## Reinstall Tracking on Android
Reinstalls on Android are detected differently than on iOS and may not be completely accurate. Nevertheless, we allow our users to track reinstalls for their android app users as well.
### How do we track reinstalls on Android?
For tracking reinstalls on Android, we depend on Google Advertising Id, unique_id which is saved locally by the SDK, and push token (FCM token) which changes on every reinstall. By observing and detecting a change in the push token and unique_id saved by the SDK, we can predict if a user has reinstalled the app.
Please note that reinstalls can only be tracked for up to 60 days. Meaning, if a user reinstalls the app after 60 days of uninstalling, we would not be able to identify a reinstall.
## Data Tracking for ReInstalls
Every time a reinstall is detected on Android or iOS, MoEngage will track the below data points automatically which you can use in your Segmentation / Analytics / Campaigns as required -
### USER PROPERTIES
* **Device Reinstall**: Every time a reinstall is detected, we save Device Reinstall: True in the user profile.
* **User Reinstall**: Every time a reinstalled user logs into an already identified (existing user where ID exists) user in MoEngage, we save an attribute User Reinstall: True in the user profile.
User Properties for reinstall are generally used in your Event Triggered Campaigns, Flows, and Analytics.
### EVENTS
* **Device Reinstall**: This event is tracked every time a reinstall is detected.
* **User Reinstall:** This event is tracked when a reinstalled user logs into an already identified (existing user where ID exists) user in MoEngage who is marked as uninstalled (Install Status: False) and because of the login, the status user gets marked as installed (Install Status: True).
Events for reinstall are generally used in Segmentation and Analytics.
### Limitations
1. If a user clears data on the device and push_id is also changed - In this case we will treat it as a case of “reinstall” instead of “data cleared on existing device”
2. If a user uninstalls the app resets Google Advertising Id and installs the app again, we will treat it as a new install.
3. If you have opted out of GAID tracking (Google Advertising Id), reinstall tracking will not work.
4. If the push token changes without the user uninstalling the app and the user logs out of the app at the same time, we may end up detecting this user as a reinstall.
# Migrate or Transfer Push Tokens
Source: https://moengage.com/docs/user-guide/getting-started/migrate-to-moengage/migrate-or-transfer-push-tokens
Migrate push tokens from your previous platform to MoEngage seamlessly. Ensure uninterrupted push notification delivery during your platform transition.
# Introduction
Brand Marketers transitioning from other platforms to MoEngage want to migrate their historical user-device data to the MoEngage platform to start leveraging the platform's capabilities to the fullest extent without any delay. As part of the transition process, the end-users of the brand need to upgrade to the new version of the brand-app which is integrated with MoEngage SDK. This typically involves a delay as the entire user-base of the brand slowly moves to the new version.
This article provides you with information on various methods that can assist you in seamlessly migrating the historical data of your users and their devices to MoEngage using server-to-server APIs. These methods simplify your migration journey, making it more convenient.
# Use Cases
For a brand/business with a substantial user base, it takes time for all users to transition to the upgraded app version, delaying reaping the benefits of the platform. However, for users who have already installed the updated app version that includes the MoEngage SDK, it begins tracking their data immediately.\
This gives rise to some scenarios, as mentioned below, and this article provides the solution for each scenario:
## Scenario 1:
Users who have not upgraded to the latest app version integrated with MoEngage SDK cannot receive push notifications triggered from MoEngage platform.
## Solution: Push token migration using Track Device API
Because a substantial user-base have not yet upgraded to the latest app version, MoEngage SDK cannot yet track their user-device properties and events. Instead of waiting for the entire user base to update their apps to the version which is integrated with the MoEngage SDK, you can use the Track Device API to import Push tokens already available to you into MoEngage. Track Device API or Bulk Import API helps you to create/update devices of existing users.
Using [Track device API](https://www.moengage.com/docs/api/device/track-device), you can seamlessly migrate the already available device information with you, such as Push token, GAID/ IDFV and platform information into MoEngage. MoEngage validates and accepts unique values of Push token, GAID/IDFV and platform of every device attached to the user.
Once above device information is ingested successfully into MoEngage, you can trigger Push campaigns from the MoEngage platform.
> [!NOTE]
>
> **iOS device behavior**:
>
> * This method of Push notification delivery by migrating device attributes using Device API and sending push campaigns from the MoEngage platform is applicable only to iOS devices. Android devices with later versions of AndroidOS still require MoEngage SDK to render Push notifications. Further, such notifications will launch the app but will not be able to redirect to a specific page in the app, make sure to frame the title, subtitle and message content of the push notification accordingly.
> * Although Push notifications will be delivered for iOS devices, corresponding campaign stats such as *Push notification clicked* will not be tracked, as these events are tracked by MoEngage SDK which may not be integrated with the app version used by end-users during migration.
>
> **Track Device API reachability behavior**:
>
> * When you pass a push token using the Track Device API, reachability is only updated if the device is currently marked as *Installed*. If a device is marked as *Uninstalled*, updating the `push_id` or `moe_push_opted` using Track Device API will not affect its reachability (it will remain Unreachable). To change a device's status back to *Installed*, the MoEngage SDK must actively track the device.
## Scenario 2:
Nudge users to upgrade to the latest app version integrated with MoEngage SDK by effectively targeting them.
## Solution: Migrate User Device Information Using Bulk Import API
As a marketer, you can create users and their devices using the [Bulk Import API](https://www.moengage.com/docs/api/bulk/bulk-import-users-and-events) of MoEngage. You can then assign a custom user property with a corresponding value to indicate users who should be notified about the app version upgrade.\
For example, consider the custom user property *bulk_migration* and its value to be set to *true* for the users who have not upgraded to the latest app version. You can use this custom user property to create a segment, as explained below:
### Create a Segment
Perform the following steps to create a segment that contains the users who have not performed the app upgrade:
1. On the left navigation menu in the MoEngage dashboard, click **Segment** > **Create segment**.
2. Click **Filter users by**, and then click the **User property** tab.
3. In the **Select attribute** list, select the custom user property you created to mark the migrated users. In this use case, the custom user property is *bulk_migration* set to *true*.

4. Perform the remaining steps to create the segment. For more information, refer to [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
After creating the segment, you can send campaigns to target the users in this segment and nudge them to upgrade to the latest app version integrated with MoEngage SDK.
# Feature or Product in Beta
Source: https://moengage.com/docs/user-guide/getting-started/overview/feature-or-product-in-beta
Understand what a beta release means in MoEngage. Learn the difference between open and closed beta features, and what to expect from beta products.
The Beta tag around a product or feature indicates that the respective product or feature is not released to the public, but is an open or closed beta release.
# What is a Beta Release?
MoEngage does a beta release when the product feature is complete and all the development is done but the feature may have some bugs and performance issues. This release is mostly done for users who want to test the product, use it cautiously, and report bugs.
# What is a Closed or Open Beta Release?
When the product or feature in beta is exposed to all the customers, it is called an Open Beta Release. When the product or feature in beta is exposed only to a limited or closed group of customers, it is called a Closed Beta Release.
# What does a Beta Feature Mean for MoEngage Users?
If you are seeing any beta product or feature, you are among the users or clients who would have either requested the feature, or the Product team at MoEngage would have considered the product or feature relevant to you.
You must be cautious while using any beta feature because it might have some low-impact bugs that might have escaped testing (QA). It will be great if you report any bugs or performance issues that you face while using the product or features in beta. It will help MoEngage to improve your experience and deliver a bug-free product.
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Terms to Know
Source: https://moengage.com/docs/user-guide/getting-started/overview/terms-to-know
Familiarize yourself with key MoEngage terms and concepts before getting started. Covers definitions like Merlin AI and core platform vocabulary.
These terms can help you as you begin your journey on MoEngage.
| Term | Definition |
| - | - |
| A/B & Multivariate Testing | Multivariate or split testing are experiments that marketers conduct by modifying one or more variables to determine the effect on a campaign. A/B testing compares two versions of a message against each other by sending them to equal, randomly chosen groups of users to see which performs better, and is used when testing only one variable. Multivariate testing sends more than two variations of a communication to different randomly chosen users to compare their performance. For more information, refer to [Overview](/docs/user-guide/ai-and-intelligence/ab-testing/what-is-ab-or-multivariate-testing/overview). |
| A/B Split in Flows | A/B Split lets you test up to five variations of flow paths to determine which is the best-performing option. You can experiment with different channels, different messages on the same channel, and different message frequencies across these flow paths. After analyzing the performance of each branch, you can change the user distribution in favor of the winning branch. For more information, refer to [A/B Split in Flows](/docs/user-guide/flows-cross-channel-messaging/create/experimentation/ab-split-in-flows). |
| Affinity Segments | Affinity segments group and target users based on their personalities, lifestyles, beliefs, and choices as displayed within your app. You can analyze personality traits to understand users better, such as finding users who listen to a particular artist most often or who book cab rides during a specific time window. Use these segments to tailor campaigns to each group's preferences and habits. For more information, refer to [Affinity Segments](/docs/user-guide/segment/create-segments/affinity-segments). |
| AIRA (Support Bot) | AIRA (Artificial Intelligence Resolution Agent) is the MoEngage generative AI support bot. It addresses your queries by referencing an extensive knowledge base and custom workflows, and can escalate complex issues by creating support tickets. AIRA is available 24/7. For more information, refer to [AIRA Overview](/docs/user-guide/contact-support/aira-support-bot/aira-overview). |
| Analytics | MoEngage Analytics helps you understand how users interact with your web and mobile apps. You can use it to track events and analyze trends to measure the performance of your app and campaigns. |
| Anonymous vs. Registered User | An anonymous user is someone who has not yet been identified by your website or app, such as a visitor who has not logged in or a new user who has not signed up. A registered user is someone who has signed up or logged in to your website or app. MoEngage assigns a non-changeable MoEngage ID to recognize a user as soon as they visit, and when the user signs up you pass a unique ID so they can be recognized across devices and platforms. For more information, refer to [Anonymous to Registered User Merge](/docs/user-guide/data/user-data/anonymous-to-registered-user-merge). |
| API | MoEngage APIs provide a web service where you can send actions taken by your users directly through HTTPS, rather than through the mobile SDKs or the web SDK. This allows you to pass user data to MoEngage that is not tracked within your app or website. For more information, refer to [API](https://www.moengage.com/docs/api/introduction). |
| Auxiliary Data | Auxiliary Data helps you import supplementary user information into an existing database for campaign personalization. Use it for short-term data that does not need permanent storage, such as limited-time offers, discounts, or promotions. You ingest the data through file imports and use it during campaign creation for the duration it stays relevant. For more information, refer to [Auxiliary Data](/docs/user-guide/data/imports/file-based-imports/auxiliary-data). |
| Behavior Analysis | Behavior Analysis provides insights into user interactions with your web and mobile applications. You can track specific events and assess emerging trends to evaluate the effectiveness of your product and marketing campaigns. It generates graphical charts for visualization and tabular reports for in-depth analysis. For more information, refer to [Behavior - Overview](/docs/user-guide/analyze/analytics/behavior/behavior-overview). |
| Best Time Analysis | Best Time Analysis is a dashboard that shows detailed hourly user activity over the past 24 hours for each channel. The charts help you identify the most preferred time slots for sending campaigns to your users, rather than sending communications to everyone at a fixed time. For each channel, you can find the best time slot to increase the chances of interaction or response. For more information, refer to [Best Time Analysis](/docs/user-guide/analyze/dashboards/best-time-analysis). |
| Best Time to Send (BTS) | Best Time to Send (BTS), also known as Send Time Optimization, provides a prescriptive time slot to send a campaign to a user to increase the chance of interaction or response. BTS is defined at a user level and analyzes historical user interactions with campaigns and channels separately for Push, Email, SMS, and MMS. This lets you target each user at their most preferred time slot instead of sending a communication to all users at a fixed time. For more information, refer to [Best Time to Send](/docs/user-guide/ai-and-intelligence/timing/best-time-to-send). |
| Business Events | Business events let you create events based on business actions rather than user actions, and run campaigns when these events occur. Unlike an event-triggered campaign that starts from a user action (such as viewing a webpage), a business event campaign starts from an action taken at the business end (such as a brand restocking an item). This lets you automate campaign delivery around internal business actions. For more information, refer to [Overview - Business Events](/docs/user-guide/campaigns-and-channels/getting-started/triggers/business-event/overview-business-events). |
| BYOK (Bring Your Own Key) | By default, MoEngage generates and manages the encryption keys used to protect your PII. Bring Your Own Key (BYOK) gives you direct control over the master encryption key, so no one, including MoEngage, can access your users' PII without involving your key. It is an add-on to PII Data Encryption and requires manual enablement by the MoEngage team. For more information, refer to [Bring Your Own Key (BYOK) For PII Data Encryption](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/-bring-your-own-key-byok-for-PII-data-encryption). |
| Campaign Approval Flow | Campaign approval allows Marketing teams to control or review the campaigns going live by implementing a creator-approver (maker-checker) approach. For more information, refer to [Campaign Approval Workflow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow). |
| Campaign Decisioning | Campaign Decisioning shifts campaign delivery from manual, rule-based targeting to automated, outcome-based decisions at the individual user level. Instead of asking "Who fits this segment?", the Campaign Decisioning Agent evaluates the probability that a specific user will convert if they receive a message. This real-time intelligence assesses every potential interaction before it occurs, enabling probability-based optimization at scale. For more information, refer to [Introduction](/docs/user-guide/decisioning/campaign-decisioning/introduction). |
| Cards | Cards are a customizable engagement channel for delivering personalized campaigns, offers, and recommendations that reside in the users' app inbox or news feed without interrupting their flow. You can use the MoEngage Cards Inbox or Self-handled Cards to deliver Card campaigns. Once delivered, a card remains part of the user's app experience, and unlike other channels it requires no opt-in. For more information, refer to [Cards Overview](/docs/user-guide/campaigns-and-channels/cards/getting-started-with-cards/cards-overview). |
| Catalogs | An item catalog is a prerequisite for creating and using recommendations. It is a list of all your business offerings with their relevant details, such as products, services, flights, articles, restaurants, dishes, and social media feeds. With the Catalog feature, you can create and manage item catalogs, connect them to MoEngage, and use the item information in your campaigns. For more information, refer to [Catalogs](/docs/user-guide/content/recommendations/prerequisites/catalogs). |
| Computed Traits | Computed traits are dynamic user properties created by applying calculations and transformations to the event data you already collect in MoEngage. They update automatically based on user behavior, letting you build richer user profiles for segmentation and personalization without manual uploads or developer effort. For more information, refer to [Computed Traits - Overview](/docs/user-guide/data/computed-traits/computed-traits-overview). |
| Connected Apps | MoEngage Connected Apps provide a low-code platform for integrating various data sources and channels. This platform lets marketers and partners connect their marketing technology stack, exchange real-time data, and create personalized customer interactions across sources and platforms. Connected Apps let you connect any app to MoEngage and send users, events, and segments from MoEngage to your own app. For more information, refer to [Overview](/docs/user-guide/campaigns-and-channels/connected-apps/getting-started-with-connected-apps/overview). |
| Connectors | Connectors let you plug MoEngage into external systems to push real-time data to, or pull data from, other owned or third-party platforms. A Connector campaign can retrieve real-time data from MoEngage or pass data to other analytics systems, helping you target users across all communication channels. For more information, refer to [Create a Connector Campaign](/docs/user-guide/campaigns-and-channels/connectors/create/create-a-connector-campaign). |
| Content APIs | A content API is an external API you set up to use dynamic data during MoEngage campaigns. You configure it under Settings > Advanced Settings by adding the API name, HTTP method, and other details, and you can personalize its parameters with user properties. For more information, refer to [Add a Content API](/docs/user-guide/settings/advanced-settings/add-a-content-api). |
| Content Blocks | Content blocks are reusable pieces of content, such as a header, footer, or call-to-action button, that you can use across multiple campaigns and channels. When you edit a content block, the change applies everywhere it is used, helping you maintain consistency and update at scale. For more information, refer to [Content Blocks](/docs/user-guide/content/content-blocks/content-blocks). |
| Control Group | A control group is a subset of the users you target with a campaign who do not receive the campaign communication, acting as a baseline for comparison. By measuring this group alongside your target groups, which do receive the communication, you can determine the true impact and effectiveness of your marketing efforts. For more information, refer to [Control Groups](/docs/user-guide/campaigns-and-channels/getting-started/introduction/control-groups). |
| Conversion Goals / Conversion Attribution | Multiple Conversion Goals in Flows let you track up to five user events that, when performed, reflect the success of your flow, and you can also track the revenue accumulated from one of the goals. You can use them to track intermediate steps a user takes toward the primary conversion goal, such as tracking "Add to cart" as a step toward "Purchase". For more information, refer to [Add Multiple Conversion Goals](/docs/user-guide/flows-cross-channel-messaging/create/actions-in-flows/add-multiple-conversion-goals). |
| Coupons | MoEngage Coupons let you allocate and distribute single-use coupons to eligible users. Single-use coupon codes are unique codes distributed to individual customers so that no two users receive the same coupon and each coupon can be used only once. You can send coupons to specific cohorts, such as new users for activation, inactive users for resurrection, or users who abandoned a purchase. For more information, refer to [Overview](/docs/user-guide/content/coupons/overview). |
| Custom Dashboards | Custom dashboards let you add custom analysis charts and reports tailored to your product and marketing needs. You can add multiple charts and reports to a dashboard and monitor them at the same time. You can create a custom dashboard as either a private dashboard or a workspace dashboard. For more information, refer to [Custom Dashboards](/docs/user-guide/analyze/dashboards/custom-dashboards). |
| Custom Segments | Custom segments let you save a user segment query under a name and reuse it across multiple pages in the MoEngage dashboard, instead of rebuilding the same query for each campaign, flow, or analysis. For more information, refer to [Custom Segments](/docs/user-guide/segment/new-ui-experience/custom-segments). |
| Data Archival (Retention) Policy | Data archival is the systematic process of removing inactive or dormant user data so your workspace focuses only on users who provide genuine engagement opportunities and business value. MoEngage uses it to balance platform performance and data hygiene with global privacy standards such as GDPR and CCPA. Every 14 days, MoEngage runs a process to remove inactive and unreachable users, events, and devices, and each entity has its own archival policy. Upon archival, the data points are deleted permanently. For more information, refer to [Data Archival (Retention) Policy](/docs/user-guide/data/key-concepts/data-archival-retention-policy). |
| Data Centers | MoEngage maintains multiple global data centers, and your account belongs to a specific one when you sign up. Your data center determines your dashboard access URL, SDK endpoints, and REST API endpoints. You can identify your data center from your dashboard URL after signing up. For more information, refer to [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
| Decision Policy | A Decision Policy is a rule-based engine that selects and ranks the most relevant offerings to display to a user or user segment. By grouping offerings and applying a defined ranking strategy, the policy presents only a few optimal offerings from a large pool. It defines the quantity of offerings to return, the offering pool to choose from, the selection strategy, and fallback offerings for users not eligible for any primary offering. For more information, refer to [Create Decision Policy](/docs/user-guide/decisioning/offer-decisioning/decision-policy). |
| Derived Events | Derived events are events that MoEngage generates by default, alongside derived attributes. You can use them in segmentation and analytics as filters to segment users. MoEngage groups them into categories such as lifecycle, acquisition, uninstall, reachability, and campaign activity. For more information, refer to [Derived Events & Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes). |
| Derived User Properties | Derived user properties are user properties that MoEngage generates by default, such as lifecycle stage and lifetime value (LTV). You can use them in segmentation and analytics as filters to segment your users. If Portfolio is enabled for your workspace, the behavior of derived user properties changes. For more information, refer to [Derived User Properties](/docs/user-guide/data/user-data/derived-user-attributes). |
| Do Not Disturb (DND) | Do Not Disturb (DND) lets you configure idle hours during which trigger notifications are not sent to users. This prevents Push, Email, SMS, MMS, and RCS messages from reaching users at odd hours. For more information, refer to [Do Not Disturb](/docs/user-guide/settings/channels/delivery-controls/do-not-disturb). |
| Dynamic Sender Routing | Dynamic sender routing is a routing system in MoEngage Inform that automatically selects the most appropriate sender for each API request. You define custom routing rules based on user properties or API attributes to improve deliverability, manage sending costs, and meet local compliance requirements. It is supported for the SMS and Email channels. For more information, refer to [Dynamic Sender Routing](/docs/user-guide/inform/advanced-concepts/dynamic-sender-routing). |
| Dynamic Template Selector | Dynamic Template Selector, available in MoEngage Inform through Rule-Based Templates, lets you serve the correct message variant for a single alert instead of creating multiple duplicate alerts. The template variation is selected in real time based on user or API attributes, rather than random percentage splits or optimization rules. For more information, refer to [Dynamic Template Selector](/docs/user-guide/inform/advanced-concepts/dynamic-template-selector). |
| Engagement Channels | A channel is the method you use to deliver messages to your users, such as a push notification on their phone or an email in their inbox. MoEngage supports a range of channels across mobile, web, messaging, and ad platforms, so you can engage your audience across different touchpoints. Choosing the right channel helps you deliver relevant content and achieve your campaign objectives. For more information, refer to [MoEngage Channels](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels). |
| Environment | Every MoEngage account for an app or web provides two different environments: TEST and LIVE. Each environment has its own Workspace ID, available under **Settings** > **Account** > **General settings**. For more information, refer to [Dashboard Overview](/docs/user-guide/getting-started/initial-setup/dashboard-overview). |
| Event Properties | Event properties (also called event properties) are the parameters associated with each tracked event that provide context and detail about the event and the user interaction it represents. They can include values such as user identifiers, timestamps, geographic location, device information, and other metadata. You use these attributes to segment and analyze event data and to personalize messaging. For more information, refer to [A Complete Guide to Event Tracking](/docs/user-guide/data/event-data/a-complete-guide-to-event-tracking). |
| Event Naming Conventions | Event naming conventions are the practices you follow when naming events to keep tracking consistent and clear across your implementation. Recommended practices include using clear, descriptive names, staying consistent, using lowercase with underscores or dashes, starting action-based events with verbs, including relevant context, avoiding abbreviations, and keeping names concise. Clear, human-readable names make events self-explanatory when you collaborate or analyze event data later. For more information, refer to [Event Naming Conventions](/docs/user-guide/data/key-concepts/event-naming-conventions). |
| Events | Events track the actions that users perform in your app or website. For example, launching an app, viewing a product, sharing a song, making a purchase, and so on. |
| Filter-based Segments | A rule-based (filter) segment is a group of users defined by specific properties, values, or rules applied to user properties, events, and event properties. MoEngage evaluates these rules against your data to produce a dynamic group of users, and segment membership updates as user data changes. You can use these segments to send campaigns or to analyze behavioral traits of users. For more information, refer to [Rule-Based (Filter) Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments). |
| Flows | A Flow is a cross-channel marketing automation tool for building multi-channel user journeys. It tracks user actions across platforms, analyzes them, and takes decisions based on them, so you can deliver an omnichannel experience instead of using channels in isolation. For more information, refer to [Overview - Flows](/docs/user-guide/flows-cross-channel-messaging/getting-started/overview-flows/overview-flows). |
| Frequency Capping (FC) | Frequency capping (FC) lets you control how often users receive campaign messages, preventing bursts of communication from multiple channels at once. You can configure it by channel or with tag-based rules. For more information, refer to [Frequency Capping](/docs/user-guide/settings/channels/delivery-controls/frequency-capping). |
| Funnels | A funnel represents a series of events that guide users toward a defined event, and is used to calculate conversion rates based on certain user actions. Funnels provide insights into user conversion across web and mobile applications, helping you understand user interactions at various stages of the customer journey. The resulting charts help you evaluate conversion rates at each stage and assess overall product performance. For more information, refer to [Funnels - Overview](/docs/user-guide/analyze/analytics/funnels/funnels-overview). |
| FUP | Fair Usage Policy (FUP) is a set of guidelines and rules implemented to ensure all customers have equal and non-discriminatory access to MoEngage resources. |
| In-App Message | In-app messaging lets you engage users while they are actively using your application. Unlike push notifications that appear outside the app, in-app messages display within the app's interface and are triggered by specific user actions or attributes. You can use them to drive conversions, show recommendations, onboard new users, and gather feedback. For more information, refer to [Overview - In-App Message](/docs/user-guide/campaigns-and-channels/in-app-message/getting-started-with-in-app-message/overview-in-app-message). |
| Inform (Transactional Alerts) | MoEngage Inform provides a unified messaging infrastructure across multiple channels to build and manage transactional alerts. A transactional alert is any time-sensitive transactional content that a brand sends to its customers, such as order confirmations, shipping updates, security and account alerts, password resets, and OTPs. For more information, refer to [Overview - Inform](/docs/user-guide/inform/overview-inform). |
| Intelligent Path Optimizer | Intelligent Path Optimizer lets you A/B test up to five branches in a flow, where Merlin AI automatically adjusts the user distribution toward the best-performing path. You configure the metric you want to maximize, which can be Engagement, Conversion, or both. If you prefer to handle the user distribution manually, you can use A/B Split instead. For more information, refer to [Intelligent Path Optimizer](/docs/user-guide/flows-cross-channel-messaging/create/intelligence-in-flows/intelligent-path-optimizer). |
| Key Metrics | Key metrics is a dashboard page that provides all important and necessary information for day-to-day use for marketers. A quick glance at the Key metrics page shows the usage, engagement, and performance metrics of the product. For more information, refer to [Key Metrics](/docs/user-guide/analyze/dashboards/key-metrics). |
| Landing Pages | A landing page is a dedicated webpage designed to capture a customer's attention when they click on a published campaign. These pages drive a customer toward a desired outcome, such as a product purchase, event registration, or opting in for more information. Unlike regular web pages, a landing page is minimal and tailored to a specific customer segment to keep visitors focused on the conversion goal. For more information, refer to [Overview](/docs/user-guide/content/landing-pages/getting-started-with-landing-pages/overview). |
| Localization | Localization lets you tailor your campaign messages to engage users across different languages, cultures, and regions. Using locales, you can adapt your message within a single campaign to deliver relevant content to different audience segments based on their language, geographic location, age, or gender. For more information, refer to [Localize Campaign Messages](/docs/user-guide/campaigns-and-channels/getting-started/campaign-content/localize-campaign-messages). |
| Merlin AI | Merlin AI is the machine-learning engine of MoEngage that adds intelligence to your orchestrations and powers your recommendations. It automatically maximizes campaign engagement by predicting and sending the right message at the right time. |
| Message Personalization | Personalization is a method of tailoring marketing messages to individual users to improve engagement and conversion rates. By addressing users by name, referencing their past interactions, or showing products they viewed, you create more relevant connections with users. As a marketer, you can personalize one or multiple attributes in the same message or image. For more information, refer to [Overview](/docs/user-guide/campaigns-and-channels/getting-started/message-personalization/overview). |
| MoEngage Go | MoEngage Go is the MoEngage mobile app that lets you monitor campaign performance, manage running campaigns, and approve campaigns pending review from your phone. It is a companion to the MoEngage web dashboard, focused on tasks you need to complete when away from your desk, and is available on iOS and Android. For more information, refer to [MoEngage Go: Overview](/docs/user-guide/moengage-go/moengage-go-overview). |
| Most Preferred Channel (MPC) | Most Preferred Channel (MPC) is a user-level parameter that denotes the channel a user responds to best from the available channels, such as email, push notifications, and SMS. Instead of using multiple channels to send the same message, you can engage each customer on the channel of their choice to get maximum engagement. For more information, refer to [Most Preferred Channel](/docs/user-guide/ai-and-intelligence/most-preferred-channel/most-preferred-channel). |
| MTU | Monthly Tracked Users (MTUs) are the total number of unique users for whom at least one event was tracked in a specified month. This is a key metric for billing. For more details on how MoEngage calculates MTUs, refer to [Usage Details](/docs/user-guide/settings/account/billing/usage-details). |
| My Studio | My Studio lets you store your saved analyses in one place so you can retrieve and resume your work from where you left off. It helps you avoid losing progress due to unexpected disruptions and makes it easier to explore popular analyses. My Studio is a personal, user-specific dashboard that other users cannot access, and you can save a maximum of 50 analyses. For more information, refer to [My Studio](/docs/user-guide/analyze/dashboards/my-studio). |
| Next Best Action | The Next Best Action (NBA) option in Flows uses insights on user behavior gathered by Merlin AI to engage each user on their preferred channel at the best time. It combines Most Preferred Channel and Best Time to Send to create a hyper-personalized flow for each user based on their past engagement trends rather than the collective trends of a group. For more information, refer to [Next Best Action in Flows](/docs/user-guide/flows-cross-channel-messaging/create/intelligence-in-flows/next-best-action-in-flows). |
| Object Data Type | An Object is a data type that holds data as one or more key-value pairs. You can use it to store complex attributes, such as the details of an item a user added to their cart, so those attributes can be encapsulated in a single object and used for segmentation. For example, a book object can hold keys like product_name, price, and sku. This feature must be enabled for your account by your MoEngage CSM or the Support team. For more information, refer to [Support for Object Data Type](/docs/user-guide/data/key-concepts/support-for-object-data-type). |
| Offer Decisioning | The MoEngage Offerings & Decision Policy solution helps marketing and business teams deliver personalized promotions to their customers across digital platforms such as mobile apps and websites. You create promotions called Offerings that are tailored to specific user groups and optimized through Decision Policies to ensure relevance. It streamlines designing, managing, and displaying targeted promotions such as limited-time sales, loyalty rewards, or new service announcements. For more information, refer to [Overview](/docs/user-guide/decisioning/offer-decisioning/overview). |
| Offerings | An offering is a promotional unit that comprises elements like user eligibility, scheduling, priority, usage limits, and content design. User eligibility rules determine which users qualify, the schedule sets the active period, and priority is a manually assigned score where a higher value means higher importance. You can use pre-designed templates to build promotions that align with brand guidelines. For more information, refer to [Create Offerings](/docs/user-guide/decisioning/offer-decisioning/create-offerings). |
| On-site Message | On-site messages display pop-ups, surveys, or lead generation forms directly on your desktop or mobile website when users are visiting. This helps you capture leads, gather feedback, and deliver real-time personalized experiences. For more information, refer to [MoEngage Channels](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels). |
| Open Analytics | Open Analytics enables growth teams to access the latest data on the MoEngage platform in real time, directly from the data storage. You can query the data warehouse directly to retrieve the data you need. You can read and query data using SQL through a console or programmatically via API, and visualize the data using built-in visualization methods on the Open Analytics console. For more information, refer to [Open Analytics](/docs/user-guide/analyze/custom-analysis/open-analytics). |
| Personalize (Client-side & Server-side) | MoEngage Personalize offers two approaches to tailoring website content. Client-side personalization modifies website content in real time in the user's browser after the page loads, using JavaScript SDKs to identify the user and render experiences created for them. Server-side personalization applies changes on the server before the page is served. Compare both to choose the method that fits your website customization needs. For more information, refer to [Client-side versus Server-side personalization](/docs/user-guide/personalize/overview/client-side-versus-server-side-personalization). |
| PII (Personally Identifiable Information) | Personally Identifiable Information (PII) is any data that relates to an identified or identifiable natural person, who can be identified directly or indirectly by an identifier such as a name, identification number, location data, or an online identifier. Examples include name, residential address, date of birth, and IP address. Fields such as zip code, date of birth, gender, and passwords may not identify a person on their own, but they become PII when combined with other fields that collectively identify a living person. For more information, refer to [Personal Data or Personally Identifiable Information (PII)](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/personal-data-or-personally-identifiable-information-pii). |
| Portfolio (Multi-Project Portfolio) | Portfolio lets you manage multiple apps and websites as individual Projects within a single, unified MoEngage workspace. It is designed for enterprises that manage multiple digital properties, such as different brands or operations in multiple countries, and want to consolidate their user data and marketing efforts. It creates a unified customer view and supports cross-brand segmentation and cross-project trigger campaigns. Portfolio is a paid add-on that must be enabled by your MoEngage CSM or the Support team. For more information, refer to [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio). |
| Predict / Predictions | MoEngage Predictions forecast the actions users are likely to perform in the next few days, such as making a purchase, uninstalling the app, or becoming dormant. You can use this information to take proactive marketing steps and create campaigns for the predicted users. MoEngage provides out-of-the-box predictions for conversion, uninstall, and dormancy, and you can also predict custom actions. For more information, refer to [Overview](/docs/user-guide/ai-and-intelligence/predict/what-are-predictions/overview). |
| Proactive Insights | Proactive Insights is an AI-powered assistant that provides marketers with insights to improve their marketing efforts. It gathers data from diverse sources, transforms it into actionable insights using AI and algorithms, and presents them in a unified interface without needing manual queries. You can act on the suggested insights with a few clicks, such as sending a campaign immediately or saving a segment for further analysis. For more information, refer to [Proactive Insights](/docs/user-guide/ai-and-intelligence/proactive-insights). |
| Push Amplification™ / Push Amplification™ Plus | Push Amplification™ is a fallback delivery service used when FCM notification delivery fails. When a delivery fails, Push Amplification™ detects the failure and delivers the notification directly to app users' devices, reaching users who would otherwise be missed by FCM. For more information, refer to [Push Amplification™ and Delivery Impact](/docs/user-guide/campaigns-and-channels/mobile-push/analyze/push-amplification-and-delivery-impact). |
| Push Notification (Mobile / Web) | Push campaigns target users through notifications for your app or website. MoEngage supports one-time, periodic, and event-triggered push campaigns. For more information, refer to [Overview - Mobile Push](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/overview-mobile-push). |
| Ranking Strategy | A ranking strategy is the logic a Decision Policy uses to rank eligible offerings for each customer. MoEngage offers three ranking strategies in Decision Policies: Manual priority, where the author assigns a rank to each offering; Merlin AI, which learns from clicks and conversions to find the best-performing offering for each user; and Custom formula, where you define a weighted combination of offering attributes, performance, and priority. For more information, refer to [Custom Formula Ranking Strategy](/docs/user-guide/decisioning/offer-decisioning/custom-formula-ranking-strategy). |
| Reachability | Reachability represents the number of users who can be contacted through a chosen communication channel or platform on MoEngage. It is derived for Push, Email, SMS, and WhatsApp channels, and the method of calculation varies across the different pages on the MoEngage dashboard. For more information, refer to [User Reachability](/docs/user-guide/segment/reachability/user-reachability). |
| Real-Time Segment Evaluation | Real-time segment evaluation (RTSE) lets you engage your audience based on their demographics, behavior, and interests the moment they perform a key action. When a user performs a trigger event, MoEngage immediately checks whether they qualify for your campaign's audience criteria and triggers the campaign instantly if they do. This contrasts with periodic segments, which refresh on a set schedule. For more information, refer to [Real-Time Segment Evaluation](/docs/user-guide/segment/advanced-concepts/real-time-segment-evaluation). |
| Recommendations | You can include your product catalogs in your campaigns using recommendations. For more information, refer to [Recommendations](/docs/user-guide/content/recommendations). |
| Retention | Retention provides insights into user retention, which helps you assess users' loyalty and measure your product's recurring user base. Retention charts represent various cohorts, where a cohort is a group of users who complete the same events within a specific time frame. Tabular reports are available for download to assess retention trends across cohorts over time. For more information, refer to [Retention - Overview](/docs/user-guide/analyze/analytics/retention/retention-overview). |
| RFM | The RFM (Recency, Frequency, and Monetary) model automatically segments users into behavior-based categories such as Loyal, Promising, and At Risk, based on how recently, how often, and how much they transact. These auto-segments support user analysis, churn analysis, and campaign targeting. For more information, refer to [RFM Segments](/docs/user-guide/segment/create-segments/rfm-segments). |
| Roles | MoEngage allows multiple team members to be added to the same account. There are 5 access roles (Admin, Manager, Marketer, Developer and Analyst) with different permissions. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles). |
| SDK | Software Development Kits (SDKs) are integrated into iOS and Android applications and provide tools for marketing, customer support, and analytics. MoEngage offers SDK integration for both iOS and Android. For more information, refer to the [Developer Guide](https://www.moengage.com/docs/developer-guide/introduction). |
| Segment Nesting | Nesting lets you group segment blocks together using brackets to build complex segments that mix AND and OR conditions. Without nesting, only a single operator can combine all blocks, so you cannot express criteria such as (users who are male AND added a wallet to cart) OR (users who are female AND added a handbag to cart). By grouping blocks into nested blocks, you can create combinations like (A AND B) OR (C AND D). For more information, refer to [Segment Nesting](/docs/user-guide/segment/advanced-concepts/segment-nesting). |
| Segmentation | The Segmentation feature allows you to segment your users based on their attributes and actions in your app or website. After segmentation, you can create a campaign targeted to these segments. For more information, refer to [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments). |
| Session and Source | A session represents a user's series of interactions on your website or app within a specific timeframe, tracked by recording the events and activities users perform on their devices. Session Analysis helps you understand how users interact with your web and mobile apps so you can improve your product and design. Sessions are specific to individual devices, and server-side activity is not included within a session. For more information, refer to [Session and Source - Overview](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview). |
| Split URL Testing | Split URL testing is a structured approach to website optimization in MoEngage Personalize. You create multiple versions of a webpage, each with a different URL, then systematically test the variations to determine which one delivers the best results. Use it to test regional experiences, recommend specific product pages, or offer early access to VIP customers. For more information, refer to [Create a Split URL testing Experience](/docs/user-guide/personalize/split-url-testing/create-a-split-url-testing-experience). |
| Team | A team is a group of MoEngage users using MoEngage Dashboard who collaborate on the same campaigns. These users can be from the same geography or from the same vertical within the enterprise. For more information, refer to [Teams in MoEngage](/docs/user-guide/settings/account/team-management/teams-in-moengage). |
| Templates | The Templates feature provides a central hub where you can organize and manage reusable campaign templates for multiple channels in one place. You can create templates for different channels, edit them using the drag-and-drop editor or custom HTML editor, and manage them in folders shared across teams. For more information, refer to [Templates](/docs/user-guide/content/template/templates). |
| Triggers | Triggers are messages sent to the device when the user performs a trigger event. Messages are served in near real time. For more information, refer to [Triggers](/docs/user-guide/campaigns-and-channels/getting-started/triggers). |
| Unified Identity (Identity Resolution) | Identity Resolution merges profiles that belong to the same person across channels such as website, app, offline store, and social login into one profile. It uses identifier attributes such as ID, email, or mobile number from data ingested via Data APIs, MoEngage SDKs, or CSV files. This gives you one accurate view of each user for segmentation, personalization, and reporting. The feature is opt-in and irreversible once activated, and only Admins can access the setting. For more information, refer to [Unified Identity (Identity Resolution)](/docs/user-guide/data/user-data/unified-identity-identity-resolution). |
| Uninstall Tracking / User Install Status | Install status indicates whether an application is installed for a particular user, providing base-level install information at a user level. MoEngage tracks it through SDK install, uninstall, and reinstall tracking, through signals from silent push messages via FCM or APNs, and through Firebase integration for real-time uninstall tracking. If MoEngage detects an install, the status is marked true; otherwise false. For a user with multiple devices, the status is true if at least one device has the app installed. For more information, refer to [User Install Status](/docs/user-guide/data/user-data/user-install-status). |
| User Properties | User properties are the pieces of user data stored in MoEngage that make up a user's profile, such as first name, email address, subscription status, or pages visited. A user profile is created and updated when a user opens your app or website with the MoEngage SDK, or when you upload user information through the UI or via API. Together these attributes give you a 360-degree view of each user for segmentation, personalization, and reporting. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile). |
| User Paths | User Paths visualize user interaction and navigation within websites and apps by analyzing event trails. This analysis focuses on events performed before or after a specific target event, revealing user behavior patterns so you can identify popular navigation routes and pinpoint bottlenecks or friction points. These paths consist of event sequences originating from or converging on a desired event within a defined time frame. For more information, refer to [User Paths - Overview](/docs/user-guide/analyze/analytics/user-paths/user-paths-overview). |
| User Profile | A user profile is a collection of all information associated with a user in MoEngage systems. A user profile may contain usage information (behavior), demographic information (age, physical attributes, language, family), psychological info (attitudes, beliefs, opinions), professional info (education, work experience), and so on. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile). |
| Web Personalization | Web Personalization helps you tailor your website content to individual users by delivering personalized data when they visit your site. This lets you show each user the most relevant experience, such as personalizing home page banners based on user behavior or displaying localized content based on a user's location. For more information, refer to [Introduction](/docs/user-guide/campaigns-and-channels/web-personalization/getting-started-with-web-personalization/introduction). |
All MoEngage AI products, which were previously referred to as *Sherpa AI*, are now known as *Merlin AI*.
# Welcome to MoEngage!
Source: https://moengage.com/docs/user-guide/getting-started/welcome-to-moengage
New to MoEngage? Learn how the platform works, the key concepts you'll see in the dashboard, and what to set up first.
MoEngage is a customer engagement platform. You send MoEngage data about your users and what they do in your app or website, and MoEngage builds one profile for each user. Everything else in the platform works from those profiles: you segment users, reach them across channels, personalize their experience, and analyze the results. Merlin AI, the AI layer of MoEngage, works across all of it.
This page explains how the platform fits together, the terms you'll see in the dashboard, and what to set up first.
01 CollectBring in your dataSend users, events, and attributes from every source.
Web and mobile SDKs
REST APIs
File imports
Data warehouses
Partner integrations
02 UnifyKnow each userMerge the data into one profile per user.
User profiles
Events
User properties
Computed traits
Identity resolution
03 EngageReach the right usersTarget segments with campaigns and journeys.
Segments
Campaigns
Flows
Personalize
Inform
Messaging channels
04 MeasureLearn what workedAnalyze behavior and campaign performance.
Behavior
Funnels
Retention
Dashboards
Campaign and flow stats
Merlin AI across every stagePredict user behavior, pick the best time and channel, generate content, and automate decisions.
Predictions
Best time to send
Most preferred channel
Copywriter and Designer
Campaign and offer decisioning
MCP server
## How MoEngage Works
Some features on this page depend on your MoEngage plan or a paid add-on. For example, Inform depends on your plan, event exports are part of the Streams add-on, and segment sync is part of the Connected Segments add-on.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
### 1. Collect Data
Your developers integrate the MoEngage SDKs into your app or website and send server-side data through the REST APIs. Your data team can also import files or connect a data warehouse. For more information, refer to [Overview - Data](/docs/user-guide/data/key-concepts/overview-data) and [Imports](/docs/user-guide/data/imports/overview-imports).
### 2. Unify User Profiles
MoEngage merges the events and attributes it receives into a single profile per user. A visitor who browses anonymously and later signs in keeps one profile. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile) and [Anonymous to Registered User Merge](/docs/user-guide/data/user-data/anonymous-to-registered-user-merge).
### 3. Engage Users
Build segments from profile data, then reach those users with one-off campaigns on a single channel or with flows that move users across channels based on what they do. Send transactional alerts with Inform, and personalize your website for each visitor. For more information, refer to [Basics of Segmentation](/docs/user-guide/segment/getting-started/basics-of-segmentation), [Channels in MoEngage](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels), [Overview - Flows](/docs/user-guide/flows-cross-channel-messaging/getting-started/overview-flows/overview-flows), [Overview - Inform](/docs/user-guide/inform/overview-inform), and [Overview - Personalize](/docs/user-guide/personalize/overview/overview-personalize).
### 4. Measure Results
Track how users behave in your app or website and how your campaigns and flows perform, then refine your segments and messages. For more information, refer to [MoEngage Analytics](/docs/user-guide/analyze/moengage-analytics/overview).
### Merlin AI
Merlin AI predicts user behavior, picks the best time and channel for each message, helps you build segments and flows, and generates content. Campaign and offer decisioning choose which campaign or offer each user receives. For more information, refer to [Merlin AI Studio](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-studio).
### Data Out
You can export events to your data warehouse or cloud storage, sync segments to ad networks and other tools, and connect AI assistants to your workspace through the MoEngage MCP server. For more information, refer to [Overview - Event Exports](/docs/user-guide/data/exports/events/overview-events-exports), [Outbound Segment Sync](/docs/user-guide/data/exports/segments/outbound-segment-sync), and [MoEngage MCP Server and Connector](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server).
## Key Concepts
These terms appear throughout the dashboard and the docs. For the full list, refer to [Terms to Know](/docs/user-guide/getting-started/overview/terms-to-know).
| Term | What it means |
| - | - |
| Workspace | The account your team works in on the MoEngage dashboard. Each workspace has a Test environment and a Live environment. |
| Test and Live environments | The Test environment is for integration and QA, and the Live environment is for production data and campaigns. Each environment has its own Workspace ID and its own settings, available under **Settings** > **Account** > **General settings**. For more information, refer to [Live and Test Environments](/docs/user-guide/getting-started/initial-setup/dashboard-overview#live-and-test-environments). |
| Data center | The region where MoEngage hosts your workspace. It determines your dashboard URL and your SDK and API endpoints. For more information, refer to [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
| User property | A property of a user, such as name, email, or city. |
| Event | An action a user takes, such as viewing a product or making a purchase. Events can carry their own attributes. |
| Segment | A group of users you target or analyze, defined by conditions on their data or uploaded from a file. |
| Campaign | A message you send on one channel, such as a push notification or an email. |
| Flow | A multi-step journey that moves users across channels based on what they do. |
## Set Up Your Workspace
Steps 3 and 5 need a developer, and so does adding push credentials in step 4.
**1. Log in and secure access**
Log in to the dashboard and set up 2-step verification. If your organization uses an identity provider, configure single sign-on (SSO).
For more information, refer to [Log In to MoEngage](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage) and [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
**2. Invite your team**
Add team members and assign each one an access role, so they see only the parts of the dashboard they need.
For more information, refer to [Manage Members](/docs/user-guide/settings/account/team-management/manage-members) and [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
**3. Integrate your data**
Your developers add the MoEngage SDK to your app or website and track the events and attributes you plan to use. Use the integration checklist to agree on what to track before they start.
The SDK decides which environment receives data. On Android and iOS, debug builds send data to the Test environment and signed release builds send data to the Live environment. On the Web SDK, your developers set the environment to `TEST` or `LIVE` in the SDK configuration.
For more information, refer to the [Integration Checklist](/docs/user-guide/getting-started/integration/integration-checklist), the [SDK Integration Guide](/docs/developer-guide/introduction), and [Imports](/docs/user-guide/data/imports/overview-imports).
**4. Set up your channels**
Configure each channel you plan to use. For example, connect your email sender, connect an SMS or WhatsApp provider, or add push credentials. Push credentials come from your Firebase project for Android and your Apple Developer account for iOS. Add them in both the Test and Live environments.
For more information, refer to [Channels in MoEngage](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels).
**5. Validate the integration**
Use a debug build of your app, or a website set to `TEST`, so the data goes to the Test environment. Confirm that events and user properties reach MoEngage, and that test push notifications and in-app messages reach your device. When validation is done, release a signed build of your app, or set your website to `LIVE`, so production data goes to the Live environment.
For more information, refer to [User Events Integration Validation](/docs/user-guide/getting-started/integration-validation/user-events-integration-validation), [User Property/Profile Integration Validation](/docs/user-guide/getting-started/integration-validation/user-attributeprofile-integration-validation), [Android Push Notifications Integration Validation](/docs/user-guide/getting-started/integration-validation/android-push-notifications-integration-validation), [iOS Push Notifications Integration Validation](/docs/user-guide/getting-started/integration-validation/ios-push-notifications-integration-validation), [Web Push Notifications Integration Validation](/docs/user-guide/getting-started/integration-validation/web-push-notifications-integration-validation), and [In-App Notifications Integration Validation](/docs/user-guide/getting-started/integration-validation/in-app-notifications-integration-validation).
**6. Launch your first campaign**
Create a segment of the users you want to reach, send them a campaign, and review the results.
For more information, refer to [Basics of Segmentation](/docs/user-guide/segment/getting-started/basics-of-segmentation), [Create Push Campaigns](/docs/user-guide/campaigns-and-channels/mobile-push/create/create-push-campaigns), and [Campaign Stats](/docs/user-guide/analyze/dashboards/campaign-stats).
## Where to Start for Your Role
| If you are | Start with |
| - | - |
| A marketer or growth team member | [Channels in MoEngage](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels), then [Basics of Segmentation](/docs/user-guide/segment/getting-started/basics-of-segmentation) and [Overview - Flows](/docs/user-guide/flows-cross-channel-messaging/getting-started/overview-flows/overview-flows). |
| A developer | The [SDK Integration Guide](/docs/developer-guide/introduction) for your platform. |
| On a data team | The [API Documentation](/docs/api/introduction), [Imports](/docs/user-guide/data/imports/overview-imports), and [Partner Integrations](/docs/partner-guide/introduction). |
| An administrator | [Workspace Settings](/docs/user-guide/settings/account/general-settings/workspace-settings), [Manage Members](/docs/user-guide/settings/account/team-management/manage-members), and [Security](/docs/user-guide/settings/account/security/overview). |
## Get Help
* Ask [AIRA](/docs/user-guide/contact-support/aira-support-bot/aira-overview), the MoEngage support bot, or [raise a support ticket from the dashboard](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
* Take self-paced courses in [MoEngage Academy](https://academy.moengage.com/student/catalog).
* Follow new features in the [release notes](/docs/release-notes/product).
* Use these docs from your LLM, IDE, or AI agent. For more information, refer to [Documentation Access to Agents](/docs/documentation-access-to-agents).
# User Guide
Source: https://moengage.com/docs/user-guide/introduction
Explore the MoEngage User Guide to learn about audience engagement, campaign management, analytics, and AI-powered optimization features.
MoEngage is an insights-led customer engagement platform that helps you understand your audience, engage them across channels, and build lasting relationships; all from a single dashboard.
This user guide covers every feature and capability of the MoEngage platform, from initial setup to advanced AI-powered optimization.
## Where to Start
> [card] [Welcome to MoEngage](/docs/user-guide/getting-started/welcome-to-moengage)
>
> Learn how the platform works, the key concepts, and what to set up first.
> [card] [Dashboard Overview](/docs/user-guide/getting-started/initial-setup/dashboard-overview)
>
> Familiarize yourself with the MoEngage dashboard, navigation, and key concepts.
> [card] [Integration](/docs/user-guide/getting-started/integration/integration-checklist)
>
> Integrate MoEngage SDKs across Web, Android, iOS, and other platforms.
## Platform Capabilities
### Understand Your Users
> [card] [Data](/docs/user-guide/data/key-concepts/overview-data)
>
> Bring in user profiles, events, and attributes from any source — SDKs, file imports, or data warehouses.
> [card] [Segment](/docs/user-guide/segment/getting-started/basics-of-segmentation)
>
> Build precise audience segments based on behavior, attributes, affinity, and reachability.
> [card] [Analyze](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview)
>
> Explore funnels, retention, user paths, cohorts, and custom analytics dashboards.
### Engage Across Channels
> [card] [Campaigns & Channels](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels)
>
> Create and manage campaigns across Email, Push, SMS/MMS/RCS, WhatsApp, In-App, Web Push, Cards, and more.
> [card] [Flows](/docs/user-guide/flows-cross-channel-messaging/getting-started/overview-flows/overview-flows)
>
> Design cross-channel user journeys with conditional logic, branching, A/B splits, and real-time triggers.
> [card] [Inform](/docs/user-guide/inform/overview-inform)
>
> Send transactional messages — order confirmations, OTPs, alerts — reliably at scale.
### Optimize and Personalize
> [card] [AI & Intelligence](/docs/user-guide/ai-and-intelligence/overview)
>
> Generate content with Merlin AI, forecast user behavior, automate campaign and offer decisions, and optimize send time and channel.
> [card] [Personalize](/docs/user-guide/personalize/overview/overview-personalize)
>
> Deliver tailored web experiences with client-side and server-side personalization and split URL testing.
> [card] [Content](/docs/user-guide/content/content-blocks/content-blocks)
>
> Manage content blocks, templates, coupons, landing pages, and product recommendations.
### Advanced Features
> [card] [Settings](/docs/user-guide/settings/account/general-settings/workspace-settings)
>
> Configure your workspace, manage team roles, set delivery controls, and access API keys.
> [card] [Use Cases](/docs/use-cases/analytics/how-to-analyze-ott-content-performance)
>
> Explore real-world examples and best practices for common engagement scenarios.
## What's New
> [card] [Release Notes](/docs/release-notes/product)
>
> Check out the latest features, improvements, and fixes in the most recent release.
## Additional Resources
> [card] [Release Notes](/docs/release-notes/product)
>
> Stay up to date with the latest features, improvements, and fixes.
> [card] [Contact Support](/docs/user-guide/contact-support/aira-support-bot/aira-overview)
>
> Reach the MoEngage support team for help with your account or technical issues.
> [card] [Terms to Know](/docs/user-guide/getting-started/overview/terms-to-know)
>
> Learn the key terminology used throughout MoEngage and this documentation.
> [card] [MoEngage Academy](https://academy.moengage.com/student/catalog)
>
> Access the MoEngage Academy, a collection of tutorials for using MoEngage.
# API Key Dashboard
Source: https://moengage.com/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard
View, create, edit, regenerate and archive API keys used for authentication. This article covers the supported authentication methods: Basic Auth, OAuth 2.0, and AWS STS Auth.
> [!NOTE]
>
> This is an Early Access feature. To enable it for your account, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
An API key is a unique identifier that authenticates and authorizes requests to MoEngage API resources. Use the API Key Dashboard to create keys, scope each key to the APIs it needs, and regenerate or archive keys as your integrations change.
The multi-API key feature is currently supported for the following API groups:
| API Group | Supported Authentication Types |
| - | - |
| [Data APIs](/docs/api/data/data-overview) | Basic Auth, OAuth 2.0, AWS STS Auth |
| [Segmentation APIs](/docs/api/custom-segments/custom-segments-overview) | Basic Auth |
| [Push APIs](/docs/api/push/push-overview) | Basic Auth (Legacy) |
| [Campaigns](/docs/api/campaigns/campaigns-overview) | Basic Auth, OAuth 2.0 |
| [Inform](/docs/api/inform/inform-overview) | Basic Auth |
| [Offerings](/docs/api/offerings/offerings-overview) | Basic Auth, OAuth 2.0 |
| Decision Policy | Basic Auth, OAuth 2.0 |
| [Dashboard & Analyze](/docs/api/analytics/analytics-overview) | Basic Auth, OAuth 2.0 |
| Channel Configuration | Basic Auth, OAuth 2.0, AWS STS Auth |
| [Personalize](/docs/api/personalize-experience/personalize-overview) | Basic Auth, OAuth 2.0, AWS STS Auth |
> [!NOTE]
>
> * Segmentation APIs and Inform are available only with Basic Auth.
> * AWS STS Auth covers a subset of the groups above. See [Scopes Available to AWS STS Auth](#scopes-available-to-aws-sts-auth).
> * Creation of new API keys for Push APIs is not currently supported. Push APIs work only with **Basic Auth (Legacy)** keys migrated to this dashboard. You can [regenerate](#manage-keys) the migrated legacy key.
To send data to MoEngage, you can use the Workspace ID and key for that particular API. Whenever a key is regenerated, the old key expires immediately and it takes some time for the new key to become functional, which may result in service interruptions. MoEngage provides multiple API keys to help you avoid this situation:
* **Generate a new key while the existing key is still available**: With multi-key support, the existing key remains active until the new key becomes functional. This allows you to rotate keys for security purposes without causing downtime. For example, if your team needs time to integrate a new key, the old key continues to work during that period. After the new key is integrated, you can archive the old one.
* **Use different keys for different teams**: You can create separate keys for different internal teams or external vendors, each scoped to the APIs they need. This provides granular access control and improves security across your organization.
To restrict which IP addresses can use your keys, see [API Firewall](/docs/user-guide/settings/account/security/api-firewall).
## Authentication Types
MoEngage supports the following authentication types for API keys:
* **Basic Auth**: The standard authentication method, which uses an API key and secret. Choose this method for server-to-server integrations that do not need token expiration.
* **OAuth 2.0**: A token-based method that issues short-lived access tokens. You set the token expiry time, and MoEngage validates each access token automatically. For the full flow, including generating, using, and refreshing tokens, refer to [OAuth 2.0 Overview](/docs/api/oauth/oauth-overview).
* **AWS STS Auth**: A token-based method for workloads that run on AWS. You allowlist the AWS Security Token Service (STS) assumed-role ARNs that can use the key, and each request proves its AWS identity with a signature from the role's temporary credentials. MoEngage also issues a `MOE-APPSECRET` value for the key, which every request sends alongside that signature. Choose this method when your services already assume an IAM role and you want MoEngage to authorize those roles directly. See [Add Role ARNs](#add-role-arns) and [AWS STS Auth](/docs/api/aws-sts/aws-sts-overview).
You select the authentication type from the **Authentication type** list in the **Create new key** dialog. You cannot change the authentication type after you create the key. To move an integration to a different authentication type, create a new key and archive the old one.
## Create a Key
> [!NOTE]
>
> * After the multi-API key feature is enabled, the existing API keys in the API dashboard are migrated to your new API key dashboard as legacy keys.
> * You can view the legacy key (autogenerated previously when the workspace was created and migrated to this new dashboard) details and continue to use them. You can regenerate legacy keys. However, editing and archiving legacy keys is not supported.
> * MoEngage recommends creating and using new keys, as legacy keys will be deprecated in the future.
**1. Open the API Keys Page**
On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Account** > **API keys**.
**2. Start a New Key**
Click **+ Create new key**.

**3. Open the Key Details Form**
In the **Create new key** dialog, enter the key details.
**4. Name the Key**
Enter a name in the **Key name** box. The key name must not exceed 100 characters and must be unique across your workspace. Archived keys keep their names, so you cannot reuse the name of a key you archived earlier.
**5. Choose an Authentication Type**
From the **Authentication type** list, select the method you want to use, then set the options for that method:

> [tab] Basic Auth
>
> Under **Select APIs for access**, select the API groups you want to access using this key:
>
> * Data APIs
> * Segmentation APIs
> * Campaigns
> * Inform
> * Offerings
> * Decision Policy
> * Dashboard & Analyze
>
> 
> [tab] OAuth 2.0
>
> 1. In the **Expiry time (in minutes)** box, enter the access token lifetime. The value must be between 5 and 60 minutes, and the default is 15 minutes.
>
> > [!NOTE]
> >
> > The **Expiry time (in minutes)** box does not appear for Basic Auth keys. AWS STS Auth keys have a box with the same name, but it sets a different limit. See the **AWS STS Auth** tab.
>
> 2. Under **Select APIs for access**, select the API groups you want to access using this key:
> * Data APIs
> * Campaigns
> * Offerings
> * Decision Policy
> * Dashboard & Analyze
>
> 
>
> **Segmentation APIs** and **Inform** are not listed for OAuth 2.0 keys. To access these groups, create a Basic Auth key.
> [tab] AWS STS Auth
>
> 1. In the **Expiry time (in minutes)** box, enter how long MoEngage trusts a signature it has already verified. The value must be between 5 and 15 minutes, and the default is 15 minutes. This setting does not change how old a signature can be when MoEngage first verifies it, which the AWS freshness window governs.
>
> 2. In the **ARN** box, enter the AWS STS assumed-role ARN that can use this key. Click **+ Add value** to add another ARN, up to 10 entries. For the accepted format and the validations the dashboard applies to each entry, see [Add Role ARNs](#add-role-arns).
>
> 3. Under **Select APIs for access**, select the API groups you want to access using this key:
> * Data APIs
> * Channel Configuration
> * Personalize
>
> 
>
> **Campaigns**, **Segmentation APIs**, **Inform**, **Offerings**, **Decision Policy**, and **Dashboard & Analyze** are not available to AWS STS Auth keys. To access those groups, create a Basic Auth or OAuth 2.0 key.
>
> Not every scope inside a listed group is available to an AWS STS Auth key. See [Scopes Available to AWS STS Auth](#scopes-available-to-aws-sts-auth) for the scopes such a key can use.
>
> When you save the key, MoEngage generates a `MOE-APPSECRET` value for it. Your application sends that value as a header on every request, in addition to the AWS signature. See [View Key Details](#view-key-details) to retrieve it.
**6. Scope the API Access**
Click next to a group to expand it and select individual APIs. Use **Select all** or **De-select all** to manage selections across all groups.
**7. Save the New Key**
Click **Create key**. The new key appears under **Active API keys**.
To use the key in requests, see [Authentication](/docs/api/introduction#authentication). If you created an OAuth 2.0 key, see [OAuth 2.0 Overview](/docs/api/oauth/oauth-overview) for generating an access token, calling the APIs, and refreshing the token. For per-endpoint request limits and payload caps, see [Rate Limits](/docs/api/rate-limits).
## AWS STS Auth
This section applies only to keys that use the **AWS STS Auth** authentication type. MoEngage authorizes such a key against a list of assumed-role ARNs, and only a caller whose assumed-role ARN appears on the key can use it.
> [!NOTE]
>
> This section covers the dashboard configuration for an AWS STS Auth key. For the signing sequence that your application performs, the regional AWS STS hosts, and the headers that each API request carries, refer to [AWS STS Auth](/docs/api/aws-sts/aws-sts-overview).
### Scopes Available to AWS STS Auth
An AWS STS Auth key reaches a subset of the scopes available to Basic Auth and OAuth 2.0 keys.
| API Group | Scopes an AWS STS Auth Key Can Select |
| - | - |
| [Data APIs](/docs/api/data/data-overview) | Every scope: Get User, Track User, Merge User, Bulk Import, GDPR Delete, Delete User, Create Events, File Imports, Track Device, and Email Double Opt-in. |
| Channel Configuration | **Setup & Manage** only. **View** and **Manage Message Template** require a Basic Auth or OAuth 2.0 key. |
| [Personalize](/docs/api/personalize-experience/personalize-overview) | **View** only. |
No other scope accepts an AWS STS Auth key. To call Campaigns, Segmentation APIs, Inform, Offerings, Decision Policy, or Dashboard & Analyze, create a Basic Auth or OAuth 2.0 key.
### Add Role ARNs
You create and manage these roles in your own AWS account. MoEngage does not generate the ARN, so copy it from your AWS account and paste it into the key. For more information, see the [AWS Security Token Service API Reference](https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html).
#### ARN Format
Enter each ARN in the following format:
```text theme={null}
arn:aws:sts:::assumed-role//
```
| Segment | Description |
| - | - |
| `aws:sts` | The service. An AWS STS Auth key accepts Security Token Service ARNs only. |
| `` | Your 12-digit AWS account ID. |
| `assumed-role` | The resource type. The dashboard rejects ARNs that use `role` or any other resource type. |
| `` | The name of the IAM role your workload assumes. |
| `` | The role session name, or `*` to match every session of that role. |
For example:
```text theme={null}
arn:aws:sts::123456789012:assumed-role/MoEngageIngestionRole/data-pipeline-prod
```
The session name is mandatory. An entry that stops at the role name, such as `arn:aws:sts::123456789012:assumed-role/MoEngageIngestionRole`, is rejected as **Invalid format**.
#### Match Several ARNs With a Wildcard
Each session of a role produces a different ARN, so a role that many workloads or team members share can exceed the limit of 10 entries. Place `*` at the end of the segment you want to broaden.
| Goal | Entry | Matches |
| - | - | - |
| Every session of one role | `arn:aws:sts::123456789012:assumed-role/MoEngageIngestionRole/*` | Every session of `MoEngageIngestionRole`. |
| Every role that shares a name prefix | `arn:aws:sts::123456789012:assumed-role/MoEngageIngestionRole-*` | `MoEngageIngestionRole-Dev`, `MoEngageIngestionRole-Prod`, and every other role with that prefix. |
Two rules apply to every wildcard entry:
* An entry accepts one `*`, and only as the final character. `arn:aws:sts::123456789012:assumed-role/My*Role` and any entry with two wildcards are invalid.
* The role name must contain at least one character before the wildcard, so `arn:aws:sts::123456789012:assumed-role/*` is invalid.
> [!WARNING]
>
> A wildcard grants the key's full API access to every ARN it matches, so use one only when every matched role or session needs the same access. When you add a wildcard entry, the dashboard displays the banner **Using \* matches multiple ARNs. Ensure that this broader scope is intentional for security.**
When a wildcard entry already covers a role, you cannot add a named session for the same role. The dashboard treats the named session as a duplicate. Remove one of the two entries to save the key.
#### ARN Validations
| Condition | Message |
| - | - |
| The ARN does not match the expected format. For example, the account ID has fewer than 12 digits, the resource type is `role` instead of `assumed-role`, or the session name is missing. | **Invalid format** |
| The entry contains more than one `*`, places `*` anywhere other than the final character, or uses `*` as the entire role name. | **Invalid format** |
| You enter the same ARN twice, or you add a named session for a role that a wildcard entry already covers. | **Duplicate ARN detected** |
| The list already contains 10 ARNs. | The dashboard disables **+ Add value** and states that you can add up to 10 values. |
## View Active Keys
On the **API Keys** page, the **Active API keys** table shows the following columns:
| Column | Description |
| - | - |
| Key name | The name assigned to the key. |
| Auth type | **Basic Auth**, **OAuth 2.0**, **AWS STS Auth**, or **Basic Auth (Legacy)** for migrated legacy keys. |
| Created on | The date and time the key was created, along with the email address of the user who created it. |
| Key | The masked key value with a view button and a copy button. |
| Actions () | Options to manage the key. See [Manage Keys](#manage-keys). |
You can search for keys using the search bar. The count of active keys is displayed above the table.
> [!NOTE]
>
> Legacy keys are listed with the auth type **Basic Auth (Legacy)**. You can view, continue to use, and [regenerate](#manage-keys) these keys, but you cannot edit or archive them.
## Manage Keys
On the **API Keys** page, click for a key to see the following options: 
| Option | Description |
| - | - |
| [View key details](#view-key-details) | View the full details of the key. From the details panel, you can also access **Edit key details** and **Regenerate key**. |
| Regenerate key | Generate a new key. You can regenerate a key as often as you need. On an AWS STS Auth key, this issues a new `MOE-APPSECRET` value and leaves the key's role ARNs and API access unchanged. This option is also available for legacy keys. |
| [Edit key details](#edit-key-details) | Edit the key's name or API access settings. |
| Archive key | Archive the key. Archived keys cannot be unarchived. A maximum of 10 archived keys is maintained in the archived key list. |
**Edit key details** and **Archive key** are not available for legacy keys.
> [!WARNING]
>
> The old key expires immediately after regenerating. Replace the old key in your integrations to avoid errors. Push APIs use a single legacy key, and you cannot create a second Push API key. Update the key in your integrations right after you regenerate it to limit the interruption.
### View Key Details
**1. Open the Key Actions Menu**
On the **API Keys** page, click for the key you want to view.
**2. Open the Details Panel**
Click **View key details**. The fields in the details panel depend on the authentication type of the key:
> [tab] Basic Auth
>
> | Field | Description |
> | - | - |
> | Key name | The name assigned to the key. |
> | API key | The masked key value with a view button and a copy button. |
> | Authentication type | **Basic Auth**, or **Basic Auth (Legacy)** for a migrated legacy key. |
> | Last updated on | The date and time the key was last modified. |
> | Last updated by | The email address of the user who last modified the key. |
> | Created on | The date and time the key was created. |
> | Created by | The email address of the user who created the key. |
> | API access | The APIs selected for this key, with checkmarks indicating the enabled options. Click next to a group to see the individual APIs it includes. |
> [tab] OAuth 2.0
>
> | Field | Description |
> | - | - |
> | Key name | The name assigned to the key. |
> | API key | The masked key value with a view button and a copy button. |
> | Authentication type | **OAuth 2.0**. |
> | Access token expiration | The token lifetime in minutes. |
> | Last updated on | The date and time the key was last modified. |
> | Last updated by | The email address of the user who last modified the key. |
> | Created on | The date and time the key was created. |
> | Created by | The email address of the user who created the key. |
> | API access | The APIs selected for this key, with checkmarks indicating the enabled options. Click next to a group to see the individual APIs it includes. |
> [tab] AWS STS Auth
>
> | Field | Description |
> | - | - |
> | Key name | The name assigned to the key. |
> | API key | The masked key value with a view button and a copy button. |
> | Authentication type | **AWS STS Auth**. |
> | MOE-APPSECRET | The secret that MoEngage generated for this key, with a view button and a copy button. The value stays available after creation, so you can retrieve it here at any time. |
> | Expiry time | How long, in minutes, MoEngage trusts a signature it has already verified. |
> | ARNs | The assumed-role ARNs that can use this key. Click **Show more** to expand the full list, and hover over an entry to see the complete ARN. |
> | Last updated on | The date and time the key was last modified. |
> | Last updated by | The email address of the user who last modified the key. |
> | Created on | The date and time the key was created. |
> | Created by | The email address of the user who created the key. |
> | API access | The APIs selected for this key, with checkmarks indicating the enabled options. Click next to a group to see the individual APIs it includes. |
From the details panel, you can click **Edit key details** or **Regenerate key** to perform those actions.

### Edit Key Details
**1. Open the Key Actions Menu**
On the **API Keys** page, click for the key you want to edit.
**2. Open the Edit Dialog**
Click **Edit key details**.
**3. Update the Fields**
In the **Edit key details** dialog, edit the available fields:
> [tab] Basic Auth
>
> | Field | Editable |
> | - | - |
> | Key name | Yes |
> | Authentication type | No |
> | Select APIs for access | Yes |
> [tab] OAuth 2.0
>
> | Field | Editable |
> | - | - |
> | Key name | Yes |
> | Authentication type | No |
> | Access token expiration | Yes |
> | Select APIs for access | Yes |
> [tab] AWS STS Auth
>
> | Field | Editable |
> | - | - |
> | Key name | Yes |
> | Authentication type | No |
> | Expiry time (in minutes) | Yes |
> | ARN | Yes |
> | Select APIs for access | Yes |
>
> The same validations apply as when you create the key. See [Add Role ARNs](#add-role-arns).
**4. Save Your Changes**
Click **Save**. The **Save** button remains disabled until you make a change.
If you change the API access or the ARN list, a confirmation dialog opens with the title **Are you sure you want to update "\" Key?**. The dialog groups your changes into categories, such as **ARN added** and **ARN removed**, and shows only the categories you changed. Click **Show more** to expand a long list, and hover over an entry to see the complete ARN.

Review the summary, then click **Save** to apply the changes.
> [!WARNING]
>
> Removing an API group or an ARN revokes that access immediately. Notify everyone who uses this key before you save, because their integrations fail as soon as you confirm the change.
### View Archived Keys
1. On the **API Keys** page, click **View archived keys**.
2. The archived keys list opens with the following columns: Key name, Auth type, Archived on, and Key.

## Audit Logs

[Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs) records every API key action, so you can identify who created, updated, regenerated, or archived a key and when. These entries appear under the **API Keys** entity, and each description names the key and its authentication type. For the full list of recorded events and their description formats, see [Identity and Access Management](/docs/user-guide/settings/account/audit-logs/audit-logs#identity-and-access-management).
## FAQs
> [accordion] What are legacy keys?
>
> Legacy keys are API keys created automatically when the workspace was created and migrated from the older API keys dashboard to this one. You can regenerate them, but you cannot edit or archive them.
> [accordion] What is access token expiration in OAuth 2.0?
>
> OAuth 2.0 access token expiration is a security feature that limits how long an access token can be used to call protected APIs before it becomes invalid.
>
> An access token acts as a temporary digital pass. Instead of sharing your password with every app or service, the authorization server gives you a short-lived token. When that token reaches its expiration time, the API rejects any further requests and returns an `HTTP 401 Unauthorized` error.
> [accordion] Why does access token expiration matter?
>
> * **Better security**: If an attacker steals a short-lived token, they have only a brief window to exploit it before it stops working.
> * **Resource control**: Expiration prevents unused or abandoned tokens from filling up the authorization server's database.
> * **Standard lifespan**: You can set the access token expiration anywhere from 5 to 60 minutes.
> [accordion] How does MoEngage handle expired tokens?
>
> MoEngage issues a companion refresh token alongside the access token. Your integration exchanges that refresh token for a fresh access token in the background, without sending the API key again. The refresh token expires after 24 hours without a refresh, and after 30 days at most, so refresh at least once a day to keep the token alive. For the refresh request and its error codes, refer to [Refresh Access Token](/docs/api/oauth/refresh-access-token).
> [accordion] Where do I find my assumed-role ARN?
>
> You find it in your own AWS account. Create or identify the role your workload assumes, then copy its assumed-role ARN. MoEngage does not create the role or generate the ARN. For the format MoEngage accepts, see [ARN Format](#arn-format).
> [accordion] How many ARNs can one key have?
>
> One key accepts up to 10 ARNs. After the list reaches 10 entries, the dashboard disables **+ Add value**. To cover more sessions of the same role, use a wildcard session name instead of listing each session separately. See [Match All Sessions of a Role](#match-all-sessions-of-a-role).
> [accordion] Can I change the authentication type of an existing key?
>
> No, you cannot change it. You can edit the key name, the expiry time, the ARN list, and the API access, but the authentication type stays as you set it at creation. To switch an integration to a different authentication type, create a new key and archive the old one.
# Audit Logs
Source: https://moengage.com/docs/user-guide/settings/account/audit-logs/audit-logs
Track all user actions and configuration changes in your MoEngage workspace with audit logs. Filter by date, user, action type, and module.
Audit logs are a central place to record a trail of all actions and changes, such as user logins and configurations, that occur within your MoEngage workspace. They help you understand what changes were made, when they were made, and who made them.
The following are some examples of audit logs:
* A user logging into the account
* A user editing the account
* A user creating a content block
* A user editing an alert
> [!NOTE]
>
> * Only admins can view and download the audit logs.
> * The **Teams** is only visible when the feature is enabled for your account. (This specifies the team to which the user belongs when the particular action is performed.)
> * No user can modify or update audit logs.
# View Audit Logs
To view audit logs, perform the following steps:
1. On the left navigation menu in the MoEngage UI, navigate to **Settings**> **Account** > **Audit logs**. The Audit logs page appears. 
On the Audit logs page, the data is displayed in a tabular format, with columns containing details related to each activity performed by the user or team.
| Columns | Description |
| - | - |
| Time | This specifies the timestamp by capturing the specific day, month, and year when a particular action is performed. |
| Teams | This specifies the team to which the user belongs when a particular action is performed. |
| Entity | This specifies the type of event when the particular action is performed. |
| Activity | This specifies the summary when the particular action is performed. |
| Action | This specifies the type of task performed, such as CREATE, UPDATE, DELETE, EXPORT, INVITE, Campaign duplicated, Campaign resumed, Campaign archived, Campaign unarchived, or Campaign paused. |
| Actor | This specifies the email ID of the user who performed the particular action. |
| IP | This specifies the IP address of the system the user used to perform the particular action. |
# Events Captured in Audit Logs
This section helps you understand the events or activities performed for each module within your workspace:
## Identity and Access Management
| Entity, Module, or Object | Activity or Event | Revised Description |
| :- | :- | :- |
| **User (login/logout/change workspace)** |
Create
Update
Delete
|
A user logged in to the workspace.
The user switched to a different workspace.
A user logged out of the workspace.
|
| **Security Settings** **Note**: The Login Settings is now renamed to Security Settings |
Update
|
Login settings were updated (for example, MoEngage access enabled or login type changed to SSO).
|
| **Firewall** |
Create
Update
Delete
|
An IP address was added to the firewall. For more information, refer
An existing IP address in the firewall was updated.
An IP firewall rule was deleted.
|
| **Role** |
Create
Update
Delete
|
A new user role was created.
The description or permissions for a user role were updated.
A user role was deleted.
|
| **User Management** |
Update
Delete
|
A user's assigned role was changed.
A user's access was revoked, or their account was permanently deleted.
|
| **Team Management** |
Create
Update
Delete
|
A user was invited to join a team.
A user was added to a team, or existing team details were updated.
A team was deleted.
|
| **Authentication \[System for Cross-domain Identity Management (SCIM)]** |
Create
Update
Delete
|
A SCIM access token was generated, or SCIM was enabled for the workspace.
The SCIM configuration for the workspace was updated.
SCIM was disabled for the workspace.
|
| **Alert Management - Billing** |
Create
|
A new billing alert was created.
|
| **SSO** |
Update
|
The Single Sign-On (SSO) configuration was updated.
|
| **API Keys** |
Create
Update
Delete
|
An API key was created: `API key with name {{key-name}} and auth type {{Basic/OAuth 2.0/AWS STS}} created`.
An API key was regenerated: `API key with name {{key-name}} and auth type {{Basic/OAuth 2.0/AWS STS}} regenerated`. For an AWS STS key, MoEngage logs the secret change separately as `MOE-APPSECRET for API key with name {{key-name}} and auth type AWS STS regenerated`.
The ARN list of an AWS STS key was changed: `ARN for API key with name {{key-name}} and auth type AWS STS updated`.
An API key was archived: `API key with name {{key-name}} and auth type {{Basic/OAuth 2.0/AWS STS}} archived`.
**Note**: Descriptions use the short auth type names `Basic`, `OAuth 2.0`, and `AWS STS`. Audit logs record that a key was updated, but not which API groups were added or removed. To see the current scope of a key, open [View key details](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard#view-key-details). |
## File Import
| Entity, Module, or Object | Activity or Event | Description |
| :- | :- | :- |
| **Data Import** |
Create
Edit
Delete
|
A data import named `{{import-name}}` (`{{User - Anonymous/Registered / Event/ Aux-data}}`) was created via channel `{{S3/SFTP/CSV}}` by `{{uid}}`.
The data import `{{import-name}}` (`{{User - Anonymous/Registered / Event/ Aux-data}}`) was edited by `{{uid}}`.
The data import `{{import-name}}` (`{{User - Anonymous/Registered / Event/ Aux-data}}`) via channel `{{S3/SFTP/CSV}}` was deleted by `{{uid}}`.
A new content block was created or a draft was published. **Note**: When a draft content block is published, it is recorded as a CREATE event.
An existing content block was edited.
A content block was deleted.
|
| **UTM Parameters** |
Enable
Disable
Update
|
A UTM parameter was enabled.
A UTM parameter was disabled.
The UTM parameter settings were updated.
|
| **Tags** |
Create
Edit
Delete
|
A new tag was created.
An existing tag was edited.
A tag was deleted.
|
| **Category** |
Create
Edit
Delete
|
A new category was created.
An existing category was edited.
A category was deleted.
|
| **Content API** |
Create
Update
|
A new Content API was created.
An existing Content API was updated.
|
| **Global Control Group** |
Create
Update
Delete
Enable
|
A new Global Control Group was created.
The Global Control Group settings were updated.
The Global Control Group was deleted.
The Global Control Group was enabled or disabled. Turn on or turn off the Status toggle of a Global Control Group at **Settings** > **Advanced settings** > **Control groups** > **Global control group details**.
|
| **Reports** |
Create
Edit
Stop
Delete
|
A new report was created.
An existing report was edited.
A running report generation was stopped.
A report was deleted.
|
## Campaign Creation
| Entity, Module, or Object | Activity or Event | Description |
| :- | :- | :- |
| **Create new campaign** |
Publish
Save as draft
Send for approval
|
The campaign was published.
The campaign was saved as a draft.
The campaign was sent for approval.
|
| **Draft** |
Edit
Delete
Publish
|
The campaign draft was updated.
The campaign draft was deleted.
The campaign draft was published.
|
| **Send for approval** |
Reject
Approve
Edit
Publish
|
The campaign was rejected by an approver.
The campaign was approved.
The campaign, currently under review, was edited.
The approved campaign was published.
|
| **Under review** |
Duplicate
|
The campaign, currently under review, was duplicated.
|
| **Reject campaign** |
Duplicate
Edit
|
The rejected campaign was duplicated.
The rejected campaign was edited.
|
| **Approve campaign** |
Publish
|
The approved campaign was published.
|
| **Publish campaign** |
Edit
Duplicate
Pause
|
The published campaign was edited.
The published campaign was duplicated.
The published campaign was paused.
|
| **Pause campaign** |
Duplicate
Edit
Resume
Archive
|
The paused campaign was duplicated.
The paused campaign was edited.
The paused campaign was resumed.
The paused campaign was archived.
|
| **Archive campaign** |
Duplicate
Unarchive
|
The archived campaign was duplicated.
The archived campaign was unarchived.
|
| **Unarchive campaign** |
Duplicate
Edit
Resume
Archive
|
The unarchived campaign was duplicated.
The unarchived campaign was edited.
The unarchived campaign was resumed.
The unarchived campaign was archived.
|
| **Resume campaign** |
Duplicate
Edit
Pause
|
The active campaign was duplicated.
The active campaign was edited.
The active campaign was paused.
|
| **Edit campaign** |
Send for approval
Publish
|
The edited campaign was sent for approval.
The edited campaign was published.
|
| **WhatsApp Sender Details** |
Add
Update
Delete
|
A new WhatsApp sender was added.
An existing WhatsApp sender's details were updated.
|
# Filter Audit Logs
MoEngage allows you to search and sort audit logs within the workspace based on your selected criteria. You can filter the audit logs in two ways:
### Search Logs
1. On the left navigation menu in the MoEngage UI, navigate to **Settings** > **Account** > **Audit logs**. The Audit logs page appears.
2. In the **Search logs by** box, type the keyword, such as the Team, Entity, Activity, Action, Actor, or IP.
3. Press **Enter**.

### Filter Logs
1. Click the Filter icon.
2. On the Filter dialog box, enter the following details:
| Field | Description |
| - | - |
| **Team(s)** | Select the team to which the user belongs when the particular action is performed. |
| **Action** | Select the type of task performed. |
| **Actor** | Select the email ID of the user who performed the particular action. |
| **Date time Range** | Select the date range in which a particular action is performed. |

3. Click **Apply**.
The audit logs are displayed based on your selected criteria.
# Download Audit Logs
MoEngage allows you to export and download the audit log reports in CSV files. To download them, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, navigate to **Settings** > **Account** > **Audit logs**. The Audit logs page appears. 
2. [Filter the audit logs](#filter-audit-logs) if required.
3. Click **Export audit logs** in the upper-right corner. \
The audit log report is successfully sent to your email ID.
> [!NOTE]
>
> * You can export and download the audit log reports in CSV files using the following file naming convention: WorkspaceName_ExportID_YYYY-MM-DD.
> * Audit logs are available for the last 90 days only.
# Billing & Contract FAQs
Source: https://moengage.com/docs/user-guide/settings/account/billing/billing-and-contract-faqs
Answers to common questions about MoEngage subscription billing, usage metrics, invoicing, overages, annual escalations, and subscription changes.
This article outlines the frequently asked questions about:
* Product subscriptions
* Contract
* Billing and invoices
* Overages
* Renewals
* Annual price changes
> [!NOTE]
>
> If you can't find what you're looking for, your Customer Success Manager (CSM) is always happy to help.
## Product Subscriptions
> [accordion] Where can I see the products included in my contract?
>
> Your contracted products, along with their subscription start and end dates, are listed in the **Subscribed products** section. For more information, refer to [Manage Subscription](/docs/user-guide/settings/account/billing/manage-subscription#view-subscribed-products).
## Usage and Billable Metrics
> [accordion] Why does my billable MTU count exceed the size of my active customer base?
>
> * MTUs include all event-performing users, not just "active" ones MTUs count every unique user profile that performs at least one event in a calendar month - including background or system-triggered events. A user doesn't need to consciously open your app or website to be counted. This is broader than your intuitive notion of an "active customer."
> * Anonymous and identified profiles are both counted MTUs include all unique user profiles - both identified users (those with an email, phone number, or unique ID) and anonymous ones. Unauthenticated sessions, guest browsing, or pre-login activity all contribute to your MTU count.
## Billing Start and Invoicing
> [accordion] When does billing start after contract signing?
>
> There are two separate billing events after signing:
>
> 1. **Implementation / Onboarding fees** are invoiced immediately upon contract signing.
> 2. **Platform Subscription fees** are invoiced on the Platform Subscription Start Date specified in your Order Form.
> [accordion] We haven't completed go-live across all business units yet. How is billing handled?
>
> Billing is independent of your integration progress. The Platform Subscription fee runs from the Start Date in your Order Form, regardless of whether you have gone live across all business units.
>
> > [!TIP]
> >
> > Partner closely with your CSM during onboarding so your team can begin realizing value as quickly as possible.
> [accordion] Why are my Billable MTUs different from the actual MTUs shown in my dashboard?
>
> The difference is driven by two main factors:
>
> * **Timeframe Windows:** Dashboard metrics (like MAU) display a rolling last 30 days, whereas Billing MTUs are calculated strictly by the calendar month (28, 29, 30, or 31 days).
> * **Data Snapshots:** Billing is calculated as a fixed snapshot on the first day of the month. Dynamic dashboard queries account for real-time updates, such as user merges (which decrease dashboard counts) or delayed event processing (which increases dashboard counts), that occur after the billing snapshot has already been finalized.
## Overages
> [accordion] How can I monitor my usage to avoid unexpected overage charges?
>
> Unexpected overages can be costly and difficult to anticipate. You can monitor your MoEngage services by setting up [alerts](/docs/user-guide/inform/create/create-alert). This allows you to stay proactively aware of your usage trends and receive notifications when they exceed a defined limit, helping you avoid unexpected overages. This gives you time to adjust campaigns, throttle activity, or plan for an upgrade before charges are incurred.
> [accordion] How is an overage charge calculated when my usage exceeds the contracted limit?
>
> If your usage exceeds your contracted limit, whether for MTUs or channel-based usage like SMS, Email, or Push, an overage invoice is automatically generated.
>
> Overages are billed in fixed blocks rather than one unit at a time. Once your usage crosses into the next block, you are charged for the full block, so you always have headroom to keep running campaigns without interruption.
>
> > [!TIP]
> >
> > If you're approaching your limit and want to review your plan or upgrade your allocation, reach out to your Customer Success Manager.
## Annual Escalations
> [accordion] How and when are annual price increase applied?
>
> As per the escalation clause, an increase in price is applied at each anniversary of your Platform Subscription Start Date. The specific rate for your account is stated in your Order Form.
> [accordion] Does the annual price increment still apply if a later addendum does not mention it?
>
> Yes. The escalation clause in your Order Form, or in any previously signed addendum, remains in force unless a subsequent addendum explicitly supersedes or waives it.
> [accordion] Where can I find the annual escalation clause?
>
> You can find it in your Order Form Terms or your latest signed contract. If you'd like a walkthrough, your CSM can take you through the relevant clauses.
## Merlin AI Usage
> [accordion] How is Merlin AI usage billed?
>
> Merlin AI usage draws from a monthly pool of MoEngage Credits defined in your contract. The balance resets on the 1st of each calendar month, and unused credits don't roll over. For more information, refer to [Merlin AI Usage](/docs/user-guide/settings/account/billing/merlin-ai-usage).
> [accordion] Where do I track our credit consumption?
>
> Open **Settings** > **Account** > **Billing**, then select the **Merlin AI** tab. For more information, refer to [Merlin AI Usage](/docs/user-guide/settings/account/billing/merlin-ai-usage).
For questions about Merlin AI pricing, promotional credits, alerts, and usage limits, refer to [MoEngage Credits FAQs](/docs/user-guide/settings/account/billing/moengage-credits-faqs).
## Subscription Changes
> [accordion] How do I stop being billed for a product or service I no longer use?
>
> Reach out to your Customer Success Manager. They'll review your contract terms and, if eligible, guide you through executing an addendum to formally remove the product or service from your subscription.
>
> > [!WARNING]
> >
> > Simply pausing usage does not stop billing. A signed contract change is required.
## Still Have Questions?
For account-specific questions about your contract, invoices, or payment terms, contact your Customer Success Manager or write to our billing team.
# Manage Subscription
Source: https://moengage.com/docs/user-guide/settings/account/billing/manage-subscription
Activate your MoEngage subscription, review your current plan, and confirm the products included in your contract.
Your subscription determines the products and channels your team can use to plan and run campaigns in MoEngage. Use the **Billing** settings to activate your subscription, review your current plan, and confirm the products included in your contract. For a comparison of the plans MoEngage offers, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/).
## Activate Your Subscription
Activate your subscription to enable the plan contracted for your workspace, along with the products it includes. Use either of the following options.
### Option A: Welcome Guide
After you sign up, MoEngage displays a welcome prompt.
1. Enter your Subscription Code.
2. Click **Submit**.

### Option B: Setup Guide
1. In the upper-right corner, click the **Need help** dropdown, and then click **Setup Guide**.
2. Enter your Subscription Code and click **Submit**.

## View Your Current Plan Details
Review your plan details to confirm the features available to your team.
1. Navigate to **Settings** > **Billing**, then select the **Subscription** tab.
2. Click **Compare plans** to compare the plans MoEngage offers, or click **View details** on a specific plan to review its full feature list.

## View Subscribed Products
The **Subscribed products** section lists the products and add-ons included in your active contract. Review this section to confirm which MoEngage products your team can use and when each subscription term ends.
To view your subscribed products:
1. Click **Settings** > **Billing**, then select the **Subscription** tab.
2. Use the **Search by product name** field to find a specific product.
The table displays the following details for each contracted product:
| Field | Description |
| - | - |
| Name | The name of the product or add-on in your contract. |
| Start date | The date the product's subscription term begins. |
| End date | The date the product's subscription term ends. |
> [!NOTE]
>
> This list shows the products in your active contract. To add a product or to confirm your contract terms, contact your customer success manager.

### Download Subscribed Products
Click the **Download** icon to export your subscribed products list for internal reporting or contract review. The downloaded file includes the following columns:
| Column | Description |
| - | - |
| Date | The date the export was generated. |
| Workspace Name | The workspace the export was generated from. |
| Account Name | The billing account associated with the workspace. |
| Product | The name of the product or add-on in your contract. |
| Subscription Start Date | The date the product's subscription term begins. |
| Subscription End Date | The date the product's subscription term ends. |
### Access Permissions
Viewing and downloading subscribed products requires the same permissions as the Usage page. For more information, refer to [Access Permissions](/docs/user-guide/settings/account/billing/usage-details#access-permissions).
### FAQs
> [accordion] Why is a product missing from my Subscribed products list?
>
> The products that are part of your contract appear in this list. To add a product or to confirm your contract terms, contact your customer success manager.
> [accordion] Does the Subscribed products list reflect what I am billed for?
>
> The Subscribed products list shows the products and add-ons included in your active contract, along with their subscription terms. For a breakdown of your usage against billing metrics, refer to [Usage Details](/docs/user-guide/settings/account/billing/usage-details).
> [accordion] What happens when a product's subscription end date passes?
>
> To maintain uninterrupted access, contact your customer success manager before a subscription end date to discuss renewal or changes to your contract.
# Merlin AI Usage
Source: https://moengage.com/docs/user-guide/settings/account/billing/merlin-ai-usage
Track Merlin AI usage in MoEngage Credits, review consumption by service and team member, and monitor your usage.
## Overview
MoEngage Credits are the single unit that measures how much your workspace uses Merlin AI. Every text variation, generated creative, and agent run draws from one shared monthly credit balance.
## Features That Consume Credits
Every Merlin AI feature draws from the same credit balance:
| Feature | Where you use it |
| - | - |
| [Merlin AI Copywriter](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-copywriter/merlin-ai-copywriter) | Push campaigns, email subject lines, on-site messaging campaigns, and [Merlin AI Studio](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-studio). |
| [Merlin AI Designer](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-designer/merlin-ai-designer) | Push campaigns, email subject lines, on-site messaging campaigns, and Merlin AI Studio. |
| [Merlin AI Jinja Assistant](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-jinja-generator/merlin-ai-jinja-assistant) | Personalization across all campaigns. |
| [Merlin AI Segment Assist](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-segment-assist) | Segment creation and Merlin AI Studio. |
| [Merlin AI In-App Template Generator](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-in-app-template-generator/merlin-ai-in-app-template-generator) | In-app campaigns and Merlin AI Studio. |
| [Merlin AI Flows Assist](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-flows-assist) | Flows and Merlin AI Studio. |
| [Campaign Insights Agent](/docs/user-guide/ai-and-intelligence/merlin-ai/campaign-insights-agent) | Push campaigns, email campaigns, and on-site messaging campaigns. |
| [Custom Agents](/docs/user-guide/ai-and-intelligence/merlin-ai/agents/custom-agents) | Every agent run, recorded against the name of the agent. |
### Credit Factors
MoEngage records credits for each completed task run, based on the resources that task run uses. Each task run may have multiple agent requests associated to it.
* **Text generation:** MoEngage counts the input and output tokens the task run uses.
* **Image generation:** MoEngage counts the size, in bytes, of the asset the task run produces.
* **Agent runs:** MoEngage counts the model processing duration, the infrastructure the run uses, and any web searches the run executes.
Each completed task run updates your balance as soon as the task run finishes, so your team attributes consumption to a specific user, service, and sub service.
> [!NOTE]
>
> Merlin AI consumes credits when a task run completes, not when you accept the output. Regenerating a variation or re-running an agent consumes credits again.
## View Credit Consumption
On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Billing**, then select the **Merlin AI** tab.
### Summary Metrics
Before you read the metrics, set the scope and the reporting period:
* **Scope:** Open the scope selector and choose one of the following options:
* **Account:** View credit consumption across your entire account.
* **Workspaces:** View credit consumption for the workspaces you select. Use **Select all** or **Clear all** to adjust your selection quickly.
* **Month:** Select the month you want to report on. Every metric reflects the selected month and compares it against the previous month, so you see whether consumption is rising or falling.
The heading above the metrics confirms your current scope, and a **Last Refreshed** timestamp shows when MoEngage last updated the data.

#### Review Task-Level Data
To export the table of raw data covering every individual Merlin AI task run, click the download icon. The table includes the following details:
* The user who created the task run.
* The service and sub service of the task run.
* The credit consumed by the task run.
* The timestamp of the task run.
Apply the table filters to investigate an unexpected increase in consumption.
Based on your selection, the tab presents the following three metrics:
| Metric | What it shows |
| - | - |
| Credit usage | The credits consumed against the total allotment, with a progress bar. |
| Total AI sessions | The number of Merlin AI task runs. |
| Active AI users | The number of team members who use Merlin AI. |
### Analyze Consumption
The **Merlin AI** tab breaks your consumption down across the following four views. Each view reflects the scope and month you select.
> [tab] Consumption over time
>
> This view plots your credit consumption across the selected period, with one series per service. The legend below the chart identifies each service. Configure the chart using the following controls:
>
> * **Chart type:** Switch between a line chart and a bar chart.
> * **Granularity:** Choose **Daily**, **Weekly**, or **Monthly**.
> * **Service:** Keep **All services**, or select a single service to isolate its consumption.
>
> To download the chart, click **Export chart**.
>
> 
> [tab] Consumption by service
>
> This view splits your credits across Merlin AI services in a donut chart. A service is the Merlin AI feature that handles the task run, such as Merlin Copywriter, Merlin Designer, Jinja Assist, Inapp Assist, Flows Assist, or Custom Agent.
>
> The legend beside the chart lists each service alongside the credits it consumes and its percentage share of your total consumption.
>
> 
> [tab] Consumption by sub services
>
> This view ranks your sub services by credit consumption in a bar chart. A sub service is where you use the service, such as a push campaign, an email subject line, an in-app campaign, or Merlin AI Studio. For a Custom Agent, the sub service is the name of the agent.
>
> Each row identifies the service and the sub service, and shows the credits that combination consumes. The dropdown controls how many rows appear and defaults to the top 10. To see every sub service, click **View all**.
>
> 
> [tab] Consumption by user
>
> This view lists all users alongside the credits each user consumes, in a table with the following columns:
>
> * **Name** and **Email:** The user who created the task runs.
> * **Monthly usage:** One column for the selected month and one for each of the two preceding months, so you compare a user's recent activity.
> * **Sessions:** The number of Merlin AI task runs the user creates.
> * **Share:** The user's percentage share of total consumption, shown with a bar. Click the column heading to sort the table.
>
> To find a specific user, enter their name or email address in the search field. To narrow the table to one service, use the service dropdown. To download the table, click the export icon.
>
> 
## FAQs
> [accordion] Does every Merlin AI feature use the same number of credits?
>
> No. The credit of the task run reflects the resources that task run uses, such as the tokens a text generation consumes or the size of an image a task run produces. Review the task-level table to compare costs across services.
> [accordion] How current is the data on this tab?
>
> MoEngage records each task run against your balance as soon as the task run finishes, so consumption appears on this tab shortly afterward.
> [accordion] Can we see which team members consume the most credits?
>
> Yes. The **Merlin AI** tab lists all users and the credits each user consumes in the selected period, and the task-level table attributes each individual task run to a user.
For questions about pricing, promotional credits, alerts, and usage limits, refer to [MoEngage Credits FAQs](/docs/user-guide/settings/account/billing/moengage-credits-faqs).
## Related Articles
* [Merlin AI Studio](/docs/user-guide/ai-and-intelligence/merlin-ai/merlin-ai-studio)
* [Custom Agents](/docs/user-guide/ai-and-intelligence/merlin-ai/agents/custom-agents)
* [MoEngage Credits FAQs](/docs/user-guide/settings/account/billing/moengage-credits-faqs)
* [Usage Details](/docs/user-guide/settings/account/billing/usage-details)
* [Manage Subscription](/docs/user-guide/settings/account/billing/manage-subscription)
* [Billing & Contract FAQs](/docs/user-guide/settings/account/billing/billing-and-contract-faqs)
# MoEngage Credits FAQs
Source: https://moengage.com/docs/user-guide/settings/account/billing/moengage-credits-faqs
Answers to common questions about MoEngage Credits pricing, usage estimation, promotional credits, alerts, and usage limits for Merlin AI agents.
This article answers common questions about how MoEngage prices Merlin AI agents, how to estimate and track credit consumption, and what happens when your account reaches its monthly limit.
> [!NOTE]
>
> For questions about your credit allowance, usage planning, or contract, contact your Customer Success Manager (CSM).
## Pricing Model
> [accordion] How are Merlin AI agents priced?
>
> MoEngage prices Merlin AI agents in one unit: MoEngage Credits. Every Merlin AI agent draws from the same credit pool, including native agents such as Merlin AI Copywriter and Merlin AI Designer, [Custom Agents](/docs/user-guide/ai-and-intelligence/merlin-ai/agents/custom-agents), and agents that MoEngage releases later. You buy a monthly credit pack and plan against that pack alone.
> [accordion] Which plans include Merlin AI agents?
>
> Both the Growth and Enterprise plans include Merlin AI agents. On either plan, all agents use the same MoEngage Credits.
> [accordion] Are native agents and Custom Agents priced separately?
>
> No. One credit pool covers both. New agents use the same credits, so a new agent does not add a contract line or change your pricing.
> [accordion] What do credits pay for?
>
> Credits pay for the AI processing behind each action an agent takes: understanding your request, reasoning over your data, and generating copy, images, or campaigns. Consumption scales with the work involved. A short request, such as a subject line suggestion, consumes fewer credits than a multi-step Custom Agent task run that analyzes data and builds a campaign. For the factors MoEngage measures, refer to [Credit Factors](/docs/user-guide/settings/account/billing/merlin-ai-usage#credit-factors).
> [accordion] Do unused credits roll over?
>
> No. Credits load at the start of each month and expire at the end of it. This also applies to annual contracts: you receive a fresh allowance every month, and MoEngage does not bank unused credits quarterly or annually.
> [accordion] Are credits shared across my workspaces?
>
> Yes. MoEngage pools credits at the account level, so every workspace and user in your account draws from the same monthly allowance.
## Usage Estimation
> [accordion] What is a task run?
>
> A task run is one continuous piece of work with a Merlin AI agent. For example, asking Merlin AI Copywriter for push copy and refining it a few times, or running a Custom Agent that analyzes a segment and drafts a campaign. A task run can include several prompts, iterations, and outputs, and each of them consumes credits.
> [accordion] Which agents consume credits?
>
> All Merlin AI agents consume credits:
>
> * **Native agents:** Every Merlin AI feature listed in [Features That Consume Credits](/docs/user-guide/settings/account/billing/merlin-ai-usage#features-that-consume-credits).
> * **Custom Agents:** Every run, including runs that build push, email, in-app, or on-site messaging campaigns, or use [connectors](/docs/user-guide/ai-and-intelligence/merlin-ai/connectors/connect-external-apps).
> * **New agents:** Every Merlin AI agent that MoEngage releases later draws from the same pool.
> [accordion] How many credits does a task run use?
>
> Consumption depends on the agent and the task. A single short request, such as a subject line, consumes fewer credits than a task with several iterations, image generation, or campaign creation. To see what each task run consumed, refer to [Review Task-Level Data](/docs/user-guide/settings/account/billing/merlin-ai-usage#review-task-level-data).
> [accordion] How do I estimate how many credits I need?
>
> Use either of the following:
>
> * **Your own usage:** The **Merlin AI** tab shows credit consumption by day, week, and month, broken down by service and user, so you can identify the use cases that drive consumption. For more information, refer to [Analyze Consumption](/docs/user-guide/settings/account/billing/merlin-ai-usage#analyze-consumption).
> * **Your CSM:** Your CSM converts your planned use cases into a monthly credit recommendation based on the complexity of your requirements and tasks.
> [accordion] How do I reduce my credit consumption?
>
> * **Use a lighter model:** For simple tasks, select the **Fast** model instead of a reasoning model such as **Expert**. Lighter models consume fewer credits per task run.
> * **Refine your prompts:** Consolidate prompts and avoid redundant iterations within a task run. Clear, specific instructions reduce the number of follow-up adjustments.
> * **Adjust Custom Agent schedules:** Run automated Custom Agents less often. For example, run a monitor or report weekly instead of hourly or daily.
> * **Review usage trends:** Review task-level data on the **Merlin AI** tab to identify the agents, workspaces, or workflows that consume the most credits, and adjust their configuration.
## Promotional Credits
> [accordion] What are promotional credits?
>
> Promotional credits are complimentary, non-contractual credits that let you try Merlin AI agents and build use cases before you commit to a paid credit pack.
> [accordion] How many promotional credits do I get, and where can I see them?
>
> The **Merlin AI** tab shows your monthly allowance next to your consumption and remaining balance. Your CSM can also confirm your allowance.
> [accordion] Are any features restricted on promotional credits?
>
> No. Every Merlin AI agent feature on your plan works with promotional credits.
> [accordion] Do promotional credits expire?
>
> Yes. Like paid credits, promotional credits load monthly, and unused credits do not carry over. Promotional credits also end when the promotional program ends or when you move to a paid credit pack, whichever comes first.
> [accordion] What happens to promotional credits when I buy a paid pack?
>
> Promotional credits end. They do not stack on a paid pack; your paid monthly allowance replaces them.
> [accordion] What happens if I use up my promotional credits?
>
> Merlin AI agents pause until your next monthly allowance loads. To continue without a pause, buy a paid credit pack through your CSM.
## Usage Tracking and Alerts
> [accordion] Where can I track my credit usage?
>
> On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Billing**, then select the **Merlin AI** tab. The tab shows the credits used against your monthly allowance and updates as each task run completes. For more information, refer to [View Credit Consumption](/docs/user-guide/settings/account/billing/merlin-ai-usage#view-credit-consumption).
> [accordion] Can I see usage in more detail?
>
> Yes. The **Merlin AI** tab breaks usage down by user, workspace, service, and sub service, with daily, weekly, and monthly trends. Admins can also download the raw task run data to analyze in their own tools.
> [accordion] Do admins receive alerts before the account runs out of credits?
>
> Yes. Admins receive email alerts at 75%, 90%, and 100% of the monthly limit, and a notification when consumption reaches 100%. The alert thresholds are fixed; admins cannot add their own.
> [accordion] Are alerts set per workspace or per account?
>
> MoEngage applies alerts at the account level, because credits are pooled across the account.
> [accordion] Can I restrict usage by user, team, or workspace?
>
> No. Any user with access to Merlin AI agents can draw from the shared pool.
## Limits, Overages, and Admin Controls
> [accordion] What happens when I reach 100% of my limit?
>
> Merlin AI agents pause for your account, and your admins receive an email stating that the account has reached its limit. The rest of the MoEngage platform continues to work as usual. Agents resume when either of the following occurs:
>
> * Your next monthly allowance loads.
> * An admin raises the limit from the **Merlin AI** tab. This option is available on paid credit packs only.
> [accordion] Can I keep using agents after reaching my limit?
>
> Yes, if you are on a paid credit pack. An admin can raise your monthly limit from the **Merlin AI** tab, up to five times your allocated credits. MoEngage bills credits used beyond your pack as overage under the terms of your contract.
> [accordion] Can I lower my limit after raising it?
>
> No. An admin cannot lower a raised limit from the **Merlin AI** tab. At the start of the next month, the limit resets to the base credit allowance of your pack.
> [accordion] Does a live campaign stop if the account runs out of credits?
>
> No. Active campaigns do not consume MoEngage Credits while they run, so reaching your monthly limit does not affect running campaigns. If your account runs out of credits while you build a campaign with an agent, you cannot finalize or launch that campaign until your next monthly allowance loads or an admin raises the limit. Agents always ask for your approval before operations such as publishing a campaign.
> [accordion] How do I buy more credits or move to a bigger pack?
>
> Contact your CSM or account executive. After MoEngage updates your contract, the new monthly allowance applies to your account automatically.
## Rollout and Support
> [accordion] When does the credit-based usage limit start?
>
> The credit-based usage limit starts on January 1, 2027.
> [accordion] What should I do before the credit-based usage limit starts?
>
> Use the period before the limit starts to size your needs:
>
> 1. Try agents on the use cases you expect to rely on.
> 2. Review the **Merlin AI** tab to see how many credits those use cases consume.
> 3. Ask your CSM to recommend a credit pack based on that usage.
> [accordion] How does Merlin AI handle my data?
>
> The [MoEngage AI Terms of Usage Policy](https://www.moengage.com/ai-terms-of-usage-policy/) governs how Merlin AI features process data.
> [accordion] Who do I contact with questions?
>
> Contact your CSM for questions about credit allowances, usage planning, and contracts.
## Related Articles
* [Merlin AI Usage](/docs/user-guide/settings/account/billing/merlin-ai-usage)
* [Custom Agents](/docs/user-guide/ai-and-intelligence/merlin-ai/agents/custom-agents)
* [Billing & Contract FAQs](/docs/user-guide/settings/account/billing/billing-and-contract-faqs)
# Organization Details
Source: https://moengage.com/docs/user-guide/settings/account/billing/organization-details
View and edit your organization's agreement details with MoEngage, including contract information and billing terms on the dashboard.
The **Organization** tab provides the details of your organization's agreement with MoEngage.
> [!TIP]
>
> **Prerequisites**
>
> * You must have the **Growth** or **Enterprise** plan to view or edit your organization details.
> * Users must have the **View** permission for **Usage and** **Billing** to view the organization details.
> * Users must have the **Create & Manage** permission for **Usage and Billing** to edit the organization details.
# View Organization Details
> [!NOTE]
>
> Users on the **Starter** plan cannot view the organization details on the **Organization** tab.
>
> 
Perform the following steps to view the organization's details:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Billing**.
2. On the Billing page, select the **Organization** tab.

3. On the Organization tab, you can view the following details:
| Section | Fields & Description |
| - | - |
| Account Details |
**Organization name**: This field specifies the name of your organization.
**Industry**: This field specifies the industry in which your organization operates. For example, banking or e-commerce.
**Admin contacts**: This field specifies the email address(s) of your admins in the organization. MoEngage will send invoices, overages, and other organization-related messages to this email address.
|
| Contract Information |
**Contract Effective Date**: This field shows the date on which the contract for the organization was signed.
**Contract renewal date**: This field shows the date on which the contract is renewed for the organization.
**Billing frequency**: The field shows the frequency at which the organization is billed.
**Plan name**: This field shows the name of the current active plan configured for your workspace. **Note**: To update your account, contact your MoEngage Customer Success Manager.
**FUP Value**: This field displays the threshold or limit established in the Fair Usage Policy (FUP). The FUP outlines guidelines and rules to guarantee equitable and non-discriminatory access to MoEngage resources for all customers. For more information, refer [here](/docs/user-guide/data/key-concepts/fair-usage-policy-fup).
**FUP Type**: This field shows the type of policy (FUP) applied. The FUP type defines whether you are charged for utilising *All Events* or *Custom Events*.
**Data Retention Period**: This field shows how long your data is kept within the organization.
**Subscription code**: This field shows the subscription code entered (used to upgrade the plan details). **Note**: If you have already subscribed to a plan but have not received a subscription code, contact your customer success manager.
|
# Edit Organization Details
> [!NOTE]
>
> You can edit only the **Admin contacts** field in the **Account details** section.
To edit the organization details, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Billing**.
2. On the Billing page, select the **Organization** tab.

3. On the **Organization** tab, click the **Edit** link.

4. On the **Edit admin contacts** pop-up window, edit the existing admin contacts as necessary. You can add multiple email addresses, separate them with a comma, and press Enter.

5. Click **Save**.
Your organization details are updated successfully.
# Usage Details
Source: https://moengage.com/docs/user-guide/settings/account/billing/usage-details
Understand how MoEngage calculates your bill, then track your usage across billing metrics on the dashboard.
## MoEngage Billing Workflow
Your monthly invoice has two parts:
```text theme={null}
Platform pricing + Add-ons = Net invoice
```
**Platform pricing** is based on one or both models set in your contract:
* **Billable MTUs**: driven by your Monthly Tracked Users, Events, and Fair Usage Policy (FUP). For more information, refer to [Platform Pricing](#platform-pricing).
* **Profile-based**: a flat rate based on the number of user profiles in your account, simpler, and only applies if your contract specifies this model.
> [!NOTE]
>
> Add-ons are billed separately from platform pricing, and you're only billed for the ones you use. For more information, refer to [Add-Ons](#add-ons).
## Platform Pricing
For more information, refer to [Manage Subscription](/docs/user-guide/settings/account/billing/manage-subscription) to see which model applies to your account.
> [tab] Billable MTUs
>
> If your contract is on the Billable MTU model, your platform fee is based on your **Billable MTU**:
>
> ```text theme={null}
> Billable MTU = max(Total MTU, Events ÷ FUP)
> ```
>
> Billable MTU takes whichever is higher: your Total MTU, or your Events divided by your Fair Usage Policy (FUP) allowance. If you already know the formula and want to troubleshoot a specific change, refer to [Diagnosing a bill increase](#bill-increase-diagnosis).
>
> ### Events
>
> Every user action, tracked or auto-generated, feeds into MTU:
>
> * **Custom user actions**: events you send through your app, website, server-to-server integration, or other integrations (for example, "Added to Cart"). For more information, refer to [A Complete Guide to Event Tracking](/docs/user-guide/data/event-data/a-complete-guide-to-event-tracking).
>
> * **Standard events**: predefined events generated by MoEngage to automatically track key user interactions, such as App Opens and Website Views, as well as campaign-related interactions. For more information, refer to [Derived Events and Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes).
>
> > [!WARNING]
> >
> > Your contract defines whether "Events" here means Custom User Actions or Total Tracked Events. For more information, refer to [Organization Details](/docs/user-guide/settings/account/billing/organization-details).
>
> ### Total MTU
>
> MTU counts every unique user profile that performs at least one event in the calendar month, including anonymous profiles and background or system-triggered events, not only users who opened your app. A user active on more than one platform is counted only once.
>
> > [!NOTE]
> >
> > Total MTU is a distinct metric from MAU (Monthly Active Users). MAU is a separate dashboard metric that counts users who have at least one App/Site Opened event in the month, and it isn't part of the billing formula. Total MTU is always equal to or higher than Total MAU, since MTU also counts anonymous profiles and background events.
>
> | MTU metric | What it counts |
> | - | - |
> | Mobile Tracked Users | Unique user profiles that performed at least one event on your mobile app in the month. |
> | Web Tracked Users | Unique user profiles that performed at least one event on your website in the month. |
> | TV Tracked Users | Unique user profiles that performed at least one event on your TV app in the month. |
> | Total MTU | Count of distinct users tracked at least once in a calendar month across all platforms: mobile, web, and TV. A user active on multiple platforms in the same month is counted only once. |
>
> **Example**: 10,000 mobile-only users + 4,000 web-only users + 1,000 users active on both (counted once, not twice) = 15,000 Total MTU.
>
> ### FUP
>
> Fair Usage Policy (FUP) is the average number of events allowed per user per month, set in your contract (typically 50–500 events per user). If your event volume pushes past this allowance, your billable MTU is recalculated upward, and you start paying based on event volume, not only on user count. To find your FUP, refer to [Organization Details](/docs/user-guide/settings/account/billing/organization-details).
>
> #### Worked Example: Calculating Billable MTU
>
> Say your account has a Total MTU of 80,000, your contract sets FUP at 100 events per user, and your contract's event basis is Total Tracked Events. You record 12,000,000 Total Tracked Events this month.
>
> | Line item | Value |
> | - | - |
> | Total MTU | 80,000 |
> | Total Tracked Events this month | 12,000,000 |
> | Contracted FUP | 100 events/user |
> | Events ÷ FUP | 12,000,000 ÷ 100 = 120,000 |
> | **Billable MTU** | **max(80,000, 120,000) = 120,000** |
>
> Events ÷ FUP (120,000) is higher than Total MTU (80,000), so you're billed on 120,000, since event volume outpaced your FUP allowance.
>
> #### Try It: Billable MTU Calculator
>
> Enter your own numbers to see which side of the formula determines your bill.
>
> Billable MTU Calculator
> RESET
>
> Total MTU (all platforms)
>
> Event basis (per your contract)
>
> Events this month (selected basis)
>
> Contracted FUP (events per user)
>
> Total MTU
>
> Events ÷ FUP
>
> Billable MTU
>
> ### Bill Increase Diagnosis
>
> | Observation | Likely cause |
> | - | - |
> | Total MTU grew proportionally | Expected, more tracked users means more cost. |
> | Total MTU flat, but Billable MTU jumped | Check average events per user, you likely crossed your FUP threshold. |
> | Messaging or channel costs rose, MTU flat | This is a channel-usage change, not a user-count change. Check add-on usage (Email, SMS, WhatsApp, Push, RCS, Cards, Landing Pages, Data Exports & Imports) under [Add-Ons](#add-ons). |
> [tab] Profile-Based
>
> If your contract specifies profile-based pricing, your platform fee is a flat rate based on the number of user profiles in your account each month. MTU, Events, and FUP don't factor into your billing under this model.
>
> | Term | Description |
> | - | - |
> | All Profiles | The total number of unique user profiles (both identified and anonymous) in your workspace. |
> | Identified Profiles | The subset of All Profiles with an identifier, such as an email, mobile number, or unique ID. |
> | Billing basis | Billed per profile tier, based on either All Profiles or Identified Profiles depending on your subscription. |
>
> Add-ons (messaging channels, RCS, Cards, Data Exports & Imports) are billed the same way regardless of which platform pricing model you're on. For more information, refer to [Add-Ons](#add-ons).
>
> Profile-based billing keeps things simple, no MTU, Events, or FUP calculation is involved, and the profile count each month is the only variable. Add-ons (messaging, RCS, Data Exports & Imports) are added on top, the same as under the MTU model.
## Add-Ons
These are billed on top of platform pricing when the corresponding add-on is enabled on your plan. Add-on rates vary by contract.
> [accordion] Messaging channels
>
> Messages sent to your users through campaigns and flows on the Email, SMS, and WhatsApp channels. You're billed only for the channels enabled on your plan, based on the volume sent each month.
>
> | Metric | Description |
> | - | - |
> | Emails Sent | Number of emails sent to your users across all campaigns and flows, based on MoEngage's internal count. This number isn't used for billing. Email billing is based on delivery data reported by your configured email service provider, such as SendGrid. The two numbers can differ because each provider calculates "sent" using its own logic. For example, some providers count a message as sent as soon as their servers accept it, while others count it only after delivery attempts, deferrals, and retries are resolved, or after checking it against their own suppression list. |
> | Emails Sent via MoEngage SendGrid | Number of emails sent to your users across all campaigns and flows through MoEngage's managed SendGrid service. |
> | Dedicated IPs for emails | Number of distinct dedicated IP addresses used for sending emails. |
> | SMS Sent | Number of SMS message parts sent to your users across all campaigns and flows, based on MoEngage's internal count. This number isn't used for billing. SMS billing is based on delivery data reported by your configured SMS service provider, such as Twilio. The two numbers can differ because each provider calculates "sent" using its own logic. For example, some providers count a message as sent as soon as their servers accept it, while others count it only after carrier delivery attempts and retries are resolved and a delivery receipt is returned, or after checking it against their own opt-out list. |
> | SMS Sent via MoEngage Twilio | Number of SMS message parts sent to your users across all campaigns and flows through MoEngage's managed Twilio service. |
> | WhatsApp Messages Sent | Number of WhatsApp messages sent to your users, across all campaigns and flows. |
> [accordion] Inform
>
> Inform is MoEngage's transactional messaging infrastructure. You're billed only for channels you use, based on the number of messages sent.
>
> | Metric | Description |
> | - | - |
> | Total Inform Messages | The combined total of all messages sent across all channels (Push, Email, SMS, and WhatsApp) via Inform. |
> | Inform Push Messages | The number of push notifications sent to your users via Inform. |
> | Inform Email Messages | The number of email messages sent to your users via Inform. |
> | Inform SMS Messages | The number of SMS messages sent to your users via Inform. |
> | Inform WhatsApp Messages | The number of WhatsApp messages sent to your users via Inform. |
> [accordion] Additional channels
>
> Available if RCS, Cards, or Landing Pages are enabled on your plan.
>
> | Metric | Description |
> | - | - |
> | RCS Sent | RCS messages sent to your users. |
> | Cards Sent | Cards sent across campaigns and flows. |
> | Landing Page Views | Total non-unique impressions across landing pages. |
> [accordion] Data Exports & Imports
>
> Automated data exports to your data warehouse, partner tool, or API destination, and data imports from your data warehouse. Billed based on the monthly volume if not already covered by your plan.
>
> | Metric | Description |
> | - | - |
> | Streams | Number of events sent to partners, such as API, mParticle, and Segment. |
> | Data Warehouse Exports | Number of events sent to data warehouses, such as S3, SFTP, Snowflake, and Databricks. |
> | Data Warehouse Imports | Number of records received from data warehouses: Snowflake, Databricks, and BigQuery. |
> [accordion] Open Analytics
>
> Available if you run queries through MoEngage's open analytics or data warehouse querying capability.
>
> | Metric | Description |
> | - | - |
> | Open Analytics Usage | The total volume of monthly data scanned to execute your open analytics queries. |
### Account-Level Metrics
The following metrics are calculated at an account level in the UTC timezone, unlike all other metrics, which are calculated at a workspace level in the [workspace's configured timezone](/docs/user-guide/settings/account/general-settings/workspace-settings):
* Dedicated IPs for emails
* Emails Sent via MoEngage SendGrid
* SMS Sent via MoEngage Twilio
## View Usage
To access the Usage page, on the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Billing**, then select the **Usage** tab.
### Access Permissions
The following table describes the permissions required to access and use the Usage page:
| Permission component | Permission name | Details |
| - | - | - |
| Usage and Billing | View Usage | Grants read-only access to the Usage page. You can change filters, select a date range, and view billing charts and trends. You see a workspace only if it's attached to the same billing account as your current workspace, and you have *Usage and Billing > View Usage* permission for that workspace. |
| Usage and Billing | Manage account details | Allows you to switch between workspace and account views in the usage filter. When enabled, the **Account** option appears in the filter drop-down. At the account level, all metrics are displayed as the sum across all workspaces. |
| Usage and Billing | Download | Allows you to download charts and tables directly from the MoEngage dashboard. |
| Alert Manager | Manage alerts | Allows you to create or edit alerts on any billing metric. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles). |
## Analyse Trend
The **Usage Trends** section lets you visualize data patterns for different metrics, organized under the Data, Engage, Inform, and Media Volumes categories.

**1. Filter your data**
Select the data to analyze using the filters at the top of the page:
* **Select workspaces/account**: Use the filter drop-down to choose the scope of data to view.
* **Workspaces**: Choose one or more workspaces to include in the analysis. By default, your current workspace is selected. You only see workspaces mapped to the same billing account as your current workspace, and for which you have the necessary permissions (see [Access Permissions](#access-permissions) above).
* **Account**: View all metrics aggregated as the sum across all workspaces in your account. This option requires the *Manage account details* permission.
* **Select date range**: Define the time period. Choose **This month**, **Last month**, or a **Custom range** (up to the last 12 months). The selected date range also applies to the chart and table view.
> [!NOTE]
>
> * By default, the page shows data for the current calendar month.
> * Usage data is available from October 2025 onward.
> * All metrics are tracked based on your workspace's configured timezone, except those listed in [Account-Level Metrics](#account-level-metrics).
**2. View and interpret the trends**
Use the controls to customize your chart or table view:
* **Category**: Select the tab for the metrics you want to view: **Data**, **Engage**, **Inform**, or **Media Volumes**.
* **Metric selection**: Select a metric from the drop-down list. The available metrics depend on the category you select, for example **Events** under **Data**, or **SMS** under **Engage**.
* **Granularity**: View data aggregated **Monthly**, **Quarterly**, or **Annually**.
* **Chart and table view**: Switch between a line chart for quick visual analysis and a table for exact numbers.
For example, to see the trend of custom events you tracked over the last 3 months:
1. On the **Data** tab, select the metric you want to view from the drop-down list. **Events** is selected by default.
2. Set the granularity to **Monthly**, **Quarterly**, or **Annually**. **Monthly** is selected by default.
3. Select the chart or table icons to switch between a visual graph and a detailed data table. **Chart** view is selected by default.

**3. Export and download your data**
You can export data for reporting and record-keeping in two ways:
* **Download the metrics list**: Click **Download** on the metrics list to download a full usage report.

* **Export trends data**:
* In the chart view, click **Export Chart** to download the graph as a PNG file.
* In the table view, click **Download Table** to download the raw data as a CSV file.

## Create Alerts
Stay ahead of your usage with custom alerts that notify you as soon as a metric crosses a limit you define. This gives you time to adjust campaigns, throttle activity, or plan an upgrade well before charges are incurred.
To create an alert:
**1. Open Alert Management**
Click **+ Manage Alert** in the upper-right corner.

The **Alert management** page appears.
**2. Start a new alert**
Click **+ Create alerts** in the upper-right corner. The **Create alert** page appears.
**3. Enter the general details**
On the **Create Alert** page, enter the general details:
* **Alert name**: Enter a unique name for your alert.
* **Create Alerts On**: Campaign Stats is selected by default. To monitor usage and billing metrics, select **Billing**.
* **Send Alert On**: Select your primary notification channel (for example, Email).
* (Optional) Click **+ Add alert destination** to configure Slack, MS Teams, or Webhooks as an alert destination. For more information, refer to [Alert Destinations](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/create-an-alert#alert-destinations).
**4. Define the alert condition**
* In the **Send alerts when** list, select the metric to monitor (for example, Total Tracked Events, Total Monthly Active Users, Web Active Users).
* Set the threshold logic (for example, **Is greater than**) and enter the numerical limit.
**5. Add recipients**
In the **Members** section, select the team members who should receive notifications. You can add any registered MoEngage UI user to the alert.
**6. Save the alert**
Click **Create**. For more information, refer to [Alert Management](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/overview-alert-management).
### Alert Evaluation Logic
MoEngage evaluates alerts daily and scans usage data accumulated up to the evaluation time against your set limits. You receive a notification as soon as the daily scan identifies that your usage exceeds a defined threshold.
> [!NOTE]
>
> * You can edit and delete alerts. For more information, refer to [Managing Alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts).
> * MoEngage offers role-based permissions to create alerts. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
## FAQs
> [accordion] Why is there a discrepancy in event count between the Billing Usage page and the Data Management page?
>
> The Billing Usage page reflects all data processed within the month, including historical backfills through file or data warehouse imports and data that arrives late due to delays. The Data Management page shows a daily snapshot and doesn't retroactively update historical graphs for events added after the original date passes. Your bill reflects the total volume of data ingested, while Data Management shows only what MoEngage captured at that time.
> [accordion] Why is there a difference between the data in Billing and Key Metrics?
>
> Key Metrics shows Monthly Active Users (MAU) as a rolling count for the last 30 days. Billing MTU is calculated on the actual calendar month, which varies between 28, 29, 30, or 31 days depending on the month or leap year. This difference in calculation windows means the two numbers rarely match exactly.
> [accordion] Why is there a difference between the data in Billing and Segmentation?
>
> MoEngage calculates billing MTU on the first day of every month as a fixed snapshot. Segmentation queries run against live data, so the two can drift apart afterward:
>
> * If a user merge happens after the billing calculation, re-running a segmentation query can show a decrease in user count.
> * If events reach MoEngage's servers with a delay, re-running a segmentation query after the delay can show an increase in user count.
# Context Hub
Source: https://moengage.com/docs/user-guide/settings/account/context-hub/context-hub
Capture your brand and business context once in Context Hub and reuse it across MoEngage workflows.
Context Hub is where your Organization Context lives in MoEngage. Organization Context is the brand, business, and communication information you capture once — brand guidelines, communication and regulatory guidelines, channel details, and business-specific context — so that it can be reused across your MoEngage workflows.
You can find Context Hub under **Settings > Account > Context Hub**.
## Getting started
Before you first open Context Hub, Merlin AI extracts your brand and business context in the background, so the results are usually ready and stored by the time you arrive. You receive an email once extraction is complete.

**1. Open Context Hub and select Get started**
Go to **Settings > Account > Context Hub** and select **Get started**. In most cases, Merlin AI has already extracted your context.
**2. Review the AI Inferred context panel**
The extracted results appear as the **AI Inferred context** panel at the top of the page. See [Review and add AI-inferred context](#review-and-add-ai-inferred-context).
## How Merlin AI extracts context
Merlin AI automatically surfaces brand and business information for you to review and add to Context Hub.
### How it extracts information
* It extracts from your past campaign activity and platform usage.
* If Merlin AI identifies your brand's website from your past campaign data, it also runs a web search to gather more brand information.
### What is extracted
Merlin AI organizes the context it extracts into categories, each holding specific entities:
* **Visual system** — logos, colours, fonts, typography, buttons, hyperlinks, visual style guidelines, imagery rules, iconography, accessibility rules.
* **Identity** — brand story, approved taglines.
* **Brand voice and tone** — tone of voice, brand voice rules, prohibited words, brand voice exemplars.
* **Formatting** — naming conventions, punctuation and number formatting.
* **Others** — regulatory disclaimers, channel brand adaptations.
### When it runs
* Merlin AI runs automatically in the background, without any manual trigger.
* It runs on a fixed cadence: after one week, or after 50 campaigns are published, whichever happens first.
### How it handles what you add or leave out
* Nothing is selected by default. You choose which categories to add.
* Leaving a category unselected is not a permanent rejection. Merlin AI treats it as "not interested at the moment" and surfaces that content again on every later run.
* For a category you have already added, if a later run finds no new information about that entity, it stops appearing in the results.
## Page structure
Once Context Hub contains information, the page shows a **Last Updated** timestamp at the top.
Content sits under the **Brand** tab, with an in-page navigation list on the left: **Visual system**, **Identity**, **Brand voice and tone**, **Formatting**, and **Others**. Each section groups related entries — for example, Visual system contains Logos and Colours. A section with no entries yet shows "No context added."

## Review and add AI-inferred context
When Merlin AI finishes extracting information, the **AI Inferred context** panel appears at the top of the page, labeled "Context inferred from past campaign activity and platform usage."

**1. Review the categories**
Review the categories listed — for example, **Visual system**, **Brand voice and tone**, **Identity**, and **Formatting**. Each category shows a short description of what was extracted, and you can expand it to see the individual items it contains.
**2. Select what you want to add**
Select the checkbox next to a category to add everything in it, or expand the category and select individual items. Nothing is selected by default, and **+ Add to context hub** stays disabled until you select at least one item.
**3. Add your selection**
Click **+ Add to context hub** to confirm your selection.
> [!NOTE]
>
> Categories you do not select remain available. You can return at any time and add them. The content in an unselected category may update after a later extraction.
## Add context using Merlin AI
You can also add context on demand by chatting with Merlin AI. You share information as text, files, or a website. Merlin AI extracts the relevant context, shows it to you for review, and adds what you approve.
### Accessing the chat agent
**1. Open Context Hub**
Go to **Settings > Account > Context Hub**.
**2. Open the Add context drawer**
On the Context Hub page, open the **Add context** drawer.

Select one of the pre-defined options to start with, or write your own prompt to start extracting context.
### Provide your sources
Give Merlin AI the information you want it to extract from. Use the input box at the bottom of the chat, labeled "Paste, type or attach context here or ask a question." You can:
* **Type or paste text**, such as a list of do's and don'ts for copywriters.
* **Attach a document**, such as a brand guidelines PDF. Select the **+** button to attach a file.
* **Share a website.** Paste a URL, such as your brand's website.
* **Ask Merlin AI to search the web** for information, such as about your brand.
You can combine sources in a single message. For example, you can attach a document and include a website URL in the same request.
> [!NOTE]
>
> You can also ask Merlin AI a question about what is already in Context Hub. It answers using the stored context without adding anything.
### Review the extracted information
After you send a request, the extracted context appears in the **Extracted information** panel on the right, grouped by category. The panel shows when the information was last extracted.
Merlin AI compares what it extracts against what is already stored and separates the results into two tabs:
* **New additions** — context that is new to Context Hub.
* **Updates** — context that changes a value already stored in Context Hub.

Each result is a checkbox tree. Expand a category to see its entries and the individual details Merlin AI found for each one. Select the checkbox next to a category, an entry, or a single detail to choose what you want to add. Clear a checkbox to leave that item out.
> [!NOTE]
>
> Only the items you select are added to Context Hub. Review the extracted items and select only the ones you want — nothing is saved to Context Hub until you select **Add to context hub**.
### Add to Context Hub
Once you have reviewed your selection, select **Add to context hub**. The selected new additions and updates are saved to Context Hub.
Items you do not select are not added.
> [!NOTE]
>
> Context extracted during a session but not added to Context Hub is available only while you are logged in. If you log out, you need to chat with Merlin AI again to extract the information from your sources.
### Conversation history
Merlin AI retains your conversation history for 30 days.
## Manually edit added context
**1. Find the entry**
Locate the entry you want to edit. Use the in-page navigation list (**Visual system**, **Identity**, **Brand voice and tone**, **Formatting**, **Others**) to jump to the relevant section if needed.
**2. Expand the entry**
Click the entry to expand it. The entry opens in an editable state.
**3. Make your changes**
Edit the content directly in the expanded entry. Your changes save automatically.

> [!NOTE]
>
> Some entries have their own fields. For example, the Fonts entry under Visual system lets you set fallback fonts and add fonts. Default fonts you add apply to campaigns published after the font is added; previously published campaigns keep the fonts they were created with.
## Clear or delete context
Context Hub includes a standard set of information, and you can also add your own custom information. Each entry has a three-dot menu with options to clear or delete it.
To clear an entry:
**1. Find the entry**
Locate the entry you want to clear.
**2. Open the entry menu**
Click the three-dot menu on that entry.
**3. Clear the content**
Select **Clear content**.
> [!WARNING]
>
> Clearing content happens immediately. There is no confirmation step, and cleared content cannot be recovered. Clearing removes the entry's values but keeps the entry itself.
**Deleting an entry**
The three-dot menu also has a delete option, labeled with the entry name — for example, **Delete Logos**. You can delete only the custom information you added. For standard information that is part of Context Hub, this option is disabled. Deleting removes the entry entirely.

## Applicability
Applicability is a layer on top of every entity in Context Hub. It determines how that entity is used in downstream, MoEngage-native surfaces. There are two kinds of downstream usage:
* **Manual usage** — the specific channels where the entity is applied directly: Email, In-app, OSM, and Landing pages.
* **Merlin AI usage** — the MoEngage AI features that may draw on the entity, such as Custom agents, Flows assist, Email agent, In-app agents, and Segment assist.
Each entity shows a usage indicator with one of two states: **Merlin AI only**, or **Manual + Merlin AI**.
### Applicability matrix
The Applicability matrix lists each entity by sub-category and marks where it applies across the manual channels and Merlin AI features. To open it, use either of these:
* Select **here** in the help link at the top of the page: "Click here to learn more about how information in Context Hub is used within MoEngage."
* Hover over the grid (dots) icon on an entry to open its usage popover, then select **View usage for all data points**.

In the matrix, use the search box, the **All / Manual usage / Merlin AI usage** filters, or the sub-category selector to narrow the list.

The matrix uses these columns:
* **Sub-category** — the category the entity belongs to, such as Identity or Visual system.
* **Information** — the specific entity within that sub-category, such as Brand story, Approved taglines, Logos, Colours, Typography, Buttons, Hyperlinks, or Fonts.
The remaining columns are the **Manual usage** channels and **Merlin AI usage** features described above. A green check means the entity is used in that channel or feature; a dash means it is not.
Every Brand entity is available to all Merlin AI surfaces (Custom agents, Flows assist, Email agent, In-app agents, and Segment assist). The manual channels vary by entity:
| Entity | Applied channels |
| - | - |
| Fonts | Email, In-app, OSM, Landing pages |
| Colours | Email, In-app, OSM, Landing pages |
| Logos | In-app only |
| Typography | Email, In-app |
| Buttons | Email, In-app |
| Hyperlinks | Email, In-app |
| Visual style guidelines | None |
| Imagery rules | None |
| Iconography | None |
| Accessibility rules | None |
| Brand story | None |
| Approved taglines | None |
| Tone of voice | None |
| Brand voice rules | None |
| Prohibited words | None |
| Regulatory disclaimers | None |
| Channel brand adaptations | None |
| Brand voice exemplars | None |
| Naming conventions | None |
| Punctuation & number formatting | None |
# How To Resolve reCAPTCHA Issues in the Browser When Logging In to the Dashboard?
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/how-to-resolve-recaptcha-issues-in-the-browser-when-logging-in-to-the-dashboard
Troubleshoot reCAPTCHA errors when logging into the MoEngage dashboard. Fix issues by updating your browser, enabling JavaScript, or more.
## Problem
When logging in to the MoEngage dashboard, the browser encounters issues with contacting reCAPTCHA.
## Instructions
If reCAPTCHA fails to load or function correctly, follow these steps:
1. **Update the browser**:
* Ensure your browser is current and meets the minimum system requirements.
2. **Enable JavaScript**:
* Verify that JavaScript is enabled in your browser. For more information, read [Allow JavaScript in your browser](https://support.google.com/adsense/answer/12654?hl=en).
3. **Disable extensions**:
* Turn off any browser extensions that might interfere with reCAPTCHA.
4. **Reset your browser**:
* Try resetting your browser settings.
5. **Check for malware**:
* Scan your device for malware that could affect browser functionality.
6. **Change your DNS**:
* Switch to Google DNS to resolve potential connectivity issues.
7. **Avoid VPNs and proxy services**:
* VPNs and proxy services may trigger reCAPTCHA's security measures. Disable them and try again.
# Suspicious Login Verification
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/suspicious-login-verification
Learn how MoEngage verifies suspicious logins from new devices or locations using an OTP sent to your registered email for added security.
# Overview
Logging in from a new location or a new device requires further authentication using an OTP sent to your email address. MoEngage sends an OTP to your registered email whenever it detects a new device/new location for your ID. This is more beneficial than only using login credentials, as
* An additional layer of authentication increases security.
* The risk, in case of compromised credentials, is reduced.
# Log In
Once you enter your login credentials on the login page, MoEngage detects either your device or location as unrecognized and takes you to a new page where the system asks you for an OTP.

1. Enter the OTP received on your registered email address.
2. Click **Verify**.
> [!NOTE]
>
> * If you don't see the mail in your inbox, you can search for an email with the subject line MoEngage login OTP.
> * The OTP is valid for 3 minutes only. After 3 minutes, your OTP will expire, and you will have to re-enter your credentials.
You should now be directed to your MoEngage account. If you still have any issues, contact the MoEngage Support team.
# Troubleshoot SCIM Integration Errors
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/troubleshoot-scim-integration-errors
Resolve common SCIM provisioning errors in MoEngage when integrating with your identity provider, including JumpCloud and other SCIM 2.0 IdPs.
## Supported Identity Providers
MoEngage supports SCIM provisioning with any Identity Provider (IdP) that follows the SCIM 2.0 protocol. [Okta, Azure (Microsoft Entra ID), and JumpCloud](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim) are documented with step-by-step guides because most MoEngage customers use these IdPs, not because MoEngage limits SCIM support to them.
If you use a different SCIM 2.0-compliant IdP, follow your IdP's documentation to configure the SCIM base URL and bearer token generated from your MoEngage workspace. For details on generating this token, refer to [Configure SCIM in MoEngage](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim).
## Problem
Provisioning fails, or user or role updates from your IdP don't sync to MoEngage.
## Explanation
SCIM sync errors surface in your IdP's admin console, not in MoEngage, since your IdP is the system that initiates and reports the sync operation.
> [!NOTE]
>
> Set up [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso) for your MoEngage workspace before you configure SCIM. MoEngage requires a working SSO configuration as a prerequisite for SCIM.
## Solution
1. Check your IdP's admin console for the specific sync error message and details.
2. Share the exact error message from your IdP with the MoEngage Support team so they can investigate the sync failure.
## JumpCloud-Specific Issues
> [accordion] Provisioning fails when group management is enabled
>
> JumpCloud currently creates SCIM groups without any user members, which the MoEngage API rejects. Leave the **Enable management of User Groups and Group Membership in this application** toggle disabled on the Provisioning tab, and assign roles at the individual user level instead. For steps, refer to [Map the Role Attribute](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-4-map-the-role-attribute).
> [accordion] Role updates don't reflect in MoEngage
>
> Confirm the destination attribute in JumpCloud's Export Attribute Mapping uses a period before role, not a colon: `urn:ietf:params:scim:schemas:extension:moengage:2.0:User.role`. JumpCloud reads role as a property of the `moengage:2.0:User` extension, unlike the colon-separated syntax used for Okta and Azure.
# User unable to log in
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/user-unable-to-log-in
Resolve MoEngage 2FA login errors like expired OTP by checking your system clock. Step-by-step fix for two-factor authentication failures.
## Issue: An error occurs on the 2 Factor Authentication screen during login
#### Scenario
After entering the email and password, the user is redirected to the 2 Factor Authentication screen and then to the login screen with the error "OTP Expired, please login again."
#### Explanation
If there is a difference between the local system time and the current time, the code verifies the user's current local system time for OTP verification. So, the user gets the error for OTP expiration.
#### Resolution Steps
* Ask the user to check the current local system time and verify it with the current time on this website: [https://greenwichmeantime.com/current-time/](https://greenwichmeantime.com/current-time/)
* If the times differ, ask the user to change their system time.
> [!NOTE]
>
> This issue is also seen with a difference of 3 seconds in the timings, so if the user mentions that there is no time difference or the issue is unresolved after following the resolutions steps, please contact the user and verify the exact time.
# Why Does Switching Between LIVE and TEST Environments Fail?
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/why-does-switching-between-live-and-test-environments-fail
Fix the MoEngage error when switching between LIVE and TEST environments by inviting the team member to both workspace environments.
## Problem
When trying to switch to the LIVE environment, the following message appears:
No permission to access account. 
## Explanation
This issue occurs because you have been invited to only the TEST or LIVE environment, not both.
## Solution
Invite the team member to the missing environment (LIVE or TEST) to grant access.
# Why Is the OTP Not Received on Email for 2FA?
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/why-is-the-otp-not-received-on-email-for-2fa
Troubleshoot missing OTP emails for two-factor authentication in MoEngage, including spam folder checks and domain whitelisting steps.
## Problem
A one-time password (OTP) is not received through email for two-factor authentication (2FA).
## Solution
Perform the following steps:
1. Ensure that 2FA is enabled in the workspace.
2. Ensure that you have entered the correct email address.
3. Check your spam or junk folder for the OTP email.
4. Ensure that the MoEngage domain is whitelisted by the IT team.
5. Ideally, the OTP Verification page looks like this: 
6. If the 2-Step Verification page shows a warning message, set up a 2-step verification on your device. The warning message states: "WARNING! Your admin has enabled 2-step verification for your account. Please set it up on your device to continue access." 
# Why Is the User Unable to Log in to the Dashboard?
Source: https://moengage.com/docs/user-guide/settings/account/faqs-account-management/why-is-the-user-unable-to-log-in-to-the-dashboard
Resolve MoEngage dashboard login issues by verifying your data center URL, checking signup status, and contacting your account admin.
## Problem
Unable to log in to the MoEngage dashboard.
## Solution
Perform the following steps:
* Verify the data cluster URL. Ensure that the URL you are using to log in is correct. The following table lists the correct URL for each data center. You can contact your admin or Customer Success Manager (CSM) to confirm your data center.
| Data Center Name | Dashboard URL |
| - | - |
| DC-01 | [https://dashboard-01.moengage.com/v4/#/auth](https://dashboard-01.moengage.com/v4/#/auth) |
| DC-02 | [https://dashboard-02.moengage.com/v4/#/auth](https://dashboard-02.moengage.com/v4/#/auth) |
| DC-03 | [https://dashboard-03.moengage.com/v4/#/auth](https://dashboard-03.moengage.com/v4/#/auth) |
| DC-04 | [https://dashboard-04.moengage.com/v4/#/auth](https://dashboard-04.moengage.com/v4/#/auth) |
| DC-05 | [https://dashboard-05.moengage.com](https://dashboard-05.moengage.com)[v/4/#/auth](https://dashboard-04.moengage.com/v4/#/auth) |
| DC-06 | [https://dashboard-06.moengage.com](https://dashboard-06.moengage.com)[v/4/#/auth](https://dashboard-04.moengage.com/v4/#/auth) |
* Check if you have joined the dashboard. If you see the “Password or email incorrect” error and do not receive the password reset link, confirm whether you have signed up or joined the dashboard.
* Reach out to the admin of your account to check your status.
* If the status is Pending, check your email for a signup message from MoEngage and complete the process. 
* Clear browser cache and cookies. If you are still unable to log in after resetting the password, try clearing your browser cache and cookies:
* Open the Login page.
* Right-click the page and click **Inspect**.
* On the **Applications** tab, go to the **Storage** section.
* Clear the **Local Storage** and **Session Storage**, as shown in the following screenshot. 
# Workspace Settings
Source: https://moengage.com/docs/user-guide/settings/account/general-settings/workspace-settings
Configure general workspace settings in MoEngage, including account details and preferences, from the Settings page on the MoEngage dashboard.
## Configure Workspace Settings
Perform the following steps to configure your workspace settings:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **General settings**. 
2. On the General settings page, enter the following details:
| Section | Field | Description | |
| :- | :- | :- | - |
| **Basic details** | Workspace ID (earlier app id) | This is a unique ID that MoEngage has assigned to your current workspace. It is a read-only field. The developers in your organization need this Workspace ID when:
Integrating the SDKs
Authenticating the API requests
| |
| | Time zone | The time zone is automatically selected based on your current time zone. Select a different time zone if required. Choosing the appropriate time zone ensures that messages or notifications are delivered to users at the right time, based on their local time zone. | |
| **Goal mapping** | Conversion goal | A conversion goal is a specific action you want your users to complete. This could be anything from a product purchase, a sign-up, a content view, or any other key interaction that signifies progress or value within your business objectives. You can define this goal to track how effectively your campaigns drive desired user behavior. After you select a conversion goal, you must select an attribute in the **Revenue attribute** field. You must select the conversion goal and revenue attribute to see insights on conversions. Configured attributes are displayed as conversion metrics on the Key Metrics dashboard. Changes will take up to half an hour to reflect across the workspace. Conversion metrics in the key metrics dashboard will start reflecting after 24 hours. For more information, refer to [Key Metrics](/docs/user-guide/analyze/dashboards/key-metrics). | |
| | Revenue attribute | A revenue attribute is a specific data associated with a user's action that indicates the monetary value generated by that action. For example, if your conversion goal is a "product purchased," the revenue attribute would be "price" to measure the amount of money spent on that purchase. This field is dependent on the **Conversion goal** field. After you select a conversion goal, the revenue attributes related to that goal are available in this list. Goal mapping will help you calculate the lifetime value (LTV) and show you conversion and revenue trends in the [Key Metrics](/docs/user-guide/analyze/dashboards/key-metrics#engagement) dashboard. | |
| | Currency | Setting the right currency is important for providing accurate pricing information, offers, and promotions to customers. Displaying prices in their local currency enhances the customer's experience and eliminates confusion or discrepancies. It also helps build trust and credibility by presenting information in a familiar and understandable format. This field is dependent on the **Revenue attribute** field. After you select a revenue attribute, the available currencies are displayed in this list. | |
| **Workspace classification** | Classify your workspace environment | Specify whether this workspace is used for production or non-production purposes.
Select **Production** if this workspace handles live end-user data and campaigns.
Select **Non-Production** if this workspace is used for UAT, staging, or testing.
| |

3. Click **Save**.
## Workspace Classification
> [!NOTE]
>
> * Workspace classification data will be used to provision an automated release cycle in future where you will be notified at every stage of the rollout.
> * This feature is available only for customers on the Enterprise plan.
Workspace classification allows you to tag your workspace as **Production** or **Non-Production**. This helps MoEngage manage feature rollouts with more control—new features are rolled out to non-production workspaces first, and then to production workspaces at a later stage.
### Set Workspace Classification for an Existing Workspace
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **General settings**.
2. In the **Classify your workspace environment** field, select one of the following options:
* **Production**: Select this option if the workspace handles live end-user data and campaigns.
* **Non-Production**: Select this option if the workspace is used for UAT, staging, or testing purposes.
3. Click **Save**.
### Set Workspace Classification During Onboarding
When you create a new workspace, the onboarding flow includes a mandatory step to set the workspace classification. On the final step, you must select either **Production** or **Non-Production** before the workspace creation can be completed.

> [!NOTE]
>
> * Any existing workspace without a pre-selected classification is treated as **Non-Production** by default.
> * The **Test environment** (from the Live/Test environment toggle) is always marked as **Non-Production** and cannot be changed.
# Portfolio
Source: https://moengage.com/docs/user-guide/settings/account/portfolio/portfolio
Manage multiple apps and websites as individual projects within a single MoEngage workspace using the Portfolio feature for enterprises.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
The *Portfolio* feature enables you to manage multiple applications (apps) and websites as individual **Projects** within a single, unified MoEngage workspace. This feature is designed for enterprises that manage multiple digital properties (for example, different brands or operations in multiple countries) and wish to consolidate their user data and marketing efforts. By bringing all your apps and websites into one workspace, you can create a unified view of your customers, unlocking powerful capabilities for analysis, segmentation, and engagement.
# Use Cases
Adopting a Portfolio structure helps marketers solve several critical business challenges:
* **Unified customer view**: Consolidate user data from all your apps and websites into a single, comprehensive profile for each user, allowing you to understand the complete customer journey.
* **Cross-brand segmentation**: Build powerful audience segments based on user behavior across different projects. For example, you can identify customers active in multiple sub-brands and send a single loyalty campaign rewarding their cross-brand engagement.
* **Cross-project trigger campaigns**: Trigger a campaign from one brand to suggest a similar product when a user abandons their cart on another. For example, you can target buyers from one product line with complementary offers from another (cross-sell), or trigger a reactivation offer when a user becomes inactive in one app but remains active in another (churn prevention).
* **Centralized campaign management**: Manage and deploy Push Notification campaigns to any of your projects from a single dashboard, streamlining your operations.
* **Holistic analytics**: Gain a portfolio-level understanding of user engagement, conversion, and campaign performance across all your digital properties.
* **Controlled user communication**: Manage communication frequency (Frequency Capping) and Do Not Disturb (DND) hours for users across your entire brand portfolio to prevent message fatigue. For example, you can ensure you send only the single most relevant breaking news push from the most appropriate app, avoiding redundant notifications.
# Manage Your Portfolio
A **Project** is a single app or website in your portfolio. Your workspace can support approximately 20 projects.
## Add Project
> [!NOTE]
>
> To add projects to a Portfolio, your role must have the **Setup & manage** permission under **App Configuration**. By default, the Admin and Manager roles have this permission. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles#permissions).
1. On the left navigation menu in the MoEngage UI, click **Settings** > **Account** > **Portfolio**. 
2. On the **Portfolio** page, click **+ Add Project**. 
3. On the **Add a new Project**window, enter the following values:
| Field | Description |
| - | - |
| Project Name | This field specifies the name for the new project. It is mandatory. The project name must be a maximum of 25 alphanumeric characters and begin with a letter. Spaces and special characters are not allowed. |
| Project Icon | This field specifies the icon to represent the project. It is optional. For correct visibility on MoEngage, ensure to upload an image with a minimum resolution of 72x72 pixels. Supported file types are:
PNG
GIF
WebP
ICO
CUR
BMP
|
| Type of Business | This field specifies the business model for the configured project. It is mandatory. The available options are:
Offline / Storefront
Online
|
| Platform(s) | This field specifies the platform(s) for the configured project. It is mandatory and is visible only when the **Type of Business** field value is set to *Online*. Supported platforms are:
Android
iOS
Web
**Note**: The initial platform selection is for representation and initial setup. It does not lock the project to that platform; you can add and configure settings for other platforms later. |
4. Click **Save**.\
You can now see the project details on the **Portfolio** page. 
## Analyze Project
The **Portfolio** page offers a comprehensive overview of all configured projects, enabling detailed analysis of project-related information. You can view the following details:

* **Project Icon**: Specifies the icon associated with this project. A default icon is shown if no custom one is uploaded.
* **Project Name**: Specifies the unique name assigned to this project.
* **Project ID**: Specifies the unique ID automatically generated for the project, used to direct incoming data.
* **Platform(s)**: Specifies the target platform(s) for the project (for example, iOS, web, or Android).
* **Last Updated By**: Displays the date and the user who last modified the project. Project modification permissions are based on the app configuration level. For more information, see [Permission Levels](/docs/user-guide/settings/account/team-management/access-roles).
* **Created By**: Specifies the user who originally created the project and the creation date.
## Edit Project
To edit a project, perform the following steps:
1. Navigate to the **Portfolio**page, search for the relevant project row.
2. Click the Ellipsis ( ) icon against the preferred entry, and then click **Edit**.
3. On the **Add a New Project**window, make the required changes.
4. Click **Save**.

> [!NOTE]
>
> * Note the following points regarding project modifications:
> * The **Project Icon** is editable at any time.
> * You can add new platforms, but you cannot remove existing platforms.
> * The MoEngage support team handles project archival and deletion to ensure data integrity. For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Impact of Portfolio On
The *Portfolio* feature changes how you interact with key areas of MoEngage.
## Data and User Profiles
The Portfolio feature centralizes your data and user profiles, allowing you to manage attributes and events at both the project and portfolio levels. This feature has the following impact on data ingestion and management in MoEngage:
* **Portfolio and project-specific attributes**: MoEngage enables project-level tracking of custom, standard user properties, and events.
* Standard attributes such as basic details, including First name, Last name, Mobile number, and other such standard attributes, are tracked as portfolio-level standard attributes.
* Custom user properties can be tracked at both the project and portfolio levels.
* Standard and custom events are tracked at the project level.\
To understand user properties tracked at the project and portfolio level, refer to [Derived User Properties Behaviour](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#user-profile).
* **User profile view**: For users who exist in more than one project, a drop-down menu appears on their profile page, allowing you to view their attributes and activity for each specific project.
* **Data management**: The Data Management section provides a portfolio-level overview of unique events and user properties. This allows you to manage data across projects, with a default limit of 1024 unique events and 1024 unique user properties for the entire portfolio.
* **Data ingestion**: You can ingest data into the portfolio using Data APIs and SDKs.
For more information, refer to [Portfolio: Data Ingestion and Management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#data-ingestion)
## Segmentation
The segmentation tool allows you to build rules that span multiple projects. You can combine behaviors from different apps and websites to create highly specific audiences for cross-targeting.
* **Cross-project rules**: When building a segment, a *Project* drop-down list appears for each rule, allowing you to filter users based on behavior in one project and attributes in another.
* **Portfolio-level filtering**: For user events, you can select *Portfolio* to find users who performed an action (like *Purchase*) in any of your projects, creating a broad "OR" condition.
* **Reachability calculation**: It is important to understand that the reachability count shown in the segment builder is a **global** count (users reachable on at least one project). When you use that segment in a campaign, the count becomes **project-specific**, showing only users reachable for the single project you are sending the campaign to.
For more information, refer to [Segmentation in a Multi-Project Portfolio](/docs/user-guide/segment/advanced-concepts/segmentation-in-a-multi-project-portfolio#overview).
## Email Settings
The Portfolio feature centralizes your settings to ensure brand-consistent and contextually relevant Email campaigns through the following capabilities:
* **Project-specific configurations**: Use the Project drop-down list to select and apply unique settings to each individual project within your portfolio. This allows you to maintain independent configurations for your Overview, Sender Configuration, General Settings, Subscription Management, Font Management, and PII Tokenization.
* **Contextual personalization**: Maintain brand consistency by automatically filtering available user properties during campaign creation to only show data relevant to the sending project.
* **Project-level reachability**: Each user's Email subscription status is tracked separately for each project, so a user can be reachable for one project and unreachable for another.
> [!WARNING]
>
> If your workspace ran Email campaigns with the *Portfolio* feature before project-level Email was enabled, you cannot edit or duplicate those existing campaigns. Project-level reachability and project-level Email settings take effect as soon as you edit an existing campaign or create a new one, which can render the existing campaign's configuration invalid. Create a new Email campaign under the relevant project instead.
For more information, refer to [Portfolio for Email Campaigns](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/portfolio-for-email-campaigns#overview).
## Push Settings
The Portfolio feature centralizes key configurations to ensure your Push campaigns are always brand-consistent and contextually relevant through the following capabilities:
* **Project-specific configurations**: Apply unique settings for Mobile App Push, Web Push, and Push Previews to each project individually within your portfolio.
* **Contextual personalization**: Maintain brand consistency by automatically filtering available user properties during campaign creation to only show data relevant to the sending project.
For more information, refer to [Portfolio for Push Campaigns](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/portfolio-for-push-campaigns#overview).
## In-app Messaging Settings
The Portfolio feature centralizes configurations to ensure your In-app campaigns are delivered in the correct application context while maintaining brand consistency through the following capabilities:
* **Project-specific delivery**: Control which mobile application hosts your campaign by selecting a specific project and platform (iOS/Android) during creation.
* **Contextual personalization**: Maintain brand integrity by automatically filtering user properties to show only those relevant to the target project or global data.
For more information, refer to [Portfolio for In-app Campaigns](/docs/user-guide/campaigns-and-channels/in-app-message/getting-started-with-in-app-message/portfolio-for-in-app-campaigns#overview).
## On-site Messaging Settings
The Portfolio feature centralizes configurations to ensure your web overlays are domain-accurate and contextually relevant through the following capabilities:
* **Project-specific targeting**: Ensure your OSM campaigns appear only on the correct website by selecting the specific project and web platform for each campaign.
* **Contextual personalization**: Prevent cross-brand data leakage by automatically filtering the personalization list to show only attributes from the sending project and global attributes.
For more information, refer to [Portfolio for OSM Campaigns](/docs/user-guide/campaigns-and-channels/on-site-message/getting-started-with-on-site-message/portfolio-for-on-site-messaging#overview).
## Campaigns
The Portfolio feature unifies customer data across multiple projects to enhance how you segment, personalize, and analyze campaigns through the following key capabilities:
> [!NOTE]
>
> The *Portfolio* feature is not supported for campaigns created via the Push API. Flows that use dynamic conditions are also not supported.
* **Project-specific targeting**: Control which project sends a campaign to ensure all branding and deep links are contextually correct for that specific brand. This is supported for Push, Email, In-app, and OSM channels.
* **Cross-project segmentation**: Create precise audiences by building rules that combine user behaviors and attributes from any of your associated projects.
* **Cross-project trigger campaigns**: Trigger a campaign from one project based on a user's real-time actions in another, enabling automated cross-promotional strategies. This is not applicable in In-app and OSM channels.
* **Individual project analytics**: Analyze and compare push notification opt-in rates for each project separately using unique reachability attributes. This is only supported for the Push channel.
* **Aggregated reachability**: Determine a user’s overall reachability based on their status across all projects. A user is considered reachable if they are opted-in to notifications from at least one project.
For more information on the channel-specific support matrix of the *Portfolio* feature, refer to [Supported Features by Channel](/docs/user-guide/settings/account/portfolio/portfolio#supported-features-by-channel).
## Global Frequency Capping
The *Portfolio* feature enables you to manage communication frequency across your entire brand portfolio. This prevents message fatigue by setting a *Global Frequency Capping* that limits the total number of communications a user receives from all your projects.
* You can set a master frequency capping at the portfolio level. This limit is enforced on a per-user basis and applies to the total number of communications sent from all projects within the workspace.\
For example, if a global capping is set to five communications, a user in three different projects will receive a maximum of five communications combined across all three brands.
* While the global capping controls the overall volume, *tag-based frequency capping* allows for more granular, project-specific control.\
For example, to limit messages from a specific project to three, you can:
* Add a unique tag to all campaigns running for that specific Project.
* Set a frequency capping rule that limits communications with that specific tag to three.
For more information, refer to [Frequency Capping](/docs/user-guide/settings/channels/delivery-controls/frequency-capping#overview).
# Supported Features by Channel
The availability of key Portfolio features, such as reachability and cross-project triggers, varies by communication channel. The following table lists the features supported for each channel.\
**_\*Not Supported: Portfolio user interface elements are unavailable for these channels on the workspace._**
| Channel | Reachability Level | Cross-Project Segmentation | Cross-Project Event Triggers |
| - | - | - | - |
| **Push** | Project | Supported | Supported |
| **Email** | Project | Supported | Supported |
| **SMS & RCS** | Portfolio | Supported | Supported |
| **WhatsApp** | Portfolio | Supported | Supported |
| **In-App Messaging** | Not Applicable | Supported | Not Applicable |
| **On-site Messaging** | Not Applicable | Supported | Not Applicable |
| **Cards** | Not Applicable | Supported | \*Not Supported |
| **Connectors** | Not Applicable | Supported | Supported |
| **Facebook Audience** | Not Applicable | \*Not Supported | \*Not Supported |
| **Google Ads Audience** | Not Applicable | \*Not Supported | \*Not Supported |
| **Inform** | \*Not Supported | \*Not Supported | \*Not Supported |
| **Flows** | Not Applicable | \*Not Supported | \*Not Supported |
> [!NOTE]
>
> * **Project-level reachability**: A user's opt-in status is tracked separately for each project.
> * **Portfolio-level reachability**: A user's opt-in status applies to all projects in the portfolio. There is no project-specific opt-in status.
> * **Not Applicable**: These channels do not have a concept of opt-in reachability in the same way as Push or Email.
> * **\*Not Supported**: The dashboard does not provide portfolio UI elements for these channels.
> * To use cross-project segmentation, you can:
> * Use a custom segment to target your campaign across projects.
> * Create the segment using the project-level user property, and for event-based segmentation, select the *project name* event property specifying the project's name as the value.
> * You can use cross-project event triggers by selecting the *project name* event property, specifying the project's name as the value.
> [!NOTE]
>
> The *Portfolio* feature does not support the Web Personalization channel, which is why it is not listed in the preceding table.
# FAQs
> [accordion] If the same person uses two of my apps, will MoEngage treat them as one unified user?
>
> Yes. The primary goal of the Portfolio feature is to consolidate data from all your apps and websites (Projects) into **a single, comprehensive profile for each user**, giving you a unified view of their entire journey across your brands.
> [accordion] How are user details and actions (attributes and events) handled across different projects?
>
> Standard details like "First Name" and "Mobile Number" are tracked at the **portfolio level** (one value for the user). Custom attributes can be set at either the portfolio or project level. However, all user actions (events) are tracked at the **project level**, meaning you always know which app or website an action occurred on.
> [accordion] I created a powerful segment using data from multiple projects. Why did the audience size drop when I tried to use it in a campaign?
>
> This is the expected behavior. The segment builder shows you a **global count** of users who meet your criteria and are reachable on at least one of your projects. When you use that segment in a campaign for a specific project, the count becomes **project-specific**, showing only the users who are reachable for that particular project.
> [accordion] Are there any limits or permanent choices I should be aware of when setting up my Portfolio?
>
> Yes, there are two key things to know:
>
> * A workspace can only support approximately **20 projects**.
> * When adding platforms (like iOS or Android) to a project, that choice is permanent. **You cannot remove a platform** after it has been added.
> [accordion] Who can add projects to a Portfolio?
>
> Only users whose role has the **Setup & manage** permission under **App Configuration** can add projects to a Portfolio. By default, the Admin and Manager roles have this permission. If you don't have it, contact your account admin. Admins can assign it in **Settings** > **Account** > **Team Management** > **Roles**. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles#permissions).
> [accordion] How do I delete a Project I no longer need?
>
> You cannot delete or archive a project yourself from the dashboard. For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team to ensure data integrity.
# Related Articles
* [Portfolio: Data Ingestion and Management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management)
* [Segmentation in a Multi-Project Portfolio](/docs/user-guide/segment/advanced-concepts/segmentation-in-a-multi-project-portfolio#overview)
* [Portfolio for Email Campaigns](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/portfolio-for-email-campaigns#overview)
* [Portfolio for Push Campaigns](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/portfolio-for-push-campaigns#overview)
* [Portfolio for In-app Campaigns](/docs/user-guide/campaigns-and-channels/in-app-message/getting-started-with-in-app-message/portfolio-for-in-app-campaigns#overview)
* [Portfolio for OSM Campaigns](/docs/user-guide/campaigns-and-channels/on-site-message/getting-started-with-on-site-message/portfolio-for-on-site-messaging#overview)
* [Create an Event-Triggered Campaign](/docs/user-guide/campaigns-and-channels/getting-started/triggers/event/create-an-event-triggered-campaign#overview)
# 2-Step Verification or Two-Factor Authentication (2FA)
Source: https://moengage.com/docs/user-guide/settings/account/security/2-step-verification-or-two-factor-authentication-2fa
Enable two-factor authentication (2FA) in MoEngage to add an extra layer of security for all user logins with app-based verification codes.
# Overview
2-step verification or two-factor authentication (2FA) is a security measure that requires two different verification steps to access an account or system, rather than just a password. This adds an extra layer of protection against unauthorized access. 2FA requires the user to prove their identity in two separate ways, often combining "something they know" (like a password) with "something they have" (like a phone).
## Advantages of 2-Step Verification
2-step verification provides you with the following advantages:
* **Enhanced security**: 2-step verification significantly strengthens account security, making it significantly harder for hackers to gain unauthorized access, even if they somehow obtain a password.
* **Reduced risk of fraud and data breaches**: By requiring a second factor, 2-step verification helps prevent unauthorized access to sensitive information, reducing the risk of fraud and data breaches.
* **Compliance with regulations**: Many industries and regulations now mandate 2-step verification to protect sensitive data, ensuring businesses meet compliance requirements like those for cybersecurity insurance and financial institutions.
* **Increased customer trust**: Implementing 2-step verification demonstrates a commitment to security, building customer trust and confidence in the organization's ability to protect their information.
* **Reduced password fatigue**: 2-step verification can help alleviate password fatigue by allowing users to use simpler, easier-to-remember passwords without compromising security.
# 2-Step Verification Implementation in MoEngage
MoEngage allows you to secure your MoEngage account (workspace) with 2-step verification. You can control users' access to your workspace with the following two factors:
* Email ID and password.
* Verification code (generated by the authentication app on the device). MoEngage supports 2-step verification through apps such as Google Authenticator, Twilio Authy, etc.
You can implement 2-step verification at:
* **Workspace level**: Administrators can manage 2-step verification for all users within a workspace.
> [!NOTE]
>
> When an Admin [creates a new workspace](/docs/user-guide/getting-started/initial-setup/sign-up-with-moengage-or-create-a-new-account-in-moengage), MoEngage enables 2-step verification by default. They can enable and disable it for all team members' accounts in that workspace.
> [!WARNING]
>
> For security reasons, 2-step verification is mandatory and cannot be disabled for any workspace whose [login method](/docs/user-guide/settings/account/security/set-up-the-login-method) is set to **Password or Google sign in** or **Google Sign In only**. Only workspaces that use **Single Sign On (SSO) only** can have 2-step verification disabled.
* **User level**: If the workspace uses **Single Sign On (SSO) only** and the Admin has not enabled 2-step verification for all users at the workspace level, all users can manage 2-step verification for their respective accounts in **My profile**. For more information, refer to [Manage Your Profile](/docs/user-guide/getting-started/initial-setup/manage-your-profile).
# Disable 2-Step Verification at Workspace Level
MoEngage enables 2-step verification for a new workspace by default. To disable 2-step verification at the workspace level, perform the following steps:
> [!WARNING]
>
> You can disable 2-step verification only if the workspace's [login method](/docs/user-guide/settings/account/security/set-up-the-login-method) is set to **Single Sign On (SSO) only**. For security reasons, it's mandatory and can't be disabled for workspaces that use **Password or Google sign in** or **Google Sign In only**.
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.

2. On the Security page, click the **2-Step verification** tab.
> [!NOTE]
>
> The **2-Step Verification** tab is available only to Admins.
3. In the **2-Step verification** section, under **Enable 2- Step Verification for your team-mates** **on this workspace**, turn the **Disable** toggle on. \
The Disable pop-up window appears, prompting you to review the instructions carefully.
4. Select the **Send email to your team** check box.
5. Click **Confirm**.

The 2-step verification is now successfully disabled for all users within that workspace. You can also click the link below the **Enable** toggle to verify if your teammates have set up their devices. You can also download a CSV file that lists the status of 2-step verification for all team members' accounts.

# Enable 2-Step Verification at Workspace Level
When you create a new workspace, MoEngage enables 2-step verification for that workspace by default. If you disabled it at the workspace level and want to enable it again, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.

2. On the Security page, click the **2-Step verification** tab.
> [!NOTE]
>
> The **2-Step Verification** tab is available only to Admins.
3. In the **2-Step verification** section, under **Enable 2-Step Verification for your teammates on this workspace**, turn the **Enable** toggle on. \
The Enable pop-up window appears, prompting you to review the instructions carefully
4. Select the **Send email to your team** check box.
5. Click **Confirm**.

The 2-step verification is now successfully enabled for all users in the current workspace
6. You can also click the **report**link below the **Disable** toggle to verify if your teammates have set up their devices. You can also download a CSV file that lists the status of 2-step verification for all team members' accounts.

After you enable 2-step verification for your workspace, all users will be automatically logged out of the MoEngage dashboard. When they log in to the MoEngage dashboard again, they must set up 2-step verification on their device. For more information, refer to [Set Up 2-Step Verification on Your Device](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#set-up-2-step-verification-on-your-device).
# FAQs
**Q. I am receiving the following code "The code you entered is invalid. Ensure the system time on your authenticator device matches the time on your login device and try again."**
**A.** Please ensure that both devices have the same system time.
For a permanent resolution, install the Authenticator Extension on the same device you are using to log in to MoEngage. You can download and install it [here](https://chromewebstore.google.com/detail/authenticator/bhghoamapcdpbohphigoooaddinpkbai).
This will align the system times and prevent invalid codes in the future. If the issue persists, [contact support](/docs/user-guide/contact-support) for further assistance.
# API Firewall
Source: https://moengage.com/docs/user-guide/settings/account/security/api-firewall
Restrict API access by IP address with category-based whitelist rules, publish controls, and safeguards to prevent lockouts.
The API Firewall gives you control over which IP addresses can send requests to your MoEngage APIs. Even if an API key is compromised or stolen, the API Firewall rejects requests from any IP address that is not on your whitelist. Each rule whitelists one or more API categories, so you can restrict access to specific parts of your API surface, without affecting categories you haven't configured.
To create and scope the API keys these rules apply to, see [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard). Before you publish your first rule, collect the IP addresses of every partner and server that calls MoEngage. For more information, refer to [Whitelist Partners and Servers](/docs/user-guide/settings/account/security/whitelist-partners-and-servers).
> [!NOTE]
>
> The API Firewall applies to the following API categories: **Data**, **Segmentation**, **Campaigns**, **Partner Integration**, and **Content**. Every rule must whitelist at least one category.
## How It Works
By default, the API Firewall is inactive. Until you publish a rule that covers a category, MoEngage accepts requests to that category's APIs from any IP address. Enforcement is per category — publishing a rule protects only the categories that rule covers, and leaves every other category open.
Each rule has two independent properties: the categories it whitelists, and its publish status. Only published rules affect traffic — saving a rule never enforces it by itself.
| Rule status | Effect |
| - | - |
| **Unpublished** | Default status for new and edited rules. Saved, but not enforced. |
| **Published** | An explicit, separate action. MoEngage starts enforcing the IP restriction for every category the rule covers. Requests from IP addresses not in any published rule covering that category receive a `403` response. |
## API Categories
The API Firewall organizes API endpoints into five fixed categories. You can't rename this list or add to it. When you create or edit a rule, select every category the rule should whitelist.
### Data
| Sub-category | API Names | Description |
| - | - | - |
| User Management | [Track User](/docs/api/user/track-user), [Get User](/docs/api/user/get-user), [Merge Users](/docs/api/user/merge-users), [Delete Users](/docs/api/user/delete-users) | Create, update, retrieve, merge, and delete user profiles. |
| Event Tracking | [Track Event](/docs/api/event/track-event) | Track a custom user event. |
| Bulk Import | [Bulk Import Users & Events](/docs/api/bulk/bulk-import-users-and-events) | Import user and event data in bulk. |
| Device Management | [Track Device](/docs/api/device/track-device), [Device Opt-out](/docs/api/device/device-opt-out) | Create or update a user device, and opt a device out of notifications. |
| GDPR / CCPA | [Submit GDPR / CCPA Data Request](/docs/api/gdpr/submit-a-gdpr-ccpa-data-request) | Submit a data deletion or portability request. |
| Analytics | [List Dashboards](/docs/api/dashboards/list-dashboards), [Get Dashboard Charts](/docs/api/dashboards/get-dashboard-charts), [Get Chart Data](/docs/api/dashboards/get-chart-data) | List dashboards, and retrieve dashboard and chart data. |
### Segmentation
| Sub-category | API Names | Description |
| - | - | - |
| File Segments | [Create File Segment](/docs/api/file-segments/create-file-segment), [Add Users to File Segment](/docs/api/file-segments/add-users-to-file-segment), [Remove Users from File Segment](/docs/api/file-segments/remove-users-from-file-segment), [Replace Users in File Segment](/docs/api/file-segments/replace-users-from-file-segment) | Create a file-based segment, and add, remove, or replace users in it. |
| Filter Segments | [List Segments](/docs/api/filter-segments/list-segments), [Create Filter Segment](/docs/api/filter-segments/create-filter-segment), [Get Segment by ID](/docs/api/filter-segments/get-segment-by-id), [Update Filter Segment](/docs/api/filter-segments/update-filter-segment) | List, create, retrieve, and update filter-based segments. |
| Manage Segments | [Archive Segment](/docs/api/manage-segments/archive-segment), [Unarchive Segment](/docs/api/manage-segments/unarchive-segment) | Archive or unarchive a custom segment. |
### Campaigns
| Sub-category | API Names | Description |
| - | - | - |
| Campaign Management | [Create Campaign](/docs/api/create-campaigns/create-campaign), [Update Campaign](/docs/api/update-campaigns/update-campaign-v1-legacy), [Change Campaign Status](/docs/api/update-campaigns/change-campaign-status), [Update Global Control Group](/docs/api/update-campaigns/update-global-control-group), [Search Campaigns](/docs/api/get-campaign-details/search-campaigns), [Get Campaign Meta](/docs/api/get-campaign-details/get-campaign-meta-v1-legacy), [Get Child Campaigns](/docs/api/get-campaign-details/get-child-campaigns) | Create, update, search, and change the status of Push and Email campaigns, and manage the global control group. |
| Testing | [Test Campaign](/docs/api/test-campaigns/test-campaign), [Personalized Preview](/docs/api/test-campaigns/personalized-preview) | Send a test version of a campaign and preview personalized campaign content for a user. |
| Stats & Reports | [Get Campaign Stats](/docs/api/stats/get-campaign-stats), [Download Campaign Report](/docs/api/campaign-reports/download-campaign-report) | Retrieve campaign performance statistics and download campaign report files. |
| Business Events | [Create Business Event](/docs/api/business-events/create-business-event), [Trigger Business Event (Legacy)](/docs/api/business-events/trigger-business-event), [Search Business Events (Legacy)](/docs/api/business-events/search-business-events), [Trigger Business Event (V5)](/docs/api/business-events/trigger-business-event-v5), [List Business Events](/docs/api/business-events/list-business-events), [Search Business Events (V5)](/docs/api/business-events/search-business-events-v5) | Define, trigger, and search business events that power automated campaigns. |
| Subscriptions | [Bulk Resubscribe Users](/docs/api/resubscribe/bulk-resubscribe-users), [Update User Email Opt-in Preferences](/docs/api/opt-in-management/update-user-email-opt-in-preferences), [Get Subscription Preferences](/docs/api/subscription-preferences/get-subscription-preferences), [Update Subscription Preferences](/docs/api/subscription-preferences/update-subscription-preferences), [Bulk Update Subscription Preferences](/docs/api/subscription-preferences/bulk-update-subscription-preferences), [Get Subscription Categories (V5)](/docs/api/subscription-categories/get-subscription-categories-v5), [Get Subscription Preferences (V5)](/docs/api/subscription-preferences/get-subscription-preferences-v5), [Update Subscription Preferences (V5)](/docs/api/subscription-preferences/update-subscription-preferences-v5) | Manage a user's email opt-in status and subscription category preferences, including bulk updates. |
| Push | [Send Push Notification (V5)](/docs/api/push/push-api), [Send Push Notification (v2.1, Legacy)](/docs/api/push/push-api-v2-1-legacy) | Send a transactional push notification to Android, iOS, Web, or Windows. |
| Cards | [Fetch Cards for User](/docs/api/cards/fetch-cards-for-user), [Delete Cards for User](/docs/api/cards/delete-cards-for-user) | Retrieve or delete App Inbox cards for a user. |
| Inform | [Send Transactional Alert](/docs/api/transactional-alerts/send-transactional-alert) | Send a transactional alert by SMS, email, or push. |
| Live Activities | [Start Broadcast Live Activity](/docs/api/live-activities/start-broadcast-live-activity), [Update Broadcast Live Activity](/docs/api/live-activities/update-broadcast-live-activity), [End Broadcast Live Activity](/docs/api/live-activities/end-broadcast-live-activity) | Start, update, and end an iOS Live Activity. |
| Personalize | [Fetch Experience](/docs/api/experiences/fetch-experience), [Fetch Experience Metadata](/docs/api/experiences/fetch-experience-metadata), [Track Experience Events](/docs/api/events/track-experience-events) | Retrieve personalized experiences and their metadata, and track user interactions with them. |
| Message Archival | [View Archived Message](/docs/api/message-archival/view-archived-message) | Retrieve and view archived messages for a user. |
| Flows | [Flows Search](/docs/api/flows/search-flows), [Get Specific Flow](/docs/api/flows/get-a-single-flow), [Get Specific Version](/docs/api/flows/get-a-specific-version-of-a-flow), [Flow Status Update](/docs/api/flows/update-flow-status) | Search flows, retrieve a flow or a specific flow version, and update flow status. |
> [!NOTE]
>
> The API Firewall doesn't support the [Send Push Notification (v2, Legacy)](/docs/api/push/push-api-v2-legacy) (v2) API, and IP whitelisting rules aren't enforced on it. To restrict push requests by IP address, use [Send Push Notification (V5)](/docs/api/push/push-api). The API Firewall supports the [Send Transactional Alert](/docs/api/transactional-alerts/send-transactional-alert) (Inform) API, except for a small number of accounts that are exempt. If you think your account is exempt, contact your MoEngage Customer Success Manager (CSM) or the Support team.
### Partner Integration
| Sub-category | API Names | Description |
| - | - | - |
| Cohort Sync | [Sync Cohort Members](/docs/api/cohort-sync/sync-cohort-members) | Sync a cohort audience from a third-party analytics tool. |
| File Import | [Trigger File Imports](/docs/api/file-import/trigger-file-imports), [Get Import Details](/docs/api/file-import/import-details), [Import File Run History](/docs/api/file-import/import-file-run-history) | Trigger a partner-facing file import, and check its status and run history. |
| App Install | [Track App Install](/docs/api/tracking/track-app-install) | Retrieve or track app install information. |
| Utilities | [Test Connection API](/docs/api/utilities/test-connection-api) | Validate API credentials and test the connection to your workspace. |
### Content
| Sub-category | API Names | Description |
| - | - | - |
| In-App Templates | [Create In-App Template](/docs/api/in-app-templates/create-in-app-template), [Update In-App Template](/docs/api/in-app-templates/update-in-app-template), [Search In-App Templates](/docs/api/in-app-templates/search-in-app-templates) | Create, update, and search In-App message templates. |
| OSM Templates | [Create OSM Template](/docs/api/osm-templates/create-osm-template), [Update OSM Template](/docs/api/osm-templates/update-osm-template), [Search OSM Templates](/docs/api/osm-templates/search-osm-templates) | Create, update, and search On-Site Message templates. |
| SMS Templates | [Create SMS Template](/docs/api/sms-templates/create-sms-template), [Update SMS Template](/docs/api/sms-templates/update-sms-template), [Search SMS Templates](/docs/api/sms-templates/search-sms-templates) | Create, update, and search SMS templates. |
| Email Templates | [Create Email Template (V1)](/docs/api/email-templates/create-email-template-v1), [Get All Email Templates](/docs/api/email-templates/get-all-templates), [Get Specific Email Template](/docs/api/email-templates/get-specific-template), [Update Email Template (V1)](/docs/api/email-templates/update-specific-template), [Search Email Template](/docs/api/email-templates/search-email-template), [Create Email Template (V2)](/docs/api/email-templates/create-email-template-v2), [Update Email Template (V2)](/docs/api/email-templates/update-email-template), [Bulk Create/Update Email Templates](/docs/api/email-templates/bulk-createupdate-templates) | Create, retrieve, update, and search email templates. |
| Push Templates | [Create Push Template](/docs/api/templates/create-push-template), [Update Push Template](/docs/api/templates/update-push-template), [Search Push Templates](/docs/api/templates/search-for-push-templates) | Create, update, and search push notification templates. |
| Content Blocks | [Create Content Block](/docs/api/content-blocks/create-content-block), [Update Content Block](/docs/api/content-blocks/update-content-block), [Get Specific Content Blocks](/docs/api/content-blocks/get-specific-content-blocks), [Search Content Blocks](/docs/api/content-blocks/search-content-blocks) | Create, update, retrieve, and search reusable content blocks. |
| Recommendations | [Fetch All Recommendations](/docs/api/recommendations/fetch-all-recommendations), [Fetch Recommendation Details](/docs/api/recommendations/fetch-recommendation-details), [Fetch Recommendation Results](/docs/api/recommendations/fetch-recommendation-results) | Fetch product or content recommendation metadata and results for a user. |
| Coupon Lists | [Create Coupon List](/docs/api/coupon-lists/create-a-coupon-list), [Fetch All Coupon Lists](/docs/api/coupon-lists/fetch-all-coupon-lists), [Fetch Coupon List Details](/docs/api/coupon-lists/fetch-coupon-list-details), [Update Coupon List](/docs/api/coupon-lists/update-a-coupon-list), [Activate Coupon List](/docs/api/coupon-lists/activate-coupon-list), [Archive Coupon List](/docs/api/coupon-lists/archive-a-coupon-list) | Create, retrieve, update, activate, and archive coupon lists. |
| Coupon Files | [Upload Coupon File](/docs/api/coupon-files/upload-a-coupon-file-to-the-coupon-list), [Fetch All Coupon Files](/docs/api/coupon-files/fetch-all-coupon-files-from-coupon-list), [Delete Coupon File](/docs/api/coupon-files/delete-a-coupon-file-from-the-coupon-list) | Upload, retrieve, and delete coupon files within a coupon list. |
| Coupon Reports | [Generate Usage Report](/docs/api/reports/generate-usage-report) | Generate the usage report for a coupon list. |
| Catalog | [Create Catalog](/docs/api/catalog/create-catalog), [Add Catalog Attributes](/docs/api/catalog/add-catalog-attributes), [Add Items (Ingest)](/docs/api/items/add-items), [Get Items](/docs/api/items/get-items), [Update Items](/docs/api/items/update-items), [Delete Items](/docs/api/items/delete-items) | Create a catalog, and add, retrieve, update, or delete catalog attributes and items. |
| Offerings | [List Offerings](/docs/api/public-offerings/list-offerings), [Create Offering](/docs/api/public-offerings/create-offering), [Update Offering](/docs/api/public-offerings/update-offering), [Get Offering](/docs/api/public-offerings/get-offering), [List Offer Templates](/docs/api/public-offerings/list-offer-templates) | List, create, update, and retrieve offerings, and list templates available for Offer Decisioning. |
## Impact on Partner Integrations
Any integration where MoEngage receives calls from a partner's infrastructure is affected. If you publish rules for a category that one of these integrations uses, add the partner's IP addresses to those rules. Otherwise, MoEngage rejects the partner's requests with a `403` response. For instructions on identifying the partners that call MoEngage and collecting their IP addresses, refer to [Whitelist Partners and Servers](/docs/user-guide/settings/account/security/whitelist-partners-and-servers). The following partner integrations are affected:
| Partner name | Is IP whitelisting needed? | Scope | Action needed |
| - | - | - | - |
| [Salesforce Sales CRM](/docs/partner-guide/data-and-analytics/crm/salesforce-crm-native/overview) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Hightouch](/docs/partner-guide/data-and-analytics/cdps/hightouch) | Yes | Data | Request partner IP ranges, add to whitelist |
| [RudderStack](/docs/partner-guide/data-and-analytics/cdps/rudderstack/moengage-destination) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Salla](/docs/partner-guide/commerce-and-loyalty/e-commerce/salla) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Zapier](/docs/partner-guide/data-and-analytics/workflow-automation/zapier/overview) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Amplitude (event sync)](/docs/partner-guide/data-and-analytics/analytics/amplitude/amplitude-event-streaming) | Yes | Data | Request partner IP ranges, add to whitelist |
| [AppsFlyer Audiences](/docs/partner-guide/data-and-analytics/install-attribution/appsflyer/appsflyer-audience) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Microsoft Dynamics 365](/docs/partner-guide/data-and-analytics/crm/microsoft-dynamics-365-sales/microsoft-dynamics-365-sales) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Mixpanel](/docs/partner-guide/data-and-analytics/analytics/mixpanel) | Yes | Cohort APIs | Request partner IP ranges, add to whitelist |
| [Amplitude](/docs/partner-guide/data-and-analytics/analytics/amplitude/amplitude-audiences) | Yes | Cohort APIs | Request partner IP ranges, add to whitelist |
| [Salesforce Marketing Cloud](/docs/partner-guide/message-orchestration/marketing-cloud/salesforce-marketing-cloud-sfmc/overview) | Yes | Data, Campaigns | Request partner IP ranges, add to whitelist |
| [AEM](/docs/partner-guide/personalize-and-optimize/dynamic-content/adobe-experience-manager/syncing-experience-fragments-as-content-blocks) | Yes | Content | Request partner IP ranges, add to whitelist |
| [Segment](/docs/partner-guide/data-and-analytics/cdps/twillio-segment/getting-started/overview) | No | – | – |
| [mParticle](/docs/partner-guide/data-and-analytics/cdps/mparticle/getting-started/overview) | No | – | – |
| [Adobe RT CDP](/docs/partner-guide/data-and-analytics/cdps/adobe-real-time-cdp/overview) | No | – | – |
| Connected sources (Punchh, RevenueCat, Unbounce, etc.) | No | – | – |
> [!NOTE]
>
> If you use Connected Segments (earlier called Outbound Segment Sync), Streams, or Connector Campaigns to send data to a MoEngage workspace, add MoEngage's IP addresses to that workspace's rules. For the list of IP addresses, refer to [IP Whitelisting in MoEngage](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage).
## Use Cases
* **Protect workspaces with large teams:** Organizations with many API users can restrict access to whitelisted server IP addresses. Even if a team member leaves and takes an API key, requests from unauthorized IP addresses are rejected.
* **Protect against exposed credentials:** When an API key is exposed in a public repository, the API Firewall rejects requests from IP addresses not on your whitelist, even when valid credentials are presented.
* **Isolate non-production environments:** Create workspace-specific whitelist rules for internal automation networks or QA testing tools in staging workspaces, keeping test traffic separate from production data.
* **Scope protection to specific categories:** Enforce IP restrictions on a single sensitive category, such as Partner Integration or Segmentation, while leaving other categories not enforced during a phased rollout or migration.
## Navigate to the API Firewall
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.
2. On the **Security** page, select the **API firewall** tab.
3. On the **API firewall** page, select **Enable API Firewall**. The [Add API Firewall Rule](#add-new-api-firewall-rule) dialog box opens.

> [!NOTE]
>
> You must be an Admin for your MoEngage workspace to add API Firewall rules. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
## Create and Publish API Firewall Rules
> [!NOTE]
>
> Before configuring rules, obtain a complete list of static IP addresses and CIDR blocks used by your servers from your DevOps or Security team. For instructions on identifying every partner and server that calls MoEngage and collecting their IP addresses, refer to [Whitelist Partners and Servers](/docs/user-guide/settings/account/security/whitelist-partners-and-servers).
### Add New API Firewall Rule
1. In the **Add API firewall rule** dialog box, enter the following details:
* **Rule name:** Enter a descriptive name (for example, "Internal Corporate Network" or "AWS Production Server").
* **Whitelist categories:** Select one or more API categories this rule whitelists — **Data**, **Segmentation**, **Campaigns**, **Partner Integration**, or **Content**. You must select at least one category.
* **Condition:** Select the IP address type from the drop-down menu:
| Condition | Description |
| - | - |
| **Single IPv4** | Allows a specific IPv4 address (for example, `192.168.1.1`). |
| **Single IPv6** | Allows a specific IPv6 address. |
| **CIDR Range IPv4** | Allows a block of IPv4 addresses defined by a network address and subnet mask in CIDR notation (for example, `192.168.0.0/24`). Use this when your IP block aligns to a CIDR boundary. |
| **CIDR Range IPv6** | Allows a block of IPv6 addresses in CIDR notation. |
| **IPv4 Range** | Allows a contiguous range of IPv4 addresses specified by a start and end address (for example, `192.168.1.0 - 192.168.1.255`). Use this when your IP block does not align to a CIDR boundary. |
* **Value:** Enter the IP address, CIDR range, or start and end IP addresses in the format shown in the example.
> [!WARNING]
>
> **First rule for this category**
>
> This warning appears inline as soon as you select a category that has no other rules — published or unpublished — covering it. It alerts you that publishing this rule will enforce IP restrictions for that category within approximately 15 minutes, blocking all IPs except those in your whitelist, and advises verifying your current IP and all server IPs are included to prevent accidental lockout. It updates live as you change your category selection, so you see the consequence before you save.
>
> 
2. Select **Add rule**. After you save your first rule, MoEngage redirects you to the API firewall list page. To add more rules, select **+ Add rule** on the top right of the list page.

> [!NOTE]
>
> **Rule saved as Unpublished**
>
> Your saved rule is recorded but not yet enforced. No traffic is currently restricted for the categories it covers. Add all required server IPs before publishing to ensure uninterrupted access for your authorized systems. Once published, MoEngage accepts requests to the categories this rule covers exclusively from whitelisted IP addresses and returns a `403` error for all others.
### Publish Rules
Publishing a rule makes it active and enforces the IP restriction for every category it covers. You can publish all rules at once or publish a subset of rules selectively.
1. Select the checkbox next to each unpublished rule you want to activate.
2. Select **Publish** at the bottom of the screen.
3. In the confirmation dialog box, review the notice — including any first rule for category warnings — and then select **Publish** to confirm.
The rule status changes to **Published**. MoEngage now accepts requests to every category this rule covers only from IP addresses that match a published rule. Requests from all other addresses receive a `403` response.
> [!NOTE]
>
> If you publish only some of your rules, the categories covered exclusively by the remaining unpublished rules stay not enforced. Requests to those categories continue to be accepted from any IP address until you publish the rules that cover them.
### View Rule Details and Activity
The API firewall page displays the following information for each rule:
| Column | Description |
| - | - |
| **Name** | The descriptive name assigned to the rule. |
| **Whitelist categories** | The API categories this rule whitelists (for example, Data, or Segmentation and Campaigns). |
| **Condition** | The IP address type applied to the rule (for example, Single IPv4 or CIDR Range IPv4). |
| **Updated on** | Date and time when the rule was last updated. |
| **Updated by** | Email address of the user who last edited or modified the rule. |
| **Status** | Current enforcement state of the rule: **Published** or **Unpublished**. |
| **Actions** (ellipsis icon) | Click the ellipsis icon to access options to edit or delete the rule. |

## Manage API Firewall Rules
### Edit an Existing Rule
1. On the **API firewall** page, click the ellipsis icon on the rule you want to modify.
2. Click **Edit**. The **Edit API Firewall Rule** dialog box opens.
3. Update the **Rule name**, **Whitelist categories**, **Condition**, or **Value** as needed.

> [!WARNING]
>
> **Warnings during editing**
>
> * **First rule for this category:** If you add a category that currently has no other rules covering it, the editor shows the same first rule warning described in [Add New API Firewall Rule](#add-new-api-firewall-rule).
>
> * **Last rule for this category:** This warning appears only when you're editing a rule that is currently **Published** and is the only published rule covering one or more categories — for example, if your edit removes a category from the rule. The warning indicates that publishing this edit will disable firewall protection for those categories.
4. Select **Save**. The edited rule is saved as **Unpublished** — select **Publish** to enforce your changes.

### Filter Rules by Category
You can filter the rules list to show only rules that cover a specific API category. On the API Firewall page, select a category to view all rules whitelisting that category.

### Unpublish or Delete a Rule
* **To unpublish:** Select the active rules using the checkboxes and select **Unpublish** at the bottom of the screen. A confirmation dialog appears. Select **Unpublish** to confirm. The rule remains in your list but is no longer enforced.
> [!WARNING]
>
> **Unpublish confirmation modal**
>
> When you unpublish a rule, a confirmation modal appears showing the category the rule covers. The modal warns that unpublishing this rule will stop blocking IPs for that category and reminds you that if all rules are unpublished for a category, firewall protection is disabled and all IPs can access that category's APIs.
* **To delete:** Click the ellipsis icon on the rule, select **Delete**, and confirm the deletion in the dialog box. Deleted rules are removed from the list permanently.
> [!WARNING]
>
> **Deleting the last published rule for a category**
>
> If the rule you're deleting is **Published** and is the only published rule covering one or more categories, a confirmation modal opens. The modal lists the affected categories and warns that deleting this rule will disable firewall protection for those categories. It also suggests unpublishing the rule instead if you may need to restore it later.
>
> 
## FAQs
> [accordion] Why should I add all IP rules before publishing them?
>
> Publishing a rule enforces every category it covers within approximately 15 minutes. If you have three server IPs across two categories and publish them one at a time, each server without an active rule for its category may receive `403` errors until its rule is published and propagated. Add all rules in **Unpublished** status first, then select all and publish them together to prevent service interruptions for your authorized systems.
> [accordion] Can one rule cover multiple categories?
>
> Yes. Select multiple categories in the **Whitelist categories** field when you create or edit a rule. The rule applies to all selected categories.
> [accordion] Does the API Firewall affect mobile app or website SDK traffic?
>
> No. The API Firewall applies to server-to-server API traffic across its supported categories. It does not affect end-user mobile or web SDK traffic.
> [accordion] How does a blocked system receive notification of the block?
>
> MoEngage does not send a dashboard notification when the firewall blocks a request. The blocked system receives a `403` error directly in the API response. The dashboard status column reflects the current published or unpublished state of each rule.
> [accordion] What happens if I accidentally exclude my server's IP when publishing?
>
> The API Firewall rejects requests from any IP address not covered by an active rule for the relevant category, including your own servers. To prevent accidental lockouts, verify that all authorized server IPs are present in your rules before selecting **Publish** — the first rule warning in the editor flags categories where this would be the first active rule.
> [accordion] Can I use wildcards or fully qualified domain names (FQDNs) in rules?
>
> No. The API Firewall evaluates requests using network-layer IP identifiers. Rules must specify single IP addresses or CIDR ranges. Domain names are not supported.
> [accordion] What happens if the API Firewall experiences an internal failure?
>
> The API Firewall is designed to fail open. If an internal failure occurs, the system allows API traffic through rather than blocking legitimate requests, preserving data collection continuity.
## Next Steps
Now that your API Firewall rules are configured, refer to the following resources to strengthen your workspace security further:
* [Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs) — Review a complete record of all API Firewall rule changes, including who made each change, when, and from which IP address.
* [Firewall](/docs/user-guide/settings/account/security/firewall) — Restrict MoEngage dashboard login access to approved IP addresses, complementing the API-level protection provided by the API Firewall.
* [SDK Authentication](/docs/user-guide/settings/account/security/sdk-authentication) — Secure your mobile and web SDK traffic using JWT-based authentication to validate requests from your app users.
* [Security Best Practices](/docs/user-guide/settings/account/security/security-best-practices) — Explore recommended configurations across authentication, access control, and network security to keep your workspace secure.
# Automatic Logout
Source: https://moengage.com/docs/user-guide/settings/account/security/automatic-logout
Understand when and why MoEngage automatically logs you out of your account, and how to log back in after each automatic logout scenario.
MoEngage automatically logs you out of your account in some scenarios. The following table lists those scenarios and how you can log in to your account again:
| Scenario | To log in again: |
| - | - |
| Your session expires. See [Session Expiry](#session-expiry) for the timeout durations that apply. |
Go to the login URL of your MoEngage account.
[Log in using your credentials](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
|
| You switch between workspaces that have different login methods. For example, workspace 1 uses Google Sign In only, and workspace 2 uses Single Sign On (SSO) only. |
Go to the login URL of your MoEngage account.
[Log in using SSO](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
|
| You switch between workspaces that have different authentication mechanisms. For example, 2-step verification is disabled in workspace 1 and enabled in workspace 2. |
[Set up 2-step verification on your device](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#set-up-2-step-verification-on-your-device).
Go to the login URL of your MoEngage account.
Log in using your credentials.
On the 2-Step Verification page, use the 6-digit verification code generated by your authenticator app and verify it.
|
| Your Admin has not enabled 2-step verification at the workspace level, and you have logged in to your account. You or your admin enables 2FA settings for your workspace. |
[Set up 2-step verification on your device](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#set-up-2-step-verification-on-your-device).
Go to the login URL of your MoEngage account.
Log in using your credentials.
On the 2-Step Verification page, use the 6-digit verification code generated by your authenticator app and verify it.
|
| Your admin enables Google login or SSO options. |
Go to the login URL of your MoEngage account.
[Log in Using the Sign in with Google Option](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
|
| Your admin revokes your access within the workspace. | Request your admin to grant you access again. Otherwise, you cannot log in to your account. |
| Your IT team enables firewall settings for your workspace, but your credentials do not match the firewall criteria. That is, your IP address does not match the list of IP addresses allowed to access the workspace. | Contact your IT team to either change your IP address or change the IP addresses allowed to access the workspace. |
| Your admin changes your role. |
Go to the login URL of your MoEngage account.
[Log in using your credentials](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage).
|
## Session Expiry
MoEngage enforces the following timeout durations to end a session:
* **Idle Timeout (24 Hours)**: MoEngage automatically logs you out of the platform after 24 hours of inactivity. If you take no action within this window, your session expires, and you must re-authenticate to resume work.
* **Refresh Timeout (60 Days)**: To minimize disruptions to your workflow, MoEngage extends active sessions using refresh tokens. For security compliance, MoEngage enforces a hard session limit every 60 days. After this period, you must log in again, regardless of recent activity.
# Firewall
Source: https://moengage.com/docs/user-guide/settings/account/security/firewall
Restrict MoEngage dashboard access to approved IP addresses by configuring firewall rules. Whitelist or block specific IPs and CIDR ranges.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
This feature limits and controls the MoEngage dashboard access to only approved IP addresses or ranges with an additional authentication measure. This ensures increased security and a lower risk of compromised accounts.
> [!NOTE]
>
> You must be an Admin for your MoEngage workspace to add a firewall. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
# Add a Firewall
Perform the following steps to add a firewall:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.
2. On the Security page, click the **Firewall** tab.

3. Click **Add** **firewall**. 
4. On the **Add firewall**dialog box, enter the following details:

5. Under **Select Type**, select an option:
* **Allowed**: Select this option to whitelist any IP. You can add specific IP addresses or ranges and grant permission to access the MoEngage dashboard. Only connections originating from these IPs will be successful. This is a security measure to restrict access to authorized users and networks, such as your office or a designated VPN.
* **Blocked**: Select this option to blacklist any IP. You can add specific IP addresses or ranges and block their access to the MoEngage dashboard. Connections originating from these IPs are effectively blocked from accessing the MoEngage dashboard. If users attempt to log in from a blocked IP address, their login will fail.
6. In the **Enter IPs/ip range** box, type the IP addresses and subnets you want to allow or block as Classless Inter-Domain Routing (CIDR) ranges.
> [!WARNING]
>
> **Critical**
>
> Do not block IP addresses with a /0 or /32 subnet mask.
>
> * Blocking IP addresses with a /0 subnet mask will block all possible IPv4 addresses, and your workspace will be inaccessible.
>
> 
>
> * Blocking IP addresses with a /32 subnet mask can lead to unintended workspace inaccessibility issues for individual IP addresses.
>
> 
7. Click **Save**.
> [!WARNING]
>
> * If your current IP fails to meet the firewall criteria, you will receive the following error message:
>
> 
>
> This prevents you from adding the firewall to your workspace.
>
> * After you add the firewall successfully, any logged-in users not connected to the registered networks will be automatically logged out.
# Edit IPs or IP Ranges
To edit IPs or IP ranges, perform the following steps:
1. On the Security page, click the **Firewall** tab.
2. Click the ellipsis icon adjacent to the IP/IP range under **Actions**.
3. Click **Edit**.

4. On the **Edit firewall** dialog box, make the necessary edits. For more information, refer [here](/docs/user-guide/settings/account/security/firewall).

5. Click **Save**.
Your IP status is now updated successfully.
# Delete IPs or IP Ranges
To delete IPs or IP ranges, perform the following steps:
1. On the Security page, click the **Firewall** tab.
2. Click the ellipsis icon adjacent to the IP/IP range under **Actions**.
3. Click **Delete**.

The Delete Config pop-up window will appear, prompting for confirmation to delete the config.
4. Click **Delete**.

Your IPs or IP ranges are removed successfully.
# FAQ
* **__Why is my access to the MoEngage dashboard denied?__**
MoEngage access may be restricted to specific IP addresses configured by your administrator.
For example, the IP address of your office VPN is whitelisted, whereas the network to which your personal device is connected to may not be. When you try to access the MoEngage dashboard from outside the office VPN, MoEngage will deny you access. In that case, you need to connect to your office VPN and access the MoEngage dashboard.
If you cannot access the MoEngage dashboard, contact your MoEngage administrator to verify that you are using a whitelisted IP address. To check your current IP address, use a website such as [What is My IP Address](https://whatismyipaddress.com/).
# IP Whitelisting in MoEngage
Source: https://moengage.com/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage
Set up IP whitelisting in MoEngage to restrict dashboard and API access to approved IP addresses, enhancing security for your organization.
## Overview
IP whitelisting (IP allowlisting) is a security practice that allows organizations to restrict access to their networks, systems, and resources to predefined IP addresses, blocking all others. This cybersecurity mechanism helps businesses prevent unauthorized access and protect sensitive data. Businesses can use IP whitelisting to control access to their tools, software, applications, websites, and critical resources.
This document outlines the relevance of IP whitelisting and how marketers and developers can use it effectively.
## Key Advantages of IP Whitelisting
The following are the advantages of IP whitelisting:
* **Enhanced security**: By permitting connections only from known, trusted IP addresses, whitelisting effectively blocks potential threats from unknown sources, significantly reducing the risk of unauthorized access and malware attacks. Overall, it adds an extra layer of security to protect sensitive data.
* **Proactive defense**: Unlike blacklisting, which relies on identifying and blocking known threats, whitelisting takes a proactive approach by allowing only approved access, making it more effective against emerging threats.
* **Reduced false positives**: Because whitelisting blocks connections only from unapproved sources, the chances of accidentally blocking legitimate users are minimized, reducing frustration and disruption.
* **Improved network visibility**: By actively managing the list of allowed IP addresses, organizations gain better insight into who is accessing the network and can easily identify suspicious activity.
## Whitelist MoEngage IPs
MoEngage sends/receives data to/from the servers of customers or partners. With IP whitelisting, you can verify that requests are actually coming from MoEngage, adding an additional layer of security.
MoEngage is a multi-tenant SaaS vendor, so our services change IPs frequently for scale and security. We may need to send data from a different server when circumstances demand it to ensure our services are operational and customers are not impacted. MoEngage may use one or all of the IPs listed in this document while sending/receiving data to/from the servers of customers or partners.
### Campaign Sending
MoEngage uses dynamic IPs. But if you need MoEngage to access your service via static IPs, you must whitelist MoEngage IPs on your side. To enable static IPs for a messaging channel, contact your Customer Success Manager (CSM) or the Support team to request enablement of *Send via Static IPs for ``*. After static IPs for a messaging channel are enabled, you can whitelist the relevant MoEngage IPs based on the data center where your workspace is located. For more information on MoEngage Data Centers, refer [here](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
Here are the IPs that you can whitelist to ensure that only allowed IPs send messages:
Channels or Campaigns
Data Center
MoEngage IPs That Need Whitelisting
Connector Campaigns
DC-01
52.6.248.125
44.205.83.206
34.235.212.204
34.233.63.26
34.206.66.48
3.82.83.239
3.211.230.54
34.198.62.77
34.207.33.10
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
DC-05
Not Available
DC-06
16.78.137.157
16.78.95.240
108.137.84.19
SMS Campaigns
Out-of-the-box connectors
Custom connectors
DC-01
52.6.248.125
44.205.83.206
34.235.212.204
34.233.63.26
34.206.66.48
3.82.83.239
3.211.230.54
34.198.62.77
34.207.33.10
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
DC-05
Not Available
DC-06
16.78.137.157
16.78.95.240
108.137.84.19
WhatsApp Campaigns
DC-01
52.6.248.125
44.205.83.206
34.235.212.204
34.233.63.26
34.206.66.48
3.82.83.239
3.211.230.54
34.198.62.77
34.207.33.10
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
DC-05
Not Available
DC-06
16.78.137.157
16.78.95.240
108.137.84.19
Email Campaigns(sent via Custom API/Custom SMTP Connector/Private ESP or using PII Fetch API/Content API)
DC-01
52.6.248.125
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
DC-05
18.143.35.151
DC-06
43.218.11.107
16.78.49.147
108.137.191.127
DC-101
52.38.219.254
34.218.145.185
Push Campaigns
DC-01
34.232.43.152
44.205.187.13
54.156.161.42
DC-02
18.192.81.203
3.123.167.15
35.158.28.57
DC-03
13.202.37.36
3.108.122.10
3.6.111.53
DC-04
18.219.179.132
3.13.66.12
3.15.129.107
DC-05
Not Available
DC-06
16.78.137.157
16.78.95.240
108.137.84.19
Content API or Fetch PII Token
All data centers (DC-01 - DC-06)
PII and Content API use the same IPs as that of the channel. So, if you plan to use one or more channels in the campaign, whitelist all the campaign channel IPs mentioned above.
### Data Transfer
MoEngage connects to your data systems from the following IPs for data imports, data warehouse exports, streams, and partner exports (such as mParticle and Segment), and for connection tests on the App Marketplace. Whitelist all the IPs listed for your data center.
| Data Center | MoEngage IPs That Need Whitelisting |
| - | - |
| DC-01 |
|
To whitelist these IPs in your system, follow the steps in the guide for your partner:
| Partner | Steps |
| - | - |
| Snowflake | [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/snowflake#enable-ip-whitelisting) |
| Google BigQuery | [Step 2: Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery#step-2-enable-ip-whitelisting) |
| Databricks | [Step 4: Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/databricks#step-4-enable-ip-whitelisting) |
| Amazon Redshift | [Step 3: Allow MoEngage IPs to Access Your Cluster](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift#step-3-allow-moengage-ips-to-access-your-cluster) |
| Amazon S3 | [Step 3: Enable IP Whitelisting for Imports](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-3-enable-ip-whitelisting-for-imports). Use this only for imports from a bucket in a different AWS region from your data center. Don't restrict a bucket you export to by IP address. |
| Google Cloud Storage | [Step 4: Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/cloud-storage/google-cloud-storage#step-4-enable-ip-whitelisting) |
| SFTP | [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/cloud-storage/sftp#enable-ip-whitelisting) |
| Streams | [Enable IP Whitelisting](/docs/api/data/moengage-streams#enable-ip-whitelisting) |
### Audience Transfer
Whitelist the following MoEngage IPs so that MoEngage can connect to your or your partner's systems for [Outbound Segment Sync](/docs/user-guide/data/exports/segments/outbound-segment-sync), the [File Segment API](/docs/api/file-segments/create-file-segment), and [warehouse segments](/docs/user-guide/segment/create-segments/warehouse-segments).
Audience Transfer
Data Center
MoEngage IPs That Need Whitelisting
Outbound Segment Sync
DC-01
52.6.248.125
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
DC-05
Not Available
DC-06
43.218.197.196
DC-101
52.38.219.254
34.218.145.185
File Segment API
DC-01
184.72.243.80
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
3.139.47.208
DC-05
18.143.35.151
DC-06
43.218.197.196
DC-101
52.38.219.254
34.218.145.185
Warehouse Segments
DC-01
52.6.248.125
DC-02
18.195.110.23
DC-03
3.6.251.95
DC-04
18.217.73.1
### Catalog and Feeds
You can whitelist the following MoEngage IPs to allow MoEngage to import their catalog feed via SFTP-based ingestion:
| Data Center | MoEngage IPs That Need Whitelisting |
| - | - |
| DC-01 | 52.1.205.204 |
| DC-02 |
18.195.110.23
3.77.101.97
|
| DC-03 | 3.6.251.95 |
| DC-04 | 18.217.73.1 |
| DC-05 | Not Available |
| DC-06 | Not Available |
## IP Whitelisting for MoEngage APIs
Use the [API Firewall](/docs/user-guide/settings/account/security/api-firewall) to restrict which IP addresses can call MoEngage APIs. You create and publish whitelist rules for each API category under **Settings** > **Account** > **Security** > **API firewall**.
## Whitelist Your IPs
IPs from your or your partner’s networks that can access MoEngage services:
| Type | Description | Steps |
| - | - | - |
| Dashboard Access | Allows you to whitelist your or your partner network IPs that can access the MoEngage dashboard | You can enable the Firewall on the MoEngage dashboard. For more information, refer to [Firewall](/docs/user-guide/settings/account/security/firewall). |
| Open Analytics | Allows you to whitelist your or your partner network IPs that can access the MoEngage Open Analytics. | Please contact your MoEngage Customer Success Manager (CSM) or the Support team with the subject *Whitelist IPs for Open Analytics Access,* and share the list of IPs to be whitelisted in the ticket. |
| MoEngage APIs | Allows you to whitelist the IPs that can call MoEngage APIs, across the Data, Segmentation, Campaigns, Partner Integration, and Content categories. | Configure the rules yourself on the MoEngage dashboard. For more information, refer to [API Firewall](/docs/user-guide/settings/account/security/api-firewall). |
## Conclusion
IP whitelisting is important for maintaining data security when using MoEngage services. Contact the MoEngage Support team for additional assistance or clarification on IP whitelisting procedures.
## Frequently Asked Questions
**Does MoEngage provide IP whitelisting for MoEngage APIs?**
Yes. Use the [API Firewall](/docs/user-guide/settings/account/security/api-firewall) to configure IP rules yourself from **Settings** > **Account** > **Security** > **API firewall**. Each rule whitelists one or more API categories: Data, Segmentation, Campaigns, Partner Integration, and Content. Once you publish the rule, MoEngage rejects requests to those categories from any IP address outside your whitelist with a `403` response.
**Can a brand restrict which IPs can access MoEngage APIs on the API key level?**
No. API Firewall rules apply at the workspace level and are scoped by API category, not by individual API key. To request per-key IP restrictions:
1. Log in to your MoEngage dashboard.
2. In the upper-right corner, click **Need help** and then click **Submit product idea**.
# Just-in-Time User Provisioning (JIT)
Source: https://moengage.com/docs/user-guide/settings/account/security/just-in-time-user-provisioning-jit
Automate user creation and role management in MoEngage with Just-in-Time (JIT) provisioning. Provision users directly from your identity provider on first login.
> [!NOTE]
>
> **Early Access**
>
> Just-in-Time User Provisioning is an Early Access feature. To enable it for your account, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
> [!NOTE]
>
> MoEngage supports JIT provisioning only for logins initiated via the Identity Provider (IdP-initiated login), which allows MoEngage to correctly identify the targeted workspace.
Just-in-Time User Provisioning lets you automate the creation and management of users in your MoEngage workspace. This feature creates users directly from your Identity Provider on their first login.
> [!TIP]
>
> **Prerequisites**
>
> Before enabling JIT provisioning, ensure SSO is configured and active for your workspace. For more information, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
## Advantages
* **Faster onboarding**: New team members can access MoEngage immediately without waiting for a manual invitation.
* **Dynamic role assignment**: Roles can be automatically assigned or updated from the identity provider (if enabled in MoEngage).
* **Temporary access**: Provide session-based access to your users, where they can be automatically deleted after their session ends (if enabled in MoEngage).
# Access Just-in-Time User Provisioning
1. On the left navigation menu in your MoEngage workspace, navigate to **Settings** > **Account** > **Security** > **Login**.
2. Click **Single Sign On (SSO) only**.\
**Note**: Ensure SSO is configured. For more information, refer to [how to configure SSO](/docs/user-guide/settings/account/security/single-sign-on-sso).
3. Scroll to the **Automate user provisioning** section.

## Permissions to Access
The following table describes the permissions required to access and use JIT provisioning:
| Permission Component | Permission Name | Details |
| - | - | - |
| Security Settings | Setup & Manage | Allows you to view, enable, update, or disable user provisioning. |
## Step 1: Enable Just-in-Time User Provisioning
1. Turn the **Automate user provisioning** toggle on.

\
The **Configure provisioning method** dialog box appears.
2. Select **JIT Provisioning** as your configuration type.

## Step 2: Configure and Save
1. Provide the following fields:
| Field | Required | Description |
| - | - | - |
| Default role | Yes |
MoEngage requires a fallback role. If the role is not passed from the Identity Provider (via the SAML assertion call) or does not contain the role value, the user is assigned this default role to access the workspace.
All default and custom roles are available for selection as the default role.
|
| Update user's role | Optional | If checked, the user's role in the workspace is updated based on the value received from the Identity Provider in each SAML assertion call. **Note**: If unchecked, and the user's role received from the Identity Provider is different from the role in the workspace, the user is granted access based on the role received from the Identity Provider for that particular session only, without any permanent changes to their role in the workspace. |
| Delete user at the end of the session | Optional | If checked, the user is deleted and removed from that workspace either when the session expires (for example, user logout or force logout) or after 24 hours, whichever happens first. |
2. Click **Save**.

\
The **Save your configuration** dialog box appears, prompting you to confirm your configuration.
3. Click **Confirm**.

\
The enabled successfully message appears.
# Identity Provider (IdP) Setup
JIT provisioning supports the following Identity Providers:
* Okta
* Microsoft Azure
* OneLogin
* Any Identity Provider that supports Just-in-Time User Provisioning
> [tab] Okta
>
> ## Step 1: Add the Role Attribute to the MoEngage SSO Application
>
> 1. Navigate to the **Okta Admin Console**.
> 2. On the left navigation menu, click **Directory** > **Profile Editor**.
>
> 
> 3. On the **Profile Editor** page, select the MoEngage SSO application you created, or use the **Search for people, apps, and groups** box to find it.
>
> 
> 4. Click **Add Attribute**.
>
> 
>
> \
> The **Add Attribute** dialog box appears.
> 5. In the **Data type** list, select **string**.
> 6. In the **Display name** box, enter role.
> 7. In the **Variable name** box, enter role.
> 8. In the **Description** box, enter role.
> 9. Click **Save**.
>
> ## Step 2: Configure SAML Attribute Statements
>
> 1. Navigate to **Applications** > **Applications** and click the MoEngage SSO application.
>
> 
> 2. Click the **Sign On** tab and scroll down to the **Attribute Statements (Optional)** section.
> 3. Click **Show legacy configuration** to expand the section.
> 4. Click **Edit** adjacent to the **Profile attribute statements** section and enter the following details:
> | Field | Value |
> | - | - |
> | Name | role |
> | Name format | Basic |
> | Value | appuser.role |
> 5. Click **Save**.
>
> 
>
> ## Step 3: Assign the User and Define the Role
>
> 1. Navigate to **Applications** > **Applications** and click your MoEngage SSO application.
>
> 
> 2. On the **Assignments** tab, click **Assign** > **Assign to People**.
>
> 
> 3. In the **assignment attributes** modal, locate the **Role** field and enter the exact role name (for example, Admin, Manager, Marketer, or a custom role) as defined in your MoEngage workspace.
> 4. Click **Save and Go Back**, and then click **Done**.
>
> 
> 5. To update an existing user:
> 1. In the **Assignments** tab, click the pencil icon  next to the user.
> 2. Edit the role and click **Save**.
>
> 
>
> ## Step 4: Validation
>
> After the setup is complete, log in to MoEngage through your Identity Provider (IdP). To verify that roles are passed correctly, inspect the ACS payload and confirm that the role attribute contains the expected value as passed in the Identity Provider and defined in MoEngage (for example, Admin). This confirms that users are assigned the appropriate role upon redirection.
> [tab] Azure
>
> ## Step 1: Configure Attributes and Claims
>
> 1. Navigate to the **Azure Admin Console**.
> 2. On the Azure services page, click **Microsoft Entra ID**.
>
> 
> 3. On the **Overview** page, go to the left navigation menu and click **Manage** > **Enterprise applications**.
>
> 
> 4. On the **Enterprise applications | All applications** page, find your application in the list or use the **Search by application name or object ID** box to find it, and select the application you want to configure.
>
> 
> 5. On the left navigation menu, click **Single sign-on** and then click **Edit** in the **Attributes & Claims** section.
>
> 
> 6. On the **Attributes & Claims** page, click **Add new claim**.
> 7. On the **Manage claim** page, enter the following details:
> | Field | Required | Value |
> | - | - | - |
> | Name | Yes | Any value can be entered here (for example, role). **Note**: The claim name must be unique. |
> | Name format | Optional | Leave it blank. |
> | Source | Yes | Select the **Attribute** option (this is selected by default). |
> | Source attribute | Yes | Click **user.assignedroles** in the drop-down list. |
> 8. Click **Save**.
>
> 
> 9. After you click **Save**, verify that the Role claim appears in the **Additional claims** list with the value **user.assignedroles**.
>
> 
>
> ## Step 2: Assign Users and Roles
>
> Follow the steps mentioned in [Role Creation](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-5-role-creation) (Step 5) of the SCIM documentation before proceeding with the steps below:
>
> 1. Go back to the **Enterprise applications | All applications** page, and click **Users and groups**.
> 2. Click **Add user/group**.
>
> 
>
> \
> The **Add Assignment** page appears.
> 3. Under **Users**, click the **None Selected** link. The **Users** dialog box pane appears on the right side.
> 4. Select the required user checkbox (for example, Security Integration) and click **Select**.
>
> 
> 5. Under **Select a role**, click the **None Selected** link. The **Select a role** dialog box pane appears on the right side.
> 6. In the **Enter role name to filter items** box, type the appropriate role (for example, Analyst or Admin) and click **Select**.
>
> 
> 7. Click **Assign** at the bottom of the **Add Assignment** page.
>
> 
>
> \
> After Microsoft Entra ID successfully updates the user, the Application assignment succeeded message appears.
>
> ## Step 3: Validation
>
> After the setup is complete, log in to MoEngage through the Microsoft My Apps portal ([myapps.microsoft.com](https://myapps.microsoft.com)) by clicking the assigned application. You are redirected to the login flow. During the login process, inspect the ACS payload and verify that the role attribute is present and contains the expected value (for example, Analyst). This confirms that the role is passed correctly and that the user is provisioned in MoEngage with the appropriate role upon their first login.
# Update or Disable JIT Provisioning Configuration
## Update Configuration
1. Navigate to the **Automate user provisioning** section.
2. Click **Edit**.

3. Modify the required settings as needed.
4. Click **Save**.

\
The **Save your configuration** dialog box appears, prompting you to confirm your configuration.
5. Click **Confirm** to apply the changes.

## Disable Configuration
1. Navigate to the **Automate user provisioning** section.
2. Turn the **Automate user provisioning** toggle off.

\
The **Disable user provisioning** dialog box appears.
3. Click **Confirm**.

\
The **JIT provisioning disabled successfully** message appears to confirm the action.
# Security and Logs
* **2FA and firewall**: Existing firewall rules apply to the users created via Just-in-Time User Provisioning. If 2FA is enforced for the workspace, these users must set up and enter a 2FA code upon login.
* **Audit logs**: All activities, including enable, disable, and update operations and user create, delete, and update operations, are recorded in the Audit Logs under Login settings.
* **Notifications**: Admins receive email notifications whenever Just-in-Time User Provisioning is enabled or disabled, or when a new user is created via Just-in-Time User Provisioning.
# FAQs
> [accordion] What happens if I try to enable Just-in-Time User Provisioning while SCIM is enabled?
>
> You cannot enable Just-in-Time User Provisioning while SCIM is enabled. You must first disable SCIM.
> [accordion] What happens if the Delete user at the end of the session checkbox is NOT selected?
>
> MoEngage creates the user upon their first sign-in. The user remains active in the workspace until access is manually revoked. For more information, refer to [how to revoke access](/docs/user-guide/settings/account/team-management/manage-members).
> [accordion] What happens if the Delete user at the end of the session checkbox IS selected?
>
> MoEngage creates the user for that specific session. The system automatically revokes access when the session ends or 24 hours after user creation, whichever happens first.
>
> **Note**: This rule applies only to users created via Just-in-Time User Provisioning.
> [accordion] What happens if I switch from using SCIM to JIT?
>
> The users created via SCIM remain active in the workspace along with their role information. For further role updates, you can use JIT (if the option to update users' roles is selected) or the **Team Management** > **Members** page (if the option to update users' roles is not selected). To revoke access, refer to [how to revoke access](/docs/user-guide/settings/account/team-management/manage-members).
> [accordion] What happens if multiple role values are received in the SAML assertion call for a user?
>
> MoEngage refers to the first role value in the list when multiple values are received in the SAML assertion call.
> [accordion] What happens to a user if I perform user management operations via the Team Management > Members page while JIT is configured?
>
> * **Invite**: The user is invited to the workspace.
> * **Update Role**: The user's role can be updated. However, it is only effective if the option to update users' roles under JIT configuration is not selected.\
> **Note**: This option is provided to facilitate role updates for users who are not part of the JIT application in the Identity Provider but are part of the SSO application, or are admins logging in via password (and not part of any application in the Identity Provider).
> * **Revoke Access**: The user can be deleted or access can be revoked using the same page. However, if the user is part of the IdP application where JIT is configured, the user can log in again.
# MoEngage Access
Source: https://moengage.com/docs/user-guide/settings/account/security/moengage-access
Control whether MoEngage support can access your workspace for troubleshooting. Enable or disable access and set time-limited permissions.
By default, the MoEngage Support Team can access your workspace (account). The *MoEngage Access* feature allows you to control MoEngage access to your workspace.
> [!TIP]
>
> **Prerequisite**
>
> To manage MoEngage access, you need a default Admin role or a custom role with the **Setup & manage** permission for the **Login Settings** component. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
The following are examples of why the MoEngage users need access to your workspace:
* To diagnose and troubleshoot issues you face with your MoEngage workspace.
* Your issue is too complex to be understood without accessing your workspace.
* Your issue cannot be reproduced anywhere else.
* Visual analysis of the MoEngage workspace is needed and is not obtainable via any other method.
* Highly technical issues that need to be escalated through multiple levels of support.
> [!NOTE]
>
> * MoEngage users have read-only access to your workspace.
> * The MoEngage user's actions and changes, such as user logins, data modifications, and configuration within your workspace, are recorded in the audit logs. For more information, refer to [Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs).
# Revoke Access from MoEngage Users
> [!NOTE]
>
> If you do not want to share access to your workspace with the entire MoEngage Support Team, you can revoke it. However, you can manually add the required MoEngage team members. To add MoEngage members to your workspace, refer [here](/docs/user-guide/settings/account/team-management/manage-members).
To revoke access from MoEngage users, perform the following steps:
1. On the Security page, click the **MoEngage access** tab.
2. Turn the **Grant access to MoEngage users** toggle off.

The MoEngage access pop-up window appears, prompting confirmation to revoke access from MoEngage users.
3. Click **Revoke**.

You revoked access from MoEngage users successfully.
# Grant Access to MoEngage to Users
If you revoked the access from MoEngage users and want to grant it again, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.
2. On the Security page, click the **MoEngage access** tab.

3. Turn the **Grant access to MoEngage users** toggle on.

The MoEngage access pop-up window appears, prompting confirmation to grant access to MoEngage users.
4. Click **Allow.**\\

You granted access to MoEngage users successfully.
> [!NOTE]
>
> You can provide temporary access to MoEngage users only when you encounter an issue with the MoEngage workspace. You can revoke the access after the issue is resolved.
# Overview
Source: https://moengage.com/docs/user-guide/settings/account/security/overview
Overview of MoEngage security features including login methods, two-factor authentication, API firewall, firewall rules, SSO, and workspace access controls.
MoEngage employs security to restrict access and ensure data protection with the following features:
* [Login](/docs/user-guide/settings/account/security/overview#login)
* [2-Step verification/2FA](/docs/user-guide/settings/account/security/overview#2-step-verification)
* [API Firewall](/docs/user-guide/settings/account/security/overview#api-firewall)
* [Firewall](/docs/user-guide/settings/account/security/overview#firewall)
* [MoEngage access](/docs/user-guide/settings/account/security/overview#moengage-access)
> [!NOTE]
>
> You must be an Admin to configure the features above.
# Login
You can define the authentication methods for your team members to log in. MoEngage supports the following login methods:
* Password or Google sign in
* Google Sign In only
* Single Sign On (SSO) only

For more information, refer to [Set Up the Login Method](/docs/user-guide/settings/account/security/set-up-the-login-method).
# 2-Step verification
You can configure 2-step verification or 2-factor authentication for your workspace. If you enable 2-step verification, your team members will be prompted for additional authentication during login. For more information, refer to [Two-Factor Authentication (2FA) or 2-Step Verification](/docs/user-guide/settings/account/security/2-step-verification-or-two-factor-authentication-2fa).
# API Firewall
You can configure the API Firewall to whitelist a specific set of IP addresses per API category — Data, Segmentation, Campaigns, Partner Integration, and Content. When a category is enforced, MoEngage rejects any request to that category's APIs from an IP address not on your whitelist, protecting your data even if API credentials are compromised. For more information, refer to [API Firewall](/docs/user-guide/settings/account/security/api-firewall).
# Firewall
You can enable a firewall to restrict and control access to the dashboard by allowing or blocking specific IP addresses or ranges. For more information, refer to [Firewall](/docs/user-guide/settings/account/security/firewall).
# MoEngage access
You can enable the MoEngage Support Team to access your workspaces and troubleshoot your issues. For more information, refer to [Access for the MoEngage Team](/docs/user-guide/settings/account/security/moengage-access).
# Security Advisory - Rotate Your API Keys and Secure API Access
Source: https://moengage.com/docs/user-guide/settings/account/security/rotate-api-keys-and-secure-api-access
Rotate the API keys your integrations use and restrict API access to trusted IP addresses with the API Firewall.
In light of increased cyber activity across the industry driven by API key compromises, MoEngage recommends that all customers rotate the API keys they use for server-to-server integrations and restrict API access to trusted IP addresses. Since most customers use long-lived API keys, we highly recommend this, and also recommend rotating API keys regularly.
This guide explains how to rotate each type of key with minimal disruption and how to add an IP-based safeguard using the API Firewall.
> [!NOTE]
>
> This is precautionary guidance. We are continuing to investigate and will share further updates.
>
> If you notice unexpected campaigns, messages, or API activity in your workspace, contact MoEngage Support and Security ([Security@moengage.com](mailto:Security@moengage.com)) immediately.
## Which Rotation Path Applies to You
MoEngage supports two ways to rotate a key. Regenerating replaces the key in place and the old key stops working immediately. Creating a new key lets you move over before you retire the old one, so there is no downtime.
| API or integration | Key to rotate | Method | Impact on the old key |
| - | - | - | - |
| Push API (V5) | Any key on the API Keys page | Create a new key, switch over, then archive the old key ([Create New Keys for Supported APIs](#create-new-keys-for-supported-apis)) | Keeps working until you archive it |
| Push API (v2.1 and v2, legacy) | Push key (legacy) | Regenerate the key ([Regenerate Your Push API and Campaigns API V1 Keys](#regenerate-your-push-api-and-campaigns-api-v1-keys)) | Stops working immediately |
| Campaigns API V1, Business Events, Custom Templates, Catalog API | Campaign report / Business events / Custom templates / Catalog API key (legacy) | Regenerate the key ([Regenerate Your Push API and Campaigns API V1 Keys](#regenerate-your-push-api-and-campaigns-api-v1-keys)) | Stops working immediately |
| Data APIs, Segmentation APIs, Inform, Offerings, Decision Policy, Dashboard and Analyze, Personalize, Channel Configuration, and newer Campaigns APIs | Any key on the API Keys page | Create a new key, switch over, then archive the old key ([Create New Keys for Supported APIs](#create-new-keys-for-supported-apis)) | Keeps working until you archive it |
If you are not sure which keys your integrations use, check each server, scheduled job, third-party tool, and vendor that calls MoEngage APIs, and match it to the API in the first column.
## Before You Begin
* List every system that uses each key: backend services, scheduled jobs, CI/CD variables, data pipelines, partner and vendor tools, and saved Postman collections.
* Keep your Workspace ID handy. It does not change when you rotate keys.
* Store new keys in a secrets manager or encrypted configuration, not in source code, tickets, chat, or email.
* For keys you will regenerate, schedule a short change window and have the configuration update ready to deploy. Calls using the old key fail as soon as you regenerate it.
* Make sure you can open **Settings** > **Account** > **API keys**. If you cannot, ask your workspace administrator.
## Regenerate Your Push API and Campaigns API V1 Keys
> [!WARNING]
>
> The old key expires immediately after you regenerate it. Requests that still use it return a `401` error until you replace the key in your integrations.
1. In the MoEngage dashboard, go to **Settings** > **Account** > **API keys**. On workspaces that still show the earlier page, go to **Settings** > **Account** > **APIs**.
2. Find the key to rotate. Push API uses the **Push** key. Campaigns API V1, Business Events, Custom Templates, and Catalog API use the **Campaign report / Business events / Custom templates / Catalog API** key. Legacy keys appear with the authentication type **Basic Auth (Legacy)**.
3. Open the actions menu for the key and select **Regenerate key**. On the earlier page, select the **Regenerate** icon next to the key instead.
4. Confirm the action.
5. Copy the new key straight away and store it in your secrets manager.
6. Update the key in every system you listed in [Before You Begin](#before-you-begin) and deploy.
7. For the Push API, recalculate the `X-MOE-PushAPI-Signature` header with the new key, as described in the Push API reference. The `X-MOE-APPKEY` header still carries your Workspace ID.
8. Send a test request to each API and confirm a successful response. A `401` response means the request is still using the old key.
You can regenerate a key as often as you need. If you do not see the regenerate option for a legacy key, contact MoEngage Support by raising a ticket through the dashboard.
## Create New Keys for Supported APIs
New keys can be created for the API groups below. This method needs no downtime because the existing key keeps working while you move your integrations to the new one.
| API group | Supported authentication types |
| - | - |
| Data APIs | Basic Auth, OAuth 2.0, AWS STS Auth |
| Segmentation APIs | Basic Auth |
| Campaigns | Basic Auth, OAuth 2.0 |
| Inform | Basic Auth |
| Offerings | Basic Auth, OAuth 2.0 |
| Decision Policy | Basic Auth, OAuth 2.0 |
| Dashboard and Analyze | Basic Auth, OAuth 2.0 |
| Channel Configuration | Basic Auth, OAuth 2.0, AWS STS Auth |
| Personalize | Basic Auth, OAuth 2.0, AWS STS Auth |
> [!NOTE]
>
> If you do not see **Create new key**, ask MoEngage Support to enable it for your account.
1. Go to **Settings** > **Account** > **API keys** and select **+ Create new key**.
2. Enter a unique **Key name** of up to 100 characters. Archived keys keep their names, so you cannot reuse a name.
3. Choose the **Authentication type**. You cannot change it after the key is created.
* **Basic Auth:** an API key and secret for server-to-server calls.
* **OAuth 2.0:** short-lived access tokens with an expiry of 5 to 60 minutes (default 15). A stolen token stops working quickly.
* **AWS STS Auth:** authorizes only the AWS assumed-role ARNs you list, up to 10 per key. Use it when your workloads already run on AWS IAM roles.
4. Under **Select APIs for access**, select only the API groups and individual APIs that integration needs.
5. Select **Create key**, then copy the key and store it securely.
6. Deploy the new key to your integration and confirm requests succeed.
7. Return to the **API Keys** page, open the actions menu for the old key, and select **Archive key**.
> [!NOTE]
>
> Archived keys cannot be unarchived, and MoEngage keeps a maximum of 10 archived keys in the archived list. Archive an old key only after every integration has moved off it. Legacy keys cannot be archived, so rotate those with [Regenerate Your Push API and Campaigns API V1 Keys](#regenerate-your-push-api-and-campaigns-api-v1-keys).
Issue a separate key to each internal team and each vendor, scoped to the APIs they use. If one key is exposed, you can regenerate or archive that key without affecting anyone else.
## Add an IP Safeguard With the API Firewall
Rotating keys limits how long an exposed key stays useful. The API Firewall adds a second control: even with a valid key, a request from an IP address that is not on your allowlist receives a `403` response.
> [!NOTE]
>
> If you do not see the **API firewall** tab under **Settings** > **Account** > **Security**, ask MoEngage Support to enable the API Firewall for your workspace.
### What the Firewall Covers
Rules apply to five API categories: **Data**, **Segmentation**, **Campaigns**, **Partner Integration**, and **Content**. Every rule must cover at least one category. Enforcement is per category, so publishing a rule protects only the categories it covers.
> [!WARNING]
>
> The legacy Push API is not supported by the API Firewall, and IP rules are not enforced on it. Regenerating your Push key is the primary protection for the legacy Push API. The API Firewall supports the Inform API, except for a small number of exempt accounts. If you think your account is exempt, contact your MoEngage Customer Success Manager (CSM) or the Support team. To rotate an Inform API key, create a new key and archive the old one. The firewall also does not affect traffic from your mobile app or website SDKs.
### Set Up and Publish Rules
> [!NOTE]
>
> You must be an Admin in your MoEngage workspace to add firewall rules. Get a complete list of the static IP addresses and CIDR blocks your servers use from your DevOps or Security team first.
1. Go to **Settings** > **Account** > **Security** and open the **API firewall** tab.
2. Select **Enable API Firewall**.
3. Enter a descriptive **Rule name**, for example "AWS production servers".
4. Under **Whitelist categories**, select every category the rule covers.
5. Choose a **Condition** (single IPv4, single IPv6, IPv4 CIDR range, IPv6 CIDR range, or IPv4 range) and enter the **Value**.
6. Select **Add rule**. New rules are saved as **Unpublished** and are not enforced yet.
7. Repeat for every server IP, including staging, batch jobs, and vendor systems that call MoEngage.
8. Select all the rules and choose **Publish**, then confirm. Enforcement starts within about 15 minutes.
> [!WARNING]
>
> After you publish the first rule for a category, requests from any IP address that is not in a published rule for that category are rejected. Add all rules as unpublished first and publish them together so that none of your own systems are blocked.
For the full reference, see [API Firewall](/docs/user-guide/settings/account/security/api-firewall).
### Allow Partner Integrations Through the Firewall
Your own servers are not the only systems that call MoEngage APIs. Some partner integrations send requests to MoEngage directly from the partner's infrastructure, so the firewall treats them like any other caller. Before you publish rules for a category, check the following table for the partners you use. If a partner needs IP whitelisting for that category, get its IP ranges and add them to your rules. Otherwise, MoEngage rejects the partner's requests with a `403` response.
| Partner name | Is IP whitelisting needed? | Scope | Action needed |
| - | - | - | - |
| [Salesforce Sales CRM](/docs/partner-guide/data-and-analytics/crm/salesforce-crm-native/overview) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Hightouch](/docs/partner-guide/data-and-analytics/cdps/hightouch) | Yes | Data | Request partner IP ranges, add to whitelist |
| [RudderStack](/docs/partner-guide/data-and-analytics/cdps/rudderstack/moengage-destination) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Salla](/docs/partner-guide/commerce-and-loyalty/e-commerce/salla) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Zapier](/docs/partner-guide/data-and-analytics/workflow-automation/zapier/overview) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Amplitude (event sync)](/docs/partner-guide/data-and-analytics/analytics/amplitude/amplitude-event-streaming) | Yes | Data | Request partner IP ranges, add to whitelist |
| [AppsFlyer Audiences](/docs/partner-guide/data-and-analytics/install-attribution/appsflyer/appsflyer-audience) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Microsoft Dynamics 365](/docs/partner-guide/data-and-analytics/crm/microsoft-dynamics-365-sales/microsoft-dynamics-365-sales) | Yes | Data | Request partner IP ranges, add to whitelist |
| [Mixpanel](/docs/partner-guide/data-and-analytics/analytics/mixpanel) | Yes | Cohort APIs | Request partner IP ranges, add to whitelist |
| [Amplitude](/docs/partner-guide/data-and-analytics/analytics/amplitude/amplitude-audiences) | Yes | Cohort APIs | Request partner IP ranges, add to whitelist |
| [Salesforce Marketing Cloud](/docs/partner-guide/message-orchestration/marketing-cloud/salesforce-marketing-cloud-sfmc/overview) | Yes | Data, Campaigns | Request partner IP ranges, add to whitelist |
| [AEM](/docs/partner-guide/personalize-and-optimize/dynamic-content/adobe-experience-manager/syncing-experience-fragments-as-content-blocks) | Yes | Content | Request partner IP ranges, add to whitelist |
| [Segment](/docs/partner-guide/data-and-analytics/cdps/twillio-segment/getting-started/overview) | No | – | – |
| [mParticle](/docs/partner-guide/data-and-analytics/cdps/mparticle/getting-started/overview) | No | – | – |
| [Adobe RT CDP](/docs/partner-guide/data-and-analytics/cdps/adobe-real-time-cdp/overview) | No | – | – |
| Connected sources (Punchh, RevenueCat, Unbounce, etc.) | No | – | – |
> [!NOTE]
>
> If you use Connected Segments (earlier called Outbound Segment Sync), Streams, or Connector Campaigns to send data to a MoEngage workspace, add MoEngage's IP addresses to that workspace's rules. For the list of IP addresses, refer to [IP Whitelisting in MoEngage](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage).
### Firewall Tips
* Rules accept IP addresses and CIDR ranges only. Wildcards and domain names are not supported.
* You can edit rules, unpublish them, or delete them. Edited rules return to **Unpublished** until you publish them again.
* If the firewall has an internal failure, it fails open so that legitimate traffic keeps flowing.
* Rule changes are recorded in Audit Logs, with the user, time, and IP address of each change.
## Verify and Monitor
* Confirm that every integration returns successful responses with the new keys, and that nothing still sends the old key.
* Review [Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs) to confirm who created, regenerated, or archived each key and when.
* Remove stored copies of old keys from wikis, tickets, chat messages, and code repositories.
* Repeat the rotation on a regular schedule, and whenever someone with access to a key leaves your team or vendor.
| Response | Likely cause | What to do |
| - | - | - |
| `401 Unauthorized` | The request still uses an old, regenerated, or archived key, or the credentials are encoded incorrectly. | Replace the key in the integration. For Basic Auth, the `Authorization` header is the Base64 encoding of `workspace_id:api_key`. |
| `403 Forbidden` | The request came from an IP address that is not in a published API Firewall rule for that category. | Add the server's IP address to a rule for that category and publish it. |
## FAQs
> [accordion] Does my Workspace ID change when I rotate keys?
>
> No. Only the key changes.
> [accordion] Can I use the old and new key together after regenerating?
>
> No. Regenerating invalidates the old key immediately. To overlap old and new keys, create a new key as described in [Create New Keys for Supported APIs](#create-new-keys-for-supported-apis).
> [accordion] Can I restore an archived key?
>
> No. Archived keys cannot be unarchived. Create a new key instead.
> [accordion] Should I use the firewall if I already rotated my keys?
>
> Yes. The two controls protect against different risks: rotation replaces credentials that may have been exposed, and the firewall blocks requests from unknown IP addresses even if a valid key is exposed later.
> [accordion] Who do I contact for help?
>
> Contact your Customer Success Manager or raise a ticket with MoEngage Support from the dashboard.
## Related Documentation
* [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard)
* [API Firewall](/docs/user-guide/settings/account/security/api-firewall)
* [Security Best Practices](/docs/user-guide/settings/account/security/security-best-practices)
# SDK Authentication
Source: https://moengage.com/docs/user-guide/settings/account/security/sdk-authentication
Protect your MoEngage data integrity with SDK Authentication using JWT tokens to validate user requests and block fraudulent app activity.
# Overview
> [!NOTE]
>
> SDK Authentication is a Beta feature. For more details, reach out to your Customer Success Manager (CSM).
Protect the integrity of your data with SDK Authentication. This security feature ensures that only legitimate, logged-in users can send information from your app by stamping every request with a unique, server-generated digital signature: the JSON Web Token (JWT).
MoEngage automatically blocks any fraudulent or invalid data upon arrival (based on invalid JWT token), resulting in trustworthy user analytics and billing, free from corruption and malicious activity.
The following image shows the SDK Authentication dashboard:

## Use Cases
The SDK Authentication helps you with the following use cases:
* **Preventing user impersonation**: Block bad actors (unauthorized attempts) from maliciously updating another user's profile information (like their name, city, or preferences) or sending events on their behalf.
* **Securing high-value events**: Ensure the integrity of critical user actions like *purchase_completed*, *subscription_started*, or *demo_requested*. This prevents fake events from corrupting your analytics and triggering incorrect marketing campaigns.
* **Maintaining data cleanliness**: Maintain high data quality by stopping unauthenticated requests from sending junk data, creating fraudulent user profiles, or corrupting the user database.
## Key Concepts
Before you begin, let's understand the following core concepts of this feature:
| Concept | Description |
| - | - |
| 🔑 Public and Private Keys | This feature uses public-key cryptography. Your team generates a pair of keys. The **Private Key** stays secret on your servers to sign requests. The **Public Key** is uploaded to MoEngage to verify those signatures. |
| 🚦 Enforcement Modes | This setting controls how strictly MoEngage enforces authentication. You can choose one of two modes: **Disabled(Default)** or **Required (Recommended)**. |
## Generate Keys and JWT
Before configuring the MoEngage dashboard, your team must set up the key generation and JWT creation on your server:
1. **Generate an RSA256 Public/Private Key Pair**: You must add the Public Key (Privacy Enhanced Mail (PEM) file) to the MoEngage dashboard, while the Private Key should be stored securely on your server. MoEngage recommends an RSA Key with 2048 bits for use with the RS256 JWT algorithm.
2. **Create a JSON Web Token for the Current User**. After you have your Private Key, your server-side application should use it to return a JWT to your app or website for the currently logged-in user. Typically, you can place this logic wherever your app normally requests the current user’s profile, such as a login endpoint or an endpoint that refreshes the current user’s profile.
When generating the JWT, you must include the following fields in the Header and Payload:
**Header**
| Field | Required | Description |
| - | - | - |
| alg | Yes | The supported algorithm is RS256. |
| typ | Yes | The type must be set to JWT. |
**Payload**
| Field | Type | Keys | Required | Description |
| - | - | - | - | - |
| sub | JSON | key | Yes | The key field within `sub` must match your User ID key (for example, uid). |
| | | Value | Yes | The value field within `sub` must contain the User ID value you pass to the MoEngage SDK when calling the `changeUser` method. |
| exp | Int | NA | Yes | The expiration of when you want this token to expire (in epoch timestamp). |
The following is an example for JWT Token and Payload:
```json Example wrap theme={null}
JWT_Token = 'eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOnsia2V5IjoidWlkIiwidmFsdWUiOiJ1c2VyQG1vZW5nYWdlLmNvbSJ9LCJleHAiOjE3NTgyNjA0NzZ9.Wonz61_b89MZjUtPuvYC4WBTDt_ahdbihscbQvhLlzWjCM6ud5SFLrrzoJJG3eZ7BRikVNV8_ovaPPDmUtXu6Eba1j2MNrBC5ZK3ULv1MsYnhjUyX8puCfq4bdrYOvA1NSGIEjg_HcS18Zm7oY9_5QyrMANw2GpjnasfKsnUopbsfxjJN-oWJpJ5Kz6wY0kFfN1eW3oXvkPoP_EuXk6fPgL0KSXOEBJyjB9f08pgLmGRKLg28y8tJk8j_GLLopcU3dIO6SDfKIlhm7t7jqFbp2HK8JxDcRa7AsJ5HvufLrKRKdf5_y6vcTjJc4VfJIjfvXQGpvt1oeUjz_Mx8kyts28pzb2k3-sqE2QmPGFfGGVEHz9f2E__xZZOBrSHxUEFnNGVioTXmhYzJFNz2nRiunpj1aYeCu0naU8qpxakB7DWglQgf3etdIxpOHnwnhKdikY1v03JIbKX1XOWwnLw4AeW1qtx4DkZlAcMkF0CYUQ0b7kEJYa-UglUVVNhl3W8puwkPxCvUvjutoBlpyrZqYBXikat6qmZgc9rfPQfR08zTz1xS-IOq3dmW43z3GwIAyToJni65aWHBAVr0qM_jrEniyqTXBC4Nw9_RiRildxZzdP2OLfF0-3lyL7886nKShH11szbDcqWlP13rTppQkucO5IiUcjw7eRlGk7rj6s'
jwt_header: {
"alg": "RS256",
"typ": "JWT"
}
jwt_payload:
{
"sub": {
"key": "uid",
"value": "user@moengage.com"
},
"exp": 1755112555
}
public_key = """
-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAkFOpbMqO3sgQHBwATjz3
YQG3WXRaaych06Rvvpmxw6vA+Tbv/9LCbptZvnxXrL/h4bkdlyXKwe3ViN3lZsKR
eDG/a/gm85Zkb04O+/DujiOuoP6djxrm5KbAS6PrRaY9aPCH5IfTlFJjjOjFK4oO
wx/RbWNco4Kkb4wnhkGzKUAjO7w575uRMMv4T+RvdgpixaWpj6G7rKp7fqByqXYw
23xWSUodF0JNM5SatgQ3S2Imwnf0/7aEoPOhRAkH3XyTR+qIE66nof+YLLgqlnYC
s01MR26haoANxqijYFKZqwRXKBMxiV+NiUX0PaZpcfL2enIfBD6rGiBq9vdDX7Yr
aqZnpt1AhEGFcKCI+7MvIkDSKJ3K/QRnLvaL92Cj7ZYcaNrhfPfmHOTmFGrpsuln
DsCGazJbzsi+jqfzSF5Ewoc6Pte9b5u521QKbP8SpPYN8wEIIbDB8ZMwCUuUMBDd
Oy9wELkORwhcKmjVhD2CPcbmidbxCkm/691KDP7nOeIau2jOiytc1Q7pmYr0RErj
GUx1IbtQRFBozxCwWJ1rn0k1Ngt8WLc/Tm+dUu5Gb5ChHYd1wLWd6QITzt1cihGI
emtk9uqqW92X4YV3O1u+AM+sScvVehErHGF3WcyFgTQE0ZSruy4pliOO1rfxxMLW
rzOm15jmMVTnueqsgGbkMx0CAwEAAQ==
-----END PUBLIC KEY-----
"""
```
## Access the SDK Authentication Page
To access to the SDK Authentication page, perform the following step:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**.
2. On the **Security** page, select the **SDK Authentication** tab. 
## Permissions to access
| Capability | Permission Required | Description |
| - | - | - |
| Manage Settings | An Admin role or a custom role with Setup & manage permission for **Security Settings**. **Note:** The **Login Settings** component is now renamed to **Security Settings**. | Grants complete administrative access. The user can add/delete public keys and change the enforcement mode (**Disabled (Default)** or **Required (Recommended**). |
# Configure SDK Authentication
Follow the steps below to configure and enable JWT authentication for your account:
### Step 1: Meet Prerequisites
Before you begin the JWT authentication, ensure you have the following:
1. **MoEngage SDK Integration**: Ensure your development team has integrated the latest version of the MoEngage SDK into your application. For more information, refer to the following platform documentation:
* [Android](https://www.moengage.com/docs/developer-guide/android-sdk/sdk-integration/advanced-or-optional/jwt-authentication)
* [iOS](https://www.moengage.com/docs/developer-guide/ios-sdk/sdk-integration/advanced/jwt-authentication)
2. **Public and Private Key Pair**: A key pair must be generated that meets the technical requirements below. The **Private Key** must be stored securely on your server, while the **Public Key** will be uploaded to the MoEngage dashboard.
| Requirement | Specification |
| - | - |
| Format | Must be in the standard Privacy Enhanced Mail (PEM) format, enclosed within -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- headers. |
| Content | The string between the headers must be a valid, non-empty Base64 encoded key. |
| Algorithm | MoEngage supports RSA256 and RSA512. It is mandatory to be mentioned in the JWT header. |
| Security | The RSA key must have a minimum size of 2048 bits. |
> [!WARNING]
>
> Remember to keep your private keys private. Never expose or hard-code your private key in your app or website. Anyone who knows your private key can impersonate or create users on behalf of your application.
### Step 2: Select an Enforcement Mode
Select the enforcement mode for validating SDK requests:
1. In the **Secure SDK Requests with JWT** section, select one of the three enforcement modes
* **Disabled (Default)**: This is the default state. No authentication is performed. All SDK requests are processed.
* **Required (Recommended)**: MoEngage strictly validates all requests and rejects any request with a missing or invalid signature. Enable this only after successful testing. 
> [!WARNING]
>
> MoEngage recommends **Required (Recommended)** mode. Before you enable **Required (Recommended)** mode, ensure your development team has fully rolled out the updated app to your users. After this mode is active, any data sent from older app versions that do not have the JWT signature will be permanently blocked.
### Step 3: Add Your Public Key
If you select **Required (Recommended)**, you will be prompted to add your public key.
1. In the **Public key details** section, paste your key in the **Enter public key** box.
2. Type a descriptive name in the **Enter description (optional)** box to help you identify the key. 
### Step 4: Save and Confirm
Finally, save your settings to activate the configuration.
1. In the bottom-right corner of the page, click **Save**.\
The **Update your configuration** dialog box appears.
2. Click **Confirm** to apply your configuration.  Your configuration is saved successfully.
# FAQs
> [accordion] What happens to users on older versions of my app if I enable the 'Required' mode?
>
> Data sent from older app versions that don't have SDK authentication will be rejected and permanently lost. We strongly recommend you ensure most of your users have upgraded to the latest app version before enabling this mode.
> [accordion] What should I do if my server has a problem and can't generate tokens?
>
> If you encounter an integration issue, you can immediately return to the MoEngage dashboard and set the enforcement mode back to **Disabled**. This will allow unauthenticated data to be collected again while your team resolves the server-side issue.
> [accordion] Why does this feature use public/private keys instead of a simple secret key?
>
> This method provides higher security. With a public/private key pair, the secret (your private key) never leaves your server. Not even MoEngage has access to it, which prevents anyone from impersonating your users.
> [accordion] Can I use SDK authentication for anonymous (non-logged-in) users?
>
> No. SDK authentication is designed to verify requests only from known, logged-in users. Data from anonymous users will be processed without authentication.
# Security Best Practices
Source: https://moengage.com/docs/user-guide/settings/account/security/security-best-practices
Follow MoEngage security best practices including enabling 2FA, configuring SSO, setting up firewalls, and managing team access permissions.
As an administrator, you want to ensure MoEngage account security. Here are some recommendations for you when you create an account with MoEngage:
## Strong Authentication Practices
* Enable a **Two Factor Authentication (2FA)** system for all MoEngage account users, without exception. This helps you to restrict suspicious login attempts by verifying the identity of the user and making sure that access to the platform is secure. For more information, refer to, [2 Step Verification](/docs/user-guide/settings/account/security/2-step-verification-or-two-factor-authentication-2fa).
* Enable **Single Sign-On (SSO)** access to the MoEngage platform, organization-wide. For more information, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
> [!NOTE]
>
> You might need help from your IT support team to set up SSO. MoEngage supports SSO using SAML 2.0 and acts as a service provider (SP) for SSO.
## Granular Access Controls
* MoEngage allows you provide customized [access, permissions, and privileges](/docs/user-guide/settings/account/team-management/access-roles) for different team members. This helps in restricting every team member from having access to the complete dashboard/database and provides you more control over the information/data distribution.
* MoEngage allows you to implement [Campaign Approval Workflows](/docs/user-guide/settings/account/team-management/campaign-approval-workflow) to have better control over the campaigns that are going live. This can help ensure a more secure campaign workflow and avoid breaches in quality and policies.
## Network Restriction
You can [enable IP Whitelisting](/docs/user-guide/settings/account/security/firewall) in your SaaS application account to ensure user authentication from whitelisted IP only.
* You can whitelist your VPN IP to ensure MoEngage SaaS application access is enabled using a trusted network of your choice.
* If your organization currently does not use a VPN solution, consider adopting Open Source options such as OpenVPN, Pritunl.
* The IP Whitelisting feature on the MoEngage platform/SaaS application is available only to organizations using an Enterprise license. Please contact your MoEngage Customer Success Account Manager for more details.
## Regular User Access Audits
* Audit the access of all MoEngage account users at least once every 2 weeks.
* Revoke the access of all unused, unwanted, or off-boarded users.
* Audit the access, permissions, and privileges of all users from time to time. If they are not required, change their roles to a lower permission level wherever possible.
* Keep users with “Admin” and “Manager” roles to a minimum. We recommend you keep only one admin role for each account.
> [!WARNING]
>
> MoEngage automatically logs you out of your session if your account does not have any activity for one day. To customize the time of your session, please contact the MoEngage Support team.
For more information and a better understanding of implementing secure access controls, please contact your MoEngage Customer Success Manager (CSM) or the support team.
# Set Up the Login Method
Source: https://moengage.com/docs/user-guide/settings/account/security/set-up-the-login-method
Choose and configure the login method for your MoEngage workspace: password with Google sign-in, Google-only, or Single Sign-On (SSO) access.
Perform the following steps to set up the login method for your workspace:
1. On the left navigation menu in the MoEngage dashboard, click **Settings**> **Account** > **Security**. 
2. On the Security page, you are on the **Login** tab by default.
3. Select a login method from the following options:
* [Password or Google sign in](/docs/user-guide/settings/account/security/overview)
* [Google Sign In only](/docs/user-guide/settings/account/security/overview)
* [Single Sign On (SSO) only](/docs/user-guide/settings/account/security/overview)
****
## Password or Google sign in
This is the default option. MoEngage allows your team members to log in to the MoEngage account (workspace) using the email address and password combination or using the **Sign in with Google** button. If you selected any other option and reverted to the **Password or Google sign in** option, click **Save**.

## Google Sign In only
This option limits access to the MoEngage account using Google Sign In only. When you select this option, your team members can no longer access MoEngage using only the email address and password combination. If you want to set up this method, perform the following steps:
1. On the **Login** tab, click **Google Sign In only**.
2. Click **Save**. \
The **Are you sure want to enable Google Sign In ?** pop-up window will appear, prompting you to review the instructions carefully.
3. Select the **Send email to your teammates** check box.
4. Click **Enable**.

You have successfully enabled the **Google Sign In only** method. Your teammates must log in using their Google account by clicking the **Sign in with Google** button.
> [!NOTE]
>
> Any users who do not have a Google account, such as your external stakeholders, will be logged out.
## Single Sign On (SSO) only
This option allows you to enforce Single Sign-On (SSO) for your organization on MoEngage. When you select this option, your team members will use your configured SSO provider to log in to the MoEngage account. They can no longer access MoEngage using the email address and password combination or using the **Sign in with Google** button.
If you want to set up this method, perform the following steps:
1. On the **Login** tab, click **Single Sign On (SSO)only**.
2. Click **Configure SSO**.\
 To proceed with the next steps, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
# Single Sign-On (SSO)
Source: https://moengage.com/docs/user-guide/settings/account/security/single-sign-on-sso
Set up Single Sign-On (SSO) in MoEngage to let team members access the dashboard using your organization's central identity provider (IdP).
Single Sign-On (SSO) is a system that allows you to use one set of login credentials to access multiple applications without having to re-enter their credentials for each individual application. With SSO, you can easily access the MoEngage dashboard using your organization's central identity provider (IdP).
## Advantages of SSO
The advantages of using SSO include:
* **Simplified user experience**: SSO eliminates the need for users to remember and manage multiple usernames and passwords for different applications, making the login process much easier and faster.
* **Reduced password fatigue**: By consolidating credentials, SSO reduces the burden on users to remember and manage numerous passwords, which can lead to security risks and frustration.
* **Enhanced security**: Centralized authentication with SSO allows for more effective security controls, such as stronger password policies and multi-factor authentication, and simplifies the process of managing user access and permissions.
* **Improved productivity**: SSO allows users to spend less time on login processes and more time on core work tasks, leading to increased productivity and efficiency.
* **Reduced IT costs**: SSO streamlines user access management, reducing the workload for IT teams and minimizing the need for password resets and support calls, leading to cost savings.
## SSO Configuration
MoEngage supports SSO using Security Assertion Markup Language (SAML) 2.0 and acts as an SSO service provider (SP). SAML is an industry-standard protocol that enables user authentication delegation similar to OAuth 2.
Upon login, you are redirected to your internal or external SSO system for authentication and then returned to MoEngage when the response is verified.

> [!NOTE]
>
> * Contact your organization's IT team to set up SSO to log in to the MoEngage dashboard.
> * Only administrators can enable SSO for a workspace, which allows their teammates to log in securely using the identity provider credentials.
> * To configure SSO, you need an Admin role with the **Setup & manage** permission for the **Login Settings** component.\
> Note: The **Login Settings** is now renamed to **Security Settings**.
# Identity Providers (IdPs)
MoEngage uses Identity Providers (IdPs) to simplify and centralize user login. This allows you to securely access MoEngage services using SSO based on the SAML 2.0 standard. MoEngage supports the following IdPs currently:
* Okta
* Onelogin
* Azure (Microsoft Entra ID)
* Google Admin
* Other (you can configure other IdPs, provided they are SAML 2.0 compliant, including JumpCloud)
To enable SSO in the MoEngage dashboard, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Security**. 
2. On the Security page, click the **Login** tab.
3. Click **Single Sign On (SSO) only**.
4. Under **Single sign on**, click **Configure SSO**.  The **Configure SSO** dialog box appears.
5. In the **Identity Provider** list, select your identity provider.  Now, you must switch to that specific IdP admin console to configure the SSO settings and ensure the SSO integration between MoEngage and the selected IdP functions as intended.
> [!NOTE]
>
> If your preferred identity provider is not available in the **Identity Provider** list, you can select *Other* to configure your SSO. This function works with any SAML 2.0-compliant provider.
> [tab] Configure Okta SSO
>
> To set up SSO with Okta, perform the following steps:
>
> 1. Navigate to the **Okta Admin Console**.
> 2. On the left navigation menu, click **Applications** > **Applications**. 
> 3. On the **Applications** page, click **Create App Integration**.  \
> The Create a new app integration pop-up window appears.
> 4. Click the **SAML 2.0** option and then click **Next**.  The Create SAML integration page appears. You are taken to the first step, **General Settings**, to define your app. 
> 5. Enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | App name | Yes | Type your app name. |
> | App logo | Optional | Upload an image file (typically PNG, JPG, or GIF) to serve as your application icon. **Note**: The image file must be smaller than 1 MB. |
> | App visibility | Optional | Select the **Do not display application icon to users** check box adjacent to **App Visibility** to hide the application icon from the users. |
> 6. Click **Next.** You will move to the second step, **Configure SAML**, to define the SAML settings.
> 7. On the **Configure SSO** dialog box in the MoEngage dashboard, copy the **Single sign-on URL** and **Audience URI (SP Entity ID)**. 
> 8. Under **SAML Settings**, enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | Single Sign-On URL | Yes | This URL receives the SAML assertion (the authentication response) from Okta to MoEngage. Paste the URL copied from the MoEngage dashboard. |
> | Audience URI (SP Entity ID) | Yes | This URL informs Okta about the specific application (MoEngage) for which the authentication assertion is intended. Paste the URI copied from the MoEngage dashboard. **Note**: In this box, you can add multiple entity IDs from different workspaces, separated by commas. |
> | Name ID format | Yes | Select *EmailAddress*. |
> |  |
> 9. Scroll to the end of the page and click **Next**. You are taken to the third step, **Feedback**.
> 10. Select the **This is an internal app that we have created** check box adjacent to the **App type**. 
> 11. Click **Finish**. You must now generate the **SAML Signing Certificates** to connect your app to Okta.
> 12. By default, you are on the **Sign On** tab. Scroll to the end of the page, and under **SAML Signing Certificates**, find the **Status** marked as *Active* to download the certificate.
> 13. Click the **Actions** arrow in the **Actions** column.
> 14. Click **Download certificate**.  The metadata will be downloaded in an XML file.
> 15. Upload the downloaded XML file in the **Enter XML Configuration** box on the **Configure SSO** dialog box of the MoEngage dashboard.
> 16. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 17. Click **Configure**.  The Alert pop-up window will appear, prompting you to review the instructions properly.
> 18. Select the **Send email to the users of this workspace** check box to notify all users about your workspace's Single Sign-On (SSO) enablement.
> 19. Click **Done**.  The SSO configuration is now successfully completed. You can see the Okta SSO on the **Login** tab. 
> [tab] Configure Onelogin SSO
>
> To set up SSO with Onelogin, perform the following steps:
>
> 1. Navigate to the **Onelogin Admin Console**.
> 2. Click **Administration** next to your profile in the upper-right corner. 
> 3. Click **Applications** > **Applications**. 
> 4. On the Application page, click **Add app**.  The Find Applications page appears.
> 5. In the **Search** box, type SAML, scroll through the page, and click **SAML Test Connector (IdP)**.  The Add SAML Test Connector (IdP) page appears.
> 6. In the **Display Name** box, type the SAML name being tested. (Optional)
> 7. Click **Save**.  Your SAML is now successfully added, and the SAML Test Connector (IdP) page appears.
> 8. Click **Configuration** on the left navigation menu. 
> 9. On the **Configure SSO** dialog box in the MoEngage dashboard, copy the **Audience, ACS (Consumer) URL Validator**, and **Single Logout Url**. 
> 10. In the **Application details** section, enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | Audience | Yes | This URL specifies the intended recipient of the SAML assertion. Paste the audience copied from the MoEngage dashboard. |
> | ACS (Consumer) URL Validator | Yes | This URL adds an additional security to ensure MoEngage only accepts SAML assertions. Paste the URL validator copied from the MoEngage dashboard. |
> | ACS (Consumer) URL | Yes | This URL receives and processes the SAML authentication data for MoEngage from Onelogin. **Note**: Paste the **ACS (Consumer) URL Validator** you copied from the MoEngage dashboard in the **ACS (Consumer) URL** box. |
> | Single Logout URL | Yes | This URL allows for single logout functionality. |
> |  | | |
> 11. Click **Save**. Your SAML configuration is now successfully updated. 
> 12. In the upper-right corner, click the **More Actions** arrow and select **SAML Metadata**. \
> The metadata will be downloaded in an XML file.
> 13. Click **Upload** to upload the downloaded XML file on the **Configure SSO** dialog box in the MoEngage dashboard.
> 14. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 15. Click **Configure**.  The Alert pop-up window will appear, prompting you to review the instructions properly.
> 16. Select the **Send email to the users of this workspace** check box to notify all users about your workspace's Single Sign-On (SSO) enablement.
> 17. Click **Done**.  The SSO configuration is now successfully completed. You can see Onelogin SSO on the **Login** tab. 
> [tab] Configure Microsoft Azure SSO
>
> To set up SSO with Azure, perform the following steps:
>
> 1. Navigate to the **Azure Admin Console**.
> 2. On the Azure services page, click **Microsoft Entra ID**. 
> 3. On the Overview page, go to the left navigation menu and click **Manage** > **Enterprise** **applications**. 
> 4. On the Enterprise applications | All applications page, click **+ New application**. 
> 5. On the Browse Microsoft Entra Gallery page, in the search box, type **SAML Toolkit.**
> 6. Click the **Microsoft Entra SAML Toolkit** tile and create the application.  The created application is listed on the **Enterprise applications**| **All applications** page.
> 7. In the **Search by application name or object ID** box, type the name of the application that you created and select the application. \
> Your created application appears.  Now, you must configure SSO for the application you created.
> 8. On your opened application page, go to the left navigation menu and click **Manage** > **Single sign-on**.  The SAML-based Sign-On configuration page for your created application appears. 
> 9. Move to the first step, **Basic SAML Configuration**, to define your metadata.
> 10. In the **Basic SAML Configuration** section, click **Edit** in the upper-right corner. The **Basic SAML Configuration** pane appears on the right side. 
> 11. On the **Configure SSO** dialog box in the MoEngage dashboard, copy the **Identifier (Entity ID)** and the **Reply URL (Assertion Consumer Service URL)**. **Note**: Copying the **Sign on URL** is optional and generally not recommended. 
> 12. In the **Basic SAML Configuration section**, enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | Identifier (Entity ID) | Yes | This URL allows MoEngage to verify authentication requests from Azure, ensuring secure and seamless logins. Paste the ID copied from the MoEngage dashboard. |
> | Reply URL (Assertion Consumer Service URL) | Yes | This URL receives and processes the SAML authentication data for MoEngage from Azure. Paste the reply URL copied from the MoEngage dashboard. |
> | Sign on URL | Optional and generally not recommended. | This URL is the entry point from Azure that triggers the SAML SSO process to access MoEngage. Paste the sign-on URL copied from the MoEngage dashboard. |
> |  | | |
> 13. Click **Save**.
> 14. Your SSO configuration has been successfully saved. To download the XML file, move to the third step, **SAML Certificates**.
> 15. In the **SAMLCertificates** section, click **Download** adjacent to the **Federation Metadata XML**.  The metadata will be downloaded in an XML file.
> 16. Click **Upload**to upload the downloaded XML file on the **Configure SSO** dialog box in the MoEngage dashboard.
> 17. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 18. Click **Configure**.\
>  The Alert pop-up window will appear, prompting you to review the instructions properly.
> 19. Select the **Send email to the users of this workspace** check box to notify all users about your workspace's Single Sign-On (SSO) enablement.
> 20. Click **Done**.  The SSO configuration is now successfully completed. You can see the Azure SSO on the **Login** tab. 
> [tab] Configure Google Admin SSO
>
> To set up SSO with Google Admin, perform the following steps:
>
> 1. Navigate to the **Google Admin Console**.
> 2. On the left navigation menu, click **Apps** > click **Web and mobile apps**. 
> 3. Click the **Add app** arrow and click **Add custom SAML** **app**.  You are taken to the first step, **App details**, to define your app.
> 4. On the **App details** page, enter the following details:
>
> | Field | Required | Description |
> | - | - | - |
> | App name | Yes | Name of your SAML application. |
> | Description | Yes | Description of your SAML application configuration. |
> | Upload logo | optional | Upload an image file (typically PNG, JPG, or GIF) to serve as your application icon. **Note**: The image file must be smaller than 4 MB. |
>
> 
> 5. Click **Continue**. You are taken to the second step, **Google Identity Provider details**.
> 6. Under **Option 1: Download IdP metadata**, click **Download Metadata**.\
> The metadata will be downloaded in an XML file.
> 7. Click **Continue**.  You are taken to the third step, **Service provider details**.
> 8. On the **Configure SSO** dialog box in the MoEngage dashboard, copy the **ACS URL** and **Entity ID**. 
> 9. On the **Service provider details** page, enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | ACS URL | Yes | This URL receives and processes the SAML authentication data for MoEngage from Google Admin. Paste the URL copied from the MoEngage dashboard. |
> | Entity ID | Yes | A unique identifier for your application. Paste the ID copied from the MoEngage dashboard. |
> | Start URL | Optional | Leave this blank. |
> 10. Select the **Signed response** check box to sign the entire SAML response, which includes the assertion and other protocol-related information.
> 11. In the **Name ID format** list, select *Email*.
> 12. Click **Continue**.  You are taken to the fourth step, **Attribute mapping**. Here, you can map optional user properties (for example, first name, last name, and email address).
> 13. Click **Finish**.  Your SAML settings are updated.
> 14. On the **Configure SSO** dialog box in the MoEngage dashboard, click **Upload** to upload the XML file that you downloaded in step 6.
> 15. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 16. Click **Configure**.  The Alert pop-up window will appear, prompting you to review the instructions properly.
> 17. Select the **Send email to the users of this workspace** check box to notify all users about your workspace's Single Sign-On (SSO) enablement.
> 18. Click **Done**.  The SSO configuration is now successfully completed. You can see Google SSO on the **Login** tab. 
> [tab] Configure JumpCloud SSO
>
> JumpCloud does not appear as a named option in the **Identity Provider** list on the MoEngage dashboard. Configure it using the **Other** option instead.
>
> JumpCloud grants application access by user group, so create your user and a user group before you configure SSO.
>
> ### Step 1: Create a User
>
> 1. Navigate to the **JumpCloud Admin Portal**.
> 2. On the left navigation menu, click **Identity Management** > **Users**.
> 3. Click **+ Users**, and create your users individually, or use the import option to add users from a CSV file.
>
> 
>
> 4. Enter the user's details, and click **Save User**.
>
> 
>
> ### Step 2: Create a User Group
>
> 1. On the left navigation menu, click **Identity Management** > **User Groups**.
> 2. Click **+ User Group**.
> 3. In the **Name** box, type a name for the group.
> 4. Click the **Users** tab, and add the user you created in [Step 1](/docs/user-guide/settings/account/security/single-sign-on-sso#step-1-create-a-user).
> 5. Click **Save Group**.
>
> 
>
> ### Step 3: Create the SSO Application in JumpCloud
>
> 1. On the left navigation menu, click **Access** > **SSO Applications**.
> 2. On the **Configured Applications** page, click **+ Add New Application**.
> 3. In the search box, type SAML 2.0, and select it.
> 4. Proceed through the setup options with the default selections until you reach the **Enter General Info** step.
> 5. Enter a **Display Label**, **Description**, and (optionally) a logo for your application, and click **Save Application**.
> 6. Click **Configure Application**.
>
> 
>
> ### Step 4: Configure the SAML Settings
>
> On the **Configure SSO** dialog box in the MoEngage dashboard, in the **Identity Provider** list, you must select **Other**, since JumpCloud does not appear as a named option in the list.
>
> 
>
> Then, on the **SSO** tab of your JumpCloud application, enter the following details:
>
> 1. In the **SP Entity ID** box, paste the **Issuer** value copied from the **Configure SSO** dialog box in the MoEngage dashboard.
> 2. Under **ACS URLs**, in the **Default URL** box, paste the **Assertion Consumer Service** URL copied from the MoEngage dashboard.
>
> 
> 3. In the **SAMLSubject NameID** list, select email.
> 4. In the **SAMLSubject NameID Format** list, select `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`, which corresponds to the **Email Address** format shown on the MoEngage dashboard.
> 5. In the **Login URL** box, enter your MoEngage dashboard URL.
> 6. Select the **Declare Redirect Endpoint** and **Send failure response to the Service Provider** checkboxes.
> 7. Click **Save**.
>
> 
>
> > [!WARNING]
> >
> > Select both the **Declare Redirect Endpoint** and **Send failure response to the Service Provider** checkboxes. If you leave either checkbox cleared, uploading the SAML metadata XML file in [Step 5](/docs/user-guide/settings/account/security/single-sign-on-sso#step-5-exchange-metadata) returns an error.
>
> ### Step 5: Exchange Metadata
>
> 1. On the **SSO** tab of your JumpCloud application, scroll to **Configuration Settings** > **JumpCloud Metadata**, and click **Export Metadata** to download the SAML metadata XML file.
> 2. On the **Configure SSO** dialog box in the MoEngage dashboard, click **Upload** to upload the downloaded XML file.
> 3. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 4. Click **Configure**. The Alert pop-up window will appear, prompting you to review the instructions properly.
>
> 
> 5. Select the **Send email to the users of this workspace** check box to notify all users about your workspace's Single Sign-On (SSO) enablement.
> 6. Click **Configure**. The SSO configuration is now successfully completed. You can see the JumpCloud SSO on the **Login** tab.
>
> ### Step 6: Assign the User Group to the Application
>
> 1. On your JumpCloud application, click the **User Groups** tab.
> 2. Select the user group you created in [Step 2](/docs/user-guide/settings/account/security/single-sign-on-sso#step-2-create-a-user-group) so its members can access MoEngage through this application.
> [tab] Configure Other SSO
>
> > [!NOTE]
> >
> > If you are using an IDP that is not listed above, you can select the *Other* option from the **Identity Provider** list.
>
> To set up SSO with the **Other** option, perform the following steps:
>
> 1. Complete the necessary setup within your IdP admin console.
> 2. Add the metadata values displayed on the **Configure SSO** dialog box in the MoEngage dashboard to the corresponding fields in your IdP admin console.
> 3. Download and save the SAML metadata file generated by your IdP.
> 4. To upload the XML file you downloaded in the **Configure SSO** section of the MoEngage dashboard, click **Upload**.
> 5. By default, the **Update the same config for Test Environment** check box is selected. When it is selected, the configuration is applied to both the test and live environments. Clear the check box if you want the configuration to be applied only to the live environment.
> 6. Click **Configure**.  The Alert pop-up window will appear, prompting you to review the instructions properly.
> 7. Select the **Send email to the users of this workspace** check box.
> 8. Click **Done**.  The SSO configuration is now successfully completed. 
If you see an error while logging in via SSO, check the FAQ section below for common issues and fixes, or contact the MoEngage Support team for help.
# FAQs
> [accordion] Facing an issue while logging in?
>
> 
>
> **_Authentication Failed_**
>
> This generally happens when the SAML authentication with the Identity Provider fails. Please contact your identity provider for details.
>
> **_Persistent Error_**
>
> MoEngage supports the admin login using an email id - password combination. The Admin can go back to the Single Sign On screen (Go to settings > Security Settings) and disable SSO.
> [accordion] What if the user is not able to log in via SSO?
>
> MoEngage allows you to log in to your last-used workspace by default. If it is not accessible for any reason, you can access other workspaces using the [Login to a different workspace](/docs/user-guide/getting-started/initial-setup/log-in-to-moengage#log-into-a-different-workspace) flow.
> [accordion] Does the email address need to match between the IdP and MoEngage?
>
> Yes. Use the same email address in your organization's Identity Provider (IdP) and in MoEngage. SSO login fails if the addresses do not match.
> [accordion] Facing an issue while uploading the config file?
>
> ### 
>
> This generally happens when the uploaded XML file is invalid. Try again with the correct XML file. If the issue persists, check with your identity provider.
> [accordion] Which identity providers are supported by MoEngage?
>
> MoEngage supports all identity providers (IdPs) that support SAML 2.0
> [accordion] Can different identity providers be used for different workspaces?
>
> Yes, you can configure different identity providers for different workspaces. For example, you can use Okta to configure SSO for one workspace and Google for another. You can also have different identity providers for test and live environments.
> [accordion] Which identity provider (in case of multiple IdPs) will the user be redirected to after logging in?
>
> The user will be redirected to the IDP associated with the most recent workspace that they used before the last session ended.
> [accordion] Is there a test environment using which SSO implementation can be tested?
>
> You can use the test environment to test the SSO setup and verify that everything works as desired. Once you have verified it on the test, you will need to set up SSO again on the live environment. On the other hand, SSO gets configured to the test environment automatically if you configure it first in the live environment.
> [accordion] What happens if the user exists in the identity provider’s directory but not in MoEngage?
>
> The user will not be able to log in to MoEngage if the user is not a part of the workspace in which the SSO has been enabled.
> [accordion] What happens if the user exists in the identity provider’s directory but does not have access to the SSO workspace linked with MoEngage?
>
> The user will see the Auth Status Failure error on the MoEngage Dashboard while being redirected back from the identity provider.
> [accordion] Who can enable/disable SSO for a workspace on MoEngage?
>
> The SSO can only be enabled / disabled / edited by a user with access to the *Setup & Manage* permission under *Login Settings*.
>
> The user with the necessary permissions can go to *Settings -> Login -> Authentication,* select *Single Sign On (SSO) Only,* and perform the necessary action.
>
> 
> [accordion] What happens if the SSO is not enabled for one of the workspaces or if different identity providers have been used for different workspaces?
>
> If SSO is not enabled for one of the workspaces or if different identity providers have been used for the workspaces, the user will need to re-authenticate while switching between them.
> [accordion] What happens if the user wants to seamlessly switch between different workspaces after enabling SSO?
>
> To switch between different workspaces without re-authenticating seamlessly, the user will need to enforce SSO on all the workspaces with the same identity provider in both the Test and Live environments.
> [accordion] Can we configure SSO to allow a specific set of users to log in using SSO and others to log in with ID and Password?
>
> Only the admins have the option to log in using their MoEngage credentials once SSO is enabled. All other users must log in through SSO.
> [accordion] When using Microsoft Azure, what should be the value of the User Principal Name (UPN) attribute?
>
> UPN consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). The prefix is joined with the suffix using the "@" symbol. For example, "[someone@example.com](mailto:someone@example.com)". A UPN must be unique among all security principal objects within a directory. Read more about it [here](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/plan-connect-userprincipalname).
> [accordion] What are some of the common issues faced by the users?
>
> Here are some of the common issues faced and their resolutions.
>
> | Error | Resolution |
> | - | - |
> | *Incorrect Cluster URL* | Ensure that the correct login URL (as per your data center) is used to log into your MoEngage Dashboard. For more information, refer to [Data Centers](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
> | *Incorrect Name ID Format* | The Name ID Format should be in the format mentioned below: *urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress* |
> | *Missing Single Sign On URL* | The Single Sign On URL should be present with a valid value in the SAML metadata file. |
> | *NameIDFormat* | ``urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress``urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified``urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName``urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName``urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos``urn:oasis:names:tc:SAML:2.0:nameid-format:entity``urn:oasis:names:tc:SAML:2.0:nameid-format:persistent``urn:oasis:names:tc:SAML:2.0:nameid-format:transient`` |
> [accordion] Does two-factor authentication remain enabled even after enabling SSO authentication?
>
> Yes, two-factor authentication remains enabled even after you enable SSO for a workspace.
> [accordion] Contact Support
>
> If the FAQs above don't resolve your issue, contact the MoEngage Support team. For more information, refer to [Raise a Support Ticket Through MoEngage Dashboard](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
# System for Cross-domain Identity Management (SCIM)
Source: https://moengage.com/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim
Automate user provisioning and role management in MoEngage with SCIM integration. Sync users from your identity provider automatically.
# Introduction
System for Cross-domain Identity Management (SCIM) is an open standard that automates the exchange of user identity information between your Identity Provider (IdP) and MoEngage. SCIM integration streamlines user management by automatically synchronizing provisioning, role updates, and access revocation across all platforms.
## Operations Supported
SCIM enables the following user management operations that you can perform from your IdP:
* **Create users**: Provision new users in MoEngage.
* **Update users**: Automatically sync role updates.
* **Get users**: Retrieve a list of MoEngage users.
* **Revoke access**: Revoke user access.
## Advantages of SCIM
The following are the advantages of providing SCIM:
* **Automated lifecycle management**: Automatically manage user provisioning.
* **Centralized role assignmen**t: Assign MoEngage roles, such as default and custom roles, directly from your organization's identity provider.
* **Improved efficiency**: This process eliminates the manual overhead of inviting users individually to the MoEngage workspace.
# Identity Providers (IdPs)
MoEngage utilizes Identity Providers to simplify and centralize logins. MoEngage supports SCIM provisioning based on the SCIM 2.0 standard, so it works with any identity provider that supports the protocol. This guide provides detailed configuration steps for the following platforms:
* Okta
* Azure (Microsoft Entra ID)
* JumpCloud
> [!TIP]
>
> **Prerequisites**
>
> Before you begin the configuration, ensure you have the following:
>
> * A working single sign-on (SSO) configuration for your MoEngage workspace.
> * An Admin role with **Setup & manage** permissions for the **Security Settings** component.\
> **Note**: The **Login Settings** component is renamed to **Security Settings**.
> * Google Chrome browser—other browsers may truncate or corrupt metadata and XML strings, which can result in integration failures.
> * Complete the SSO configuration before enabling SCIM. For more information, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
> [tab] Okta
>
> # Configure SCIM in Okta
>
> ## Step 1: Locate and Verify the SSO Application
>
> To verify the SSO configuration, perform the following steps:
>
> 1. Navigate to the **Okta Admin Console**.
> 2. On the left navigation menu, go to **Applications** > **Applications**.
> 3. On the **Applications** page, find your application in the list or use the **Search for people, apps, and groups** box to find it.
> 4. Click the application name from your list that you want to configure SCIM for. 
> 5. Click the **General** tab.
> 6. Scroll to the **SAML Settings** section, and verify that the SAML configuration details match the metadata from your MoEngage workspace. 
>
> ## Step 2: Enable SCIM in Okta App Settings
>
> Now, to enable SCIM in Okta, perform the following steps:
>
> 1. Repeat steps 2 through 5 as mentioned in [Step 1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-1-locate-and-verify-the-sso-application).
> 2. In the **App Settings** section, click **Edit** in the right corner.
> 3. Click the **SCIM** radio button, and then click **Save**.  The **Provisioning** tab is displayed next to the **Sign On** tab. 
>
> ## Step 3: Configure SCIM in MoEngage and Generate Token
>
> To configure SCIM on MoEngage and generate a token, perform the following steps:
>
> 1. In the left navigation menu on the MoEngage workspace, click **Settings** > **Account** > **Security**.
> 2. On the **Security** page, click the **Login** tab.
> 3. Click **Single Sign On (SSO) only**.
> 4. Scroll to the **Automate user provisioning** section.
> 5. Turn the **Automate user provisioning** toggle on.
>
> 
>
> \
> The **Configure provisioning method** dialog box appears.
> 6. Click **SCIM configuration** as your configuration type.
>
> 
> 7. Copy the **Base Connector URL** and save it (to use in [Step 4](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-4-configure-scim-on-okta)).
> 8. In the **Default role** list, select the required role (Default or Custom role).
> 9. In the **Expiry Date** field, select the expiry date for the SCIM access token.\
> **Note**: MoEngage recommends setting an **Expiry date** period of one year.
> 10. Click **Save**.\
> The **Save your configuration** dialog box appears, prompting you to confirm your configuration.
> 11. Click **Confirm**.\
> The **Successfully generated SCIM token** message and the **Generate access token** dialog box appear. **Note**: Copy the token immediately; it is only shown once.
> 12. Click **Okay**.
>
> 
>
> ## Step 4: Configure SCIM on Okta
>
> To configure SCIM on Okta, perform the following steps:
>
> 1. Return to the **Okta Admin Console** and click the **Provisioning** tab.
>
> 2. On the left navigation pane, click **Integration**, and then click **Edit**.
>
> 3. Enter the connection details:
> 1. **SCIM connector base URL**: Paste the URL copied from the MoEngage workspace in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-scim-in-moengage-and-generate-token).
> 2. **Unique identifier field for users**: Type **email**.
>
> 4. In the **Configure Supported Provisioning Actions** section, select the appropriate check boxes to define the data flow. You can enable all five to automate both individual users and groups, or select them based on the following requirements:
> * **Import New Users and Profile Updates**: Select this to bring existing users from MoEngage into Okta.
> * **Push New Users**: Select this to automatically create a MoEngage user when a new user is assigned to the application in Okta.
> * **Push Profile Updates**: Select this to sync attribute changes, such as **Role** updates, from Okta to MoEngage.
> * **Push Groups**: Select this to sync Okta groups and their user lists to MoEngage.
> * **Import Groups**: Select this to fetch existing groups from MoEngage into Okta.
>
> 5. In the **Authentication Mode** list, click **HTTP Header**.
>
> 6. In the **HTTP Header** section, in the **Authorization** box, paste the generated access token copied in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-scim-in-moengage-and-generate-token) from the MoEngage workspace.
>
> 7. Click **Test Connector Configuration**.  A **Test Connector Configuration** dialogue box appears (this process may take up to 30 seconds). The connector configured successfully message appears to review the following list of provisioning features detected in your connector:
> * **User Import** and **Import Profile Updates**: This confirms that Okta fetches user data from MoEngage.
> * **Create Users** and **Update User Attributes**: This confirms that Okta sends new users and profile changes to MoEngage.
> * **Push Groups** and **Import Groups**: This confirms that group memberships and roles are synchronized.
>
> 8. Click **Close** and then **Save.**  
>
> > [!NOTE]
> >
> > If you do not select **Push New Users**, MoEngage does not create users for the newly assigned users, and they won't be able to sign in. You can select **Push Groups** to automatically assign specific permissions to a group of users in MoEngage based on their Okta details, eliminating the need for manual user management.
>
> ## Step 5: Enable Provisioning Actions
>
> To ensure identity data flows correctly from Okta to MoEngage, you must enable Create, Update, and Deactivate provisioning actions within the To App settings. To enable the provisioning actions, perform the following steps:
>
> 1. On the **Provisioning** tab, in the left navigation pane, under **Settings**, click **To App**.
> 2. Click **Edit** next to the **Provisioning to App** section.
> 3. Select the **Enable** check box for the following actions:
> * **Create Users**: Grant Okta permission to create users on MoEngage.
> * **Update User Attributes**: Sync profile updates from Okta to MoEngage.
> * **Deactivate Users**: Revoke MoEngage access immediately when a user is unassigned in Okta. 
>
> ## Step 6: Create Attribute Mappings
>
> Grant specific write permissions in Okta and map the role attribute to help ensure that users are provisioned with the correct permissions in MoEngage. You must create roles in MoEngage to assign them to users correctly. This attribute mapping helps ensure that users receive their intended access levels rather than the **Default** role that was configured earlier.
>
> ### Step 6.1: Configure Profile Attributes
>
> > [!NOTE]
> >
> > **Information**
> >
> > MoEngage prioritizes attributes passed via the external namespace. If multiple role attributes are configured, MoEngage resolves them in the following order:
> >
> > * **extension.role (urn:ietf:params:scim:schemas:extension:moengage:2.0:User.role):** Attributes defined with the 2.0 namespace (Highest Priority).
> > * **standard role.role**: Attributes defined under the role namespace. (This parameter will be deprecated in a future release.
> > * **Default Role**: If no roles are passed via SCIM, the system uses the default role configured in the MoEngage workspace ([Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-scim-in-moengage-and-generate-token)).
>
> To configure the custom role attribute, perform the following steps:
>
> 1. Navigate to the **Okta Admin Console**.
> 2. On the left navigation menu, click **Directory** > **Profile Editor**.\ 
> 3. On the **Profile Editor** page, find your application in the list or use the **Search for people, apps, and groups** box to find and select the appropriate application from your list. 
> 4. Under the **Attributes** section, click **+ Add Attribute**.  The **Add Attribute** dialogue box is displayed.
> 5. In the **Add Attribute** dialogue box, configure the following details:
> 1. In the **Data type**list, click **string**.
> 2. In the**Display name**box, enter role (for example, MoEngage role).
> 3. In the **Variable name** box, enter role (any value can be defined by the client).
> 4. In the **External name** box, enter role (This is the specific name passed within the schema).
> 5. In the **External namespace,** enter *urn:ietf:params:scim:schemas:extension:moengage:2.0:User* 
> 6. Scroll down and set the following:
> 1. **Attribute required**: Select the **Yes** check box to enforce that a role is provided during the user invitation process in Okta.\
> **Note**: This must be set to **Yes**. If a user invites an email without a role, MoEngage needs **Attribute required** to be active so it can fetch the default role from the MoEngage workspace. This ensures both default and custom role scenarios work during testing.
> 2. **Attribute type:**
> * **For Individual Assigning**: Select the **Personal** radio button.
> * **For Group Assigning (Bulk Update)**: Select the **Group** radio button.
> 7. Click **Save**.  The MoEngage **Role** is now established in the application's attribute list.
>
> ### Step 6.2: Group Creation and Role Updates
>
> To update roles effectively for groups, perform the following sequence:
>
> ### Step 6.2.1: Create a Group
>
> 1. Navigate to the **Okta Admin Console**.
> 2. On the left navigation menu, click **DirectoryGroups**.
> 3. Click **Add group**.  The **Add group** dialog box appears.
> 1. In the **Name** box, enter a group's name.
> 2. In the **Description** box (optional), provide a description.
> 4. Click **Save**. 
> 5. After the group is created, click it and copy the Group ID from the browser's URL (this is the unique identifier required for mapping logic). 
>
> ### Step 6.2.2: Assign Users
>
> 1. Within the **Groups** page, click **Assign People**. 
> 2. Click the **+** (plus) icon next to each user whose MoEngage roles need to be updated or assigned via this group. 
>
> ### Step 6.2.3: Update Okta User Property
>
> 1. Navigate to **Directory** > **Profile Editor**.  On the **Profile Editor** page, the **All** filter is selected by default.
> 2. Click the **Okta** filter and click the **Okta User (default)** profile. 
> 3. Scroll to the end of the page and verify whether the role attribute created in [Step 6.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-6-1-configure-profile-attributes) exists. If the attribute is missing, click **+ Add Attribute**.
> 4. In the **Add Attribute** dialog box, add a role attribute with the following settings:
> 1. In the **Data type** list, click string.
> 2. In the **Display name** box, enter role.
> 3. In the **Variable name** box, enter role.
> 4. In the **Description** (optional) box, enter a description for the role. 
> 5. In the **User permission** section, select the **Read-Write** radio button.
> 5. Click **Save**. 
>
> ### Step 6.2.4: Update the Application Attribute Mapping
>
> 1. In the **Profile Editor**, click the **Apps** filter and find your application.
> 2. Click **Mappings**. 
> 3. Select the **Okta User to** \[**Your Application Name**] (for example, **Okta User to DC 03**) tab. 
> 4. Scroll to the **role** attribute at the bottom of the list.
> 5. In the **expression** box, enter the role attribute following logic to map Okta groups to MoEngage roles (isMemberOfGroup("group_id") ? "Admin" : "User").
> 1. **group_id**: Paste the ID copied in [Step 6.2.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-6-2-1-create-a-group)
> 2. **Role**: The specific role name as defined in your MoEngage workspace.
> 6. Confirm and paste that the role attribute details (namespace and external name) for the role attribute match the mandatory values defined in [Step 6.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-6-1-configure-profile-attributes).
> 7. Click **Save Mappings** and then click **Apply updates**. 
>
> ## Step 7: Push Groups
>
> Use this option to bulk push entire groups to MoEngage. This triggers the creation of all group members in the MoEngage workspace at once.
>
> 1. Click the **Push Groups** tab.
> 2. Click **+ Push Groups** > **Find groups by name**. 
> 3. Under **Push groups by name**, in the **Enter a group to push** field, enter the name of the group assigned to the MoEngage workspace.
> 4. Ensure the **Push group memberships immediately** check box is selected. 
> 5. Click **Save**. Okta initiates a background job to sync all members.
>
> ## Step 8: Final Force Synchronization
>
> Manual force sync ensures that mapped properties and roles are updated instantly across all assigned users.
>
> 1. Click the **Provisioning** tab, and in the left navigation pane under **Settings**, click **To App**.
> 2. Scroll down to the **Attribute Mappings** section.
> 3. Click **Force Sync**.  This initiates a global synchronization, pushing the newly mapped attribute data immediately and ensuring global attributes are in sync. Individual user sync via the **Assignments** tab is not required separately as Force Sync covers all assigned users.
>
> ## Step 9: Validation
>
> Verify the following in the MoEngage workspace (**Settings** > **Account** > **Team Management**):
>
> * **User Invitation**: Confirm the user is successfully invited and the status is Joined.
>
> 
> * **Default Role Update**: Confirm that if no specific role was passed from Okta, the system correctly assigned the Default Role configured in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-scim-in-moengage-and-generate-token).
> * **Role Accuracy**: Confirm that the specific role sent from Okta (based on group membership logic) matches the assigned role in the workspace.
>
> 
> [tab] Azure
>
> # Configure SCIM in Azure
>
> ## Step 1: Locate and Verify the SSO Application
>
> To successfully configure SCIM provisioning, you must first ensure you have an active Enterprise Application in Microsoft Entra ID.
>
> 1. Before enabling SCIM, ensure you have successfully set up the SSO connection between MoEngage and Azure. For more information, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso).
> 2. To verify your enterprise application,
> 1. Navigate to the **Azure Admin Console**.
> 2. On the Azure services page, click **Microsoft Entra ID**. 
> 3. On the Overview page, go to the left navigation menu and click **Manage** > **Enterprise applications**. 
> 4. On the **Enterprise applications | All applications** page, find your application in the list or use the **Search by application name or object ID** box to find it and select the application name you want to configure from your list. 
>
> ## Step 2: Configure SCIM Provisioning in Azure
>
> You must enable automated user management by establishing a secure handshake between Microsoft Entra ID and the MoEngage API using the SCIM 2.0 protocol.
>
> ### Step 2.1: Activate SCIM in MoEngage and Generate Token
>
> To activate SCIM in MoEngage and generate a token, perform the following steps:
>
> 1. In the left navigation menu on the MoEngage workspace, click **Settings** > **Account** > **Security**.
> 2. On the **Security** page, click the **Login** tab.
> 3. Click **Single Sign On (SSO) only**.
> 4. Scroll to the **Automate user provisioning** section.
> 5. Turn the **Automate user provisioning** toggle on.
>
> 
>
> \
> The **Configure provisioning method** dialog box appears.
> 6. Click **SCIM configuration** as your configuration type.
>
> 
> 7. Copy the **Base Connector URL** and save it (to use in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-provisioning-credentials-in-azure)).
> 8. In the **Default role** list, select the required role.
> 9. In the **Expiry Date** field, select the expiry date for the SCIM access token.\
> **Note**: MoEngage recommends setting an **Expiry date** period of one year.
> 10. Click **Save**.\
> The **Save your configuration** dialog box appears, prompting you to confirm your configuration.
> 11. Click **Confirm**.\
> The **Successfully generated SCIM token** message and the **Generate access token** dialog box appear. **Note**: Copy the token immediately; it is only shown once.
> 12. Click **Okay**.
>
> 
>
> ## Step 3: Configure Provisioning Credentials in Azure
>
> To configure the provisioning credentials in Azure, perform the following steps:
>
> 1. Return to the Azure application, on the **Overview** page, go to the left navigation menu, and click **Manage** > **Provisioning**.
> 2. In the **Provisioning Mode**, click **Automatic**. 
> 3. Expand **Admin Credentials** and enter the following:
> 1. In the **Tenant URL** box, paste the **Base Connector URL** copied from the MoEngage workspace earlier.
> 2. In the **Secret Token** box, paste the **SCIM Access Token** generated in [Step 2.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-2-1-activate-scim-in-moengage-and-generate-token).
> 3. Click **Test Connection** to verify that Microsoft Entra ID can securely connect to the MoEngage API.\
> **Note**: A successful connection test automatically updates the SCIM status in your MoEngage workspace from *Inactive* to *Active*.
> 4. Click **Save** at the top. 
>
> ## Step 4: Configure Attribute Mappings
>
> > [!NOTE]
> >
> > **Information**
> >
> > To ensure MoEngage provisions users with the correct permissions, you must grant write permissions to Azure and map the custom role attribute. Since Microsoft Entra ID does not include a MoEngage-compatible "role" field by default, you must manually extend the attribute list before you can map the roles.
>
> ### Step 4.1: Create Attribute List
>
> To add the MoEngage role extension to the attribute list, perform the following steps:
>
> 1. Access the **Attribute Mapping** page using one of the following options:
> * In the **Provisioning** section of your Azure application, expand **Mappings** and click **Attribute mapping (Preview)**.  OR
> * From the left navigation, click **Attribute mapping (Preview)**.
> * Under the **Name** column, click **Provision Microsoft Entra ID Users**. 
> 2. Scroll to the end of the Attribute Mapping page and select the **Show advanced options** check box.
> 3. Click **Edit attribute list for (your app name)**. 
> 4. In the **Edit Attribute List** window, scroll to the bottom of the table to add a new row with the following technical values:
> * **Name**: Enter the attribute name. *urn:ietf:params:scim:schemas:extension:moengage:2.0:User:role*
> * **Type**: Click **String** in the drop-down list.\
> **Note**: Before entering the attribute name, verify if the MoEngage role extension already exists in the list. If you attempt to add an attribute name that is already present, Microsoft Entra ID will display an error stating that the attribute name must be unique.
> 5. Click **Save** at the top of the pane. 
> 6. Click \*\*Yes \*\*on the confirmation box.\
> After Microsoft Entra ID successfully updates the provisioning settings, the \*\*Updating user provisioning settings \*\*success message appears.
>
> ### Step 4.2: Map the User Role Attribute
>
> After the attribute is added to the list, you must map it using an expression to link Azure App Roles to MoEngage and perform the following steps:
>
> 1. On the **Attribute Mapping** page, click **Add New Mapping.** 
> 2. In the \*\*Edit Attribute \*\*section, configure the following details:
> 1. In the **Mapping Type**list, click **Expression**.
> 2. In the **Expression** box, type the expression **SingleAppRoleAssignment(\[appRoleAssignments**\
> **Note**: Type this expression manually. Copying and pasting may include hidden, unsupported characters that cause errors.
> 3. In the **Target Attribute** list, click the attribute that you created in [Step 4.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-4-1-create-attribute-list).
> 4. In the \*\*Apply this mapping \*\*list, click **Always**.
> 3. Click **OK**. 
> 4. Click **Save** at the top.
>
> ## Step 5: Role Creation
>
> Roles must be established at the global directory level before they can be assigned to users and synchronized with MoEngage.
>
> ### Step 5.1: Create App Roles
>
> To create the necessary roles that correspond with the MoEngage workspace permissions, perform the following steps:
>
> 1. Navigate to **Home** > **Microsoft Entra ID** > **Manage** > **App registrations**.
> 2. Click the **All Applications** tab and select your application. 
> 3. In the left navigation menu, click **Manage** > **App roles**.
> 4. Click the **+ Create app role**. 
> 5. Configure the following details:
> 1. In the **Display name box**, type the role name (for example, Analyst).
> 2. In the \*\*Allowed member types \*\*section, click the **(Users/Groups)** check box.
> 3. In the **Value** box, enter the MoEngage role value.\
> **Note**: When entering the Value for the role, ensure it matches the exact role name defined in your MoEngage workspace. Microsoft Entra ID uses this value to pass the correct permission data during the SCIM handshake.
> 4. In the **Description** box, type a brief description of the permissions this role provides.
> 5. Select the **Do you want to enable this app role?** check box.
> 6. Click **Apply** at the bottom of the pane. 
>
> ### Step 5.2: Assign App Roles to Users
>
> After the roles are created, you must assign them to specific users within the Enterprise application and perform the following steps:
>
> 1. Navigate to **Home** > **Microsoft Entra ID** > **Manage** > **Enterprise applications** and select your application. 
> 2. In the **Getting started** section, in the **Assign users and groups** tile, click the **Assign users and groups** link. 
> 3. Select the check box for the user you want to update and click the **Edit assignment** icon in the top menu bar. 
> 4. On the left side, under **Select a role**, click the **None Selected** link.\
> The **Select a role** dialog box pane appears on the right side. A list appears displaying the custom App Roles created in \[Step 5.1.]\(/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-5-1-create-app-roles)
> 5. Select the appropriate role from the list and click **Select**.\
> **Note**: Ensure you do not leave the role as Default Access. Microsoft Entra ID requires a specific role value to pass the correct permission data to MoEngage during the SCIM synchronization. 
> 6. Click **Assign** at the bottom of the **Edit Assignment** page.  After Microsoft Entra ID successfully updates the user, the *Application assignment succeeded* message appears in the upper-right corner.
> 7. To verify the assignment, click the user's name to open their **Overview** page. The **Basic info** section displays the user's **User principal name** and confirms that the number of **Assigned roles** is now updated. 
>
> ## Step 6: Synchronization
>
> Microsoft Entra ID automatic synchronization cycles can be inconsistent, often taking between 40 minutes and 1 hour to reflect changes. To push user profile updates or role changes to the MoEngage workspace immediately, use the Provision on demand feature.
>
> 1. Return to the Azure application, on the **Overview** page, go to the left navigation menu, and click **Manage** > **Provisioning**.
> 2. In the top menu bar, click **Provision on demand**. 
> 3. In the **Search for a user or group** box, type the name or email address of the user you assigned in [Step 5.2](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-5-2-assign-app-roles-to-users).
> 4. Select the user from the search results.
> 5. Click **Provision** at the bottom of the page. Microsoft Entra ID initiates an immediate "force push" of the user identity, including the custom MoEngage role mapping.\
> **Note**: After the process completes, a success message appears with details of the exported attributes. The SCIM status in your MoEngage workspace will now reflect these updates. 
>
> ## Step 7: Validation
>
> Verify the following in the MoEngage workspace (**Settings** > **Account** > **Team Management**):
>
> 1. **User Invitation**: Confirm the user is successfully invited and the status is Joined.
>
> 
> 2. **Default Role Update**: Confirm that if no specific role was passed from Microsoft Entra ID, the system correctly assigned the Default Role configured in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-provisioning-credentials-in-azure).
> 3. **Role Accuracy**: Confirm that the specific role sent from Microsoft Entra ID (based on app role mapping) matches the assigned role in the workspace.
>
> 
> [tab] JumpCloud
>
> # Configure SCIM in JumpCloud
>
> ## Step 1: Locate and Verify the SSO Application
>
> To verify the SSO configuration, perform the following steps:
>
> 1. Navigate to the **JumpCloud Admin Portal**.
> 2. On the left navigation menu, click **Access** > **SSO Applications**.
> 3. On the **SSO Applications** page, find your application in the list or use the search box to find it.
> 4. Click the application name from your list that you want to configure SCIM for.
> 5. Verify that the SAML settings on the application's SSO tab match the metadata from your MoEngage workspace.\
> **Note**: If you have not yet set up SSO with JumpCloud, refer to [Single Sign-On (SSO)](/docs/user-guide/settings/account/security/single-sign-on-sso) before you continue.
>
> ## Step 2: Configure SCIM in MoEngage and Generate Token
>
> To configure SCIM on MoEngage and generate a token, perform the following steps:
>
> 1. In the left navigation menu on the MoEngage workspace, click **Settings** > **Account** > **Security**.
> 2. On the **Security** page, click the **Login** tab.
> 3. Click **Single Sign On (SSO) only**.
> 4. Scroll to the **Automate user provisioning** section.
> 5. Turn the **Automate user provisioning** toggle on.
>
> 
>
> \
> The **Configure provisioning method** dialog box appears.
> 6. Click **SCIM configuration** as your configuration type.
>
> 
> 7. Copy the **Base Connector URL** and save it (to use in [Step 3](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-3-configure-scim-provisioning-in-jumpcloud)).
> 8. In the **Default role** list, select the required role (Default or Custom role).
> 9. In the **Expiry Date** field, select the expiry date for the SCIM access token.\
> **Note**: MoEngage recommends setting an **Expiry date** period of one year.
> 10. Click **Save**.\
> The **Save your configuration** dialog box appears, prompting you to confirm your configuration.
> 11. Click **Confirm**.\
> The **Successfully generated SCIM token** message and the **Generate access token** dialog box appear. **Note**: Copy the token immediately; it is only shown once.
> 12. Click **Okay**.
>
> 
>
> ## Step 3: Configure SCIM Provisioning in JumpCloud
>
> To configure SCIM provisioning in JumpCloud, perform the following steps:
>
> 1. Return to your JumpCloud application, and click the **Provisioning** tab.
>
> 2. In the **Base URL** box, paste the **Base Connector URL** copied from MoEngage in [Step 2](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-2-configure-scim-in-moengage-and-generate-token).
>
> 3. In the **Token Key** box, paste the SCIM access token generated in [Step 2](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-2-configure-scim-in-moengage-and-generate-token).
>
> 4. In the **Test User Email** box, type the email address of a test user that does not already exist in MoEngage.
>
> 5. Click **Test Connection** to verify that JumpCloud can connect to the MoEngage SCIM API.\
> **Note**: A successful connection test updates the SCIM status in your MoEngage workspace from *Inactive* to *Active*.
>
> 6. Turn off the **Enable management of User Groups and Group Membership in this application** toggle.
>
> 7. Click **Activate**.\
> JumpCloud runs provisioning tests for the Create, Get, Update, and Delete user operations against the MoEngage SCIM API.
>
> 8. Resolve any errors listed above the **Activate** button, and click **Activate** again.
>
> 9. Click **Save**.
>
> > [!NOTE]
> >
> > MoEngage does not require JumpCloud to provision group objects. JumpCloud provisions users individually, and role assignment is handled using a custom attribute, as described in [Step 4](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-4-map-the-role-attribute).
>
> ## Step 4: Map the Role Attribute
>
> Grant JumpCloud a way to pass the MoEngage role to each user during provisioning by adding a custom attribute to the user and mapping it to MoEngage's role extension.
>
> > [!NOTE]
> >
> > **Information**
> >
> > MoEngage prioritizes attributes passed via the external namespace. If multiple role attributes are configured, MoEngage resolves them in the following order:
> >
> > * **extension.role (urn:ietf:params:scim:schemas:extension:moengage:2.0:User.role):** Attributes defined with the 2.0 namespace (Highest Priority).
> > * **standard role.role**: Attributes defined under the role namespace. (This parameter will be deprecated in a future release.)
> > * **Default Role**: If no roles are passed via SCIM, the system uses the default role configured in the MoEngage workspace ([Step 2](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-2-configure-scim-in-moengage-and-generate-token)).
>
> ### Step 4.1: Add a Custom Attribute to the User
>
> Add this custom attribute when you invite a new user, or to an existing user. To add it to an existing user, perform the following steps:
>
> 1. On the left navigation menu in the JumpCloud Admin Portal, click **Identity Management** > **Users**.
> 2. Select the user you want to assign a role to.
> 3. On the **Details** tab, scroll to **Custom Attributes**, and click **add new custom attribute**.
>
> 
> 4. In the **Attribute Name** box, type role.
> 5. In the **Attribute Value** box, type the exact role name configured in your MoEngage workspace.\
> **Note**: This value is case-sensitive and must already exist as a role in your MoEngage workspace.
> 6. Click **Save User**.
>
> ### Step 4.2: Map the Attribute in Export Attribute Mapping
>
> 1. On your JumpCloud application, click the **Provisioning** tab.
> 2. Expand **Export Attribute Mapping**, and click **Edit**.
> 3. Scroll to the bottom of the **Optional Mappings** table, and click **+Add Attribute**.
>
> 
> 4. In **Mapping Type**, click **Direct Mapping (JSON Path)**. In **Source**, click **Custom User Property**, and replace the default value with the exact attribute name you used in [Step 4.1](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-4-1-add-a-custom-attribute-to-the-user), for example, role.
> 5. In the destination attribute box, type urn:ietf:params:scim:schemas:extension:moengage:2.0:User.role.\
> **Note**: Use a period before `role`, not a colon. JumpCloud reads `role` as a property of the `moengage:2.0:User` extension, rather than as a flat attribute name — unlike the syntax used for other IdPs.
> 6. Click **Update** to apply the mapping and push the updated attribute to existing users.
>
> ## Step 5: Validation
>
> Verify the following in the MoEngage workspace (**Settings** > **Account** > **Team Management**):
>
> * **User Invitation**: Confirm the user is successfully invited and the status is Joined.
>
> 
> * **Default Role Update**: Confirm that if no specific role was passed from JumpCloud, the system correctly assigned the Default Role configured in [Step 2](/docs/user-guide/settings/account/security/system-for-cross-domain-identity-management-scim#step-2-configure-scim-in-moengage-and-generate-token).
> * **Role Accuracy**: Confirm that the specific role sent from JumpCloud (based on the custom attribute mapping) matches the assigned role in the workspace.
>
> 
# Operations (Attribute Information)
The following tables detail the attributes used for SCIM operations. Use this information to understand the data exchange between your identity provider and MoEngage to ensure consistency and proper configuration.
> [!NOTE]
>
> These tables are provided for reference purposes.
### Create User
When you create a user through SCIM, your identity provider sends a request to MoEngage with a specific set of attributes. The following table defines the parameters you can include in the user-creation request:
| Parameter | Required | Updatable | Description |
| - | - | - | - |
| userName | Yes | Yes | The user's email address. This field is required by the SCIM protocol and must match the emails value. |
| givenName | Yes | No | The first name of the user as it appears in the MoEngage UI |
| familyName | Yes | No | The user's last name as it appears in the MoEngage UI. |
| emails | Yes | No | The user's email address, which acts as the primary identifier in MoEngage. |
| role | Yes | Yes | The user's role in MoEngage. This value is case-sensitive and must already exist in the platform. |
### Update or Revoke User Access
When you update or revoke user access, your identity provider sends a request to MoEngage. A single API handles this process by updating user information or revoking access by changing the active attribute.
| Parameter | Required | Updatable | Description |
| - | - | - | - |
| userName | Yes | No | The user's email address. This field is required by the SCIM protocol and must match the emails value. |
| givenName | Yes | No | The user's first name as it appears in MoEngage. |
| familyName | Yes | No | The user's last name as it appears in MoEngage. |
| emails | Yes | No | The user's email address, which acts as the primary identifier on MoEngage. |
| role | Yes | Yes | The user's role in MoEngage. This value is case-sensitive and available on MoEngage. |
| active | Yes | Yes | This value determines whether the user can access MoEngage. When the user is created, this value is set to *true* by default. To revoke a user's access, set it to *false*. |
# FAQs
> [accordion] I cannot update roles through the identity provider.
>
> Ensure that the **External namespace** is set to **role** and the **Attribute required** setting is enabled (set to True).
> [accordion] Incorrect role is being updated in MoEngage.
>
> This occurs if the identity provider passes two "role" attributes in the schema. MoEngage prioritizes the custom attribute role over the default attribute. Review the identity provider logs and schema to resolve the conflict. If both attributes are required, ensure they contain identical role values.
> [accordion] There are issues with user provisioning when using groups.
>
> Ensure the user account is created in MoEngage before the group (role) is assigned or created in MoEngage.
# Whitelist Partners and Servers
Source: https://moengage.com/docs/user-guide/settings/account/security/whitelist-partners-and-servers
Guide to find every partner and server that calls MoEngage APIs, collect their IP addresses, and publish API Firewall rules without blocking your own data.
After you publish an [API Firewall](/docs/user-guide/settings/account/security/api-firewall) rule, MoEngage blocks every API call from an IP address that isn't on your whitelist, including calls from your own partners. This guide shows you how to find every partner and server that calls MoEngage, collect their IP addresses, and publish rules without breaking your data flow.
Use this guide if any of the following apply to you:
* Your security team wants API access to MoEngage restricted by IP address.
* You're about to turn on the API Firewall.
* A partner tool already gets `403` errors from MoEngage.
> [!NOTE]
>
> The API Firewall is off by default. Until you publish a rule for a category, MoEngage accepts calls to that category from any IP address. MoEngage documentation calls this practice "IP whitelisting". Many security teams call it "IP allowlisting", which means the same thing.
## Overview
This guide covers traffic coming into MoEngage: the calls your servers and partners make to MoEngage APIs. The IP addresses belong to those callers, not to MoEngage, so you collect them from each owner and enter them in the API Firewall.
Keep a worksheet, such as a spreadsheet, as you go. Record each caller, its owner, the API category it uses, its IP addresses, where each IP address came from, and the date you got it.
The process has six steps:
1. [Find your data center and API host](#step-1-find-your-data-center-and-api-host). Partners and developers must call the host that matches your data center.
2. [Find the partners that send data into MoEngage](#step-2-find-the-partners-that-send-data-into-moengage). The dashboard shows each partner type in a different place.
3. [Find your own servers and tools that call MoEngage](#step-3-find-your-own-servers-and-tools-that-call-moengage). Your developers know their outbound IP addresses.
4. [Match each caller to an API category](#step-4-match-each-caller-to-an-api-category). You set rules per category, not per API key.
5. [Get the IP addresses from each owner](#step-5-get-the-ip-addresses-from-each-owner). No single person holds every IP address.
6. [Create the rules, then publish them together](#step-6-create-the-rules-then-publish-them-together). A workspace Admin does this in the dashboard.
## Step 1: Find Your Data Center and API Host
Your data center decides the API host that partners and developers must call. Check the address you use to log in to MoEngage. It reads `dashboard-0X.moengage.com`, where `0X` is your data center number.
| Dashboard URL | Data center | API host | Region |
| - | - | - | - |
| `dashboard-01.moengage.com` | DC-01 | `api-01.moengage.com` | US |
| `dashboard-02.moengage.com` | DC-02 | `api-02.moengage.com` | EU |
| `dashboard-03.moengage.com` | DC-03 | `api-03.moengage.com` | India |
| `dashboard-04.moengage.com` | DC-04 | `api-04.moengage.com` | US |
| `dashboard-05.moengage.com` | DC-05 | `api-05.moengage.com` | Singapore |
| `dashboard-06.moengage.com` | DC-06 | `api-06.moengage.com` | Indonesia |
Record the API host in your worksheet. Every caller in the following steps must use the host of your data center. A partner that points at the wrong host fails for a reason that has nothing to do with the API Firewall. For more information, refer to [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
> [!NOTE]
>
> **Your own outbound firewall is a separate setting.** If your network blocks your servers from reaching MoEngage, allow the domain `api-0X.moengage.com` for the Data API instead of MoEngage's IP addresses. MoEngage is multi-tenant and its IP addresses change often, so don't cache them. The API Firewall in Step 6 works in the other direction: it controls which callers MoEngage accepts.
## Step 2: Find the Partners That Send Data Into MoEngage
Partners connect to MoEngage in two ways, and each leaves a different trail, so check both. Menu names can differ slightly between the current and the new MoEngage UI.
### Partners You Set Up in MoEngage
MoEngage shows each partner type in a different part of the dashboard. Use the following table to find them.
| Partner type | Where imports show up (into MoEngage) | Where exports show up (out of MoEngage) | Needs an API Firewall entry? |
| - | - | - | - |
| Attribution partners, such as AppsFlyer, Adjust, Singular, Branch, and Airbridge | **Settings** > **Analytics** > **Acquisition tracking** shows whether tracking is on and which partner is selected in **Attribution Platform**. Some workspaces show it under **Settings** > **Analytics and Data** > **Acquisition tracking**. | Not applicable | Ask your CSM. The **Partner Integration** category includes the Track App Install API. AppsFlyer Audiences is listed in [Impact on Partner Integrations](/docs/user-guide/settings/account/security/api-firewall#impact-on-partner-integrations). |
| CDP and analytics partners, such as Hightouch, RudderStack, Segment, mParticle, Amplitude, and Mixpanel | **Settings** > **Data** > **Data management** lists every event and user property that arrives, with first and last seen dates. | **App marketplace** in the left navigation | Many do. Check the partner's name in [Impact on Partner Integrations](/docs/user-guide/settings/account/security/api-firewall#impact-on-partner-integrations). |
| Connected sources, such as Punchh, RevenueCat, and Unbounce | **Settings** > **Data** > **Data management**, as above. These partners send data to an endpoint that MoEngage sets up for them. | Not applicable | No |
| Data warehouses, such as Snowflake, BigQuery, and Databricks | **App marketplace** holds the connection. The **Data warehouses** tab under **Data** > **Data imports** lists each import. | **App marketplace** | No. MoEngage pulls the data. |
| Cloud storage, such as Amazon S3 and SFTP | **App marketplace** holds the connection. **Data** > **Data imports** lists each file import. | **App marketplace** | No. MoEngage pulls the data. |
| Connected channels, such as ad platforms and messaging apps | **App marketplace** | **App marketplace**, and the Connector campaigns you create | No. MoEngage sends the data. |
The following sections show where to check each route in the table.
#### Data Management
In [Data management](/docs/user-guide/settings/data-management/overview-data-management), open the **Events** tab. In **Select source**, select **Data API** or a partner listed under **Partners**, and then sort by **Last seen**. An event that still arrives from a partner has a recent date, which tells you the connection is live. The **Source** column shows where each event comes from.

#### Data Imports
The **Data imports** page lists your import jobs by name on the **File imports** and **Data warehouses** tabs. Use the **Select source** filter on the **File imports** tab to separate Amazon S3, SFTP, and CSV imports, and use the import names to tell partners apart.

#### App Marketplace
In **App marketplace**, select **My Integrations** to see the partners connected to your workspace.

#### Acquisition Tracking
The **Attribution Platform** field shows which attribution partner your workspace uses.

### Partners That Connect From Their Own Side
Many partners, such as Hightouch, Zapier, and Konnectify, are set up inside the partner's own tool. Someone on your team pastes your Workspace ID and Data API key into that tool, so MoEngage may show no tile or setting for the partner. Use the following methods to find these partners:
* **Open Settings > Account > APIs.** This page shows your Workspace ID and one API key per API group, such as Data, Push, Inform, Campaigns and catalog, and Personalize. Ask who copied each key and where they pasted it.
* **Use the API Key Dashboard if you have it.** With this Early Access feature, an Admin can create several named keys under **Settings** > **Account** > **API keys**, each limited to chosen APIs. Audit Logs record who created, updated, or archived each key. Creating one key per vendor is the easiest way to see who calls MoEngage. For more information, refer to [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard).

* **Ask Support which IP addresses MoEngage already sees.** [Raise a support ticket](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard) to request the IP addresses from which MoEngage received successful API requests for your workspace. Ask for a period long enough to include your longest job cycle, such as a month. Every IP address in the list should belong to a server or partner in your worksheet. Before you publish rules, find an owner for any IP address you don't recognize. The list shows only successful requests, so it can miss a caller that already fails or that runs rarely.
* **Ask the teams that own data tools.** Your data, growth, CRM, and analytics teams know which tools list MoEngage as a destination.
* **Check from the partner's side.** Look for a MoEngage entry in the destinations or connected apps list of your CDP, reverse ETL, automation, and CRM tools.
* **Use the partner impact list as a checklist.** For each partner in [Impact on Partner Integrations](/docs/user-guide/settings/account/security/api-firewall#impact-on-partner-integrations), ask whether your team uses it.
### Record the Partners
1. Open each location above and record every partner in your worksheet, with the vendor name, the owner, and a contact.
2. Mark whether the partner calls MoEngage from its own servers. The [Impact on Partner Integrations](/docs/user-guide/settings/account/security/api-firewall#impact-on-partner-integrations) table tells you which named partners do.
3. Ask your CSM about any partner you can't place. Your CSM can see the same partner list and can walk through it with you.
## Step 3: Find Your Own Servers and Tools That Call MoEngage
Partners are only part of the picture. Anything of yours that uses a MoEngage API key is also blocked after you publish a rule, so ask your developers and IT team to list every caller. Share the following table with them.
| Type of caller | Examples | What to collect |
| - | - | - |
| Production backends | Services that send user attributes and events to MoEngage as users act | The static public IP address, or the NAT gateway IP address, they send from |
| Data pipelines and scheduled jobs | Nightly syncs, bulk imports, and report downloads | The IP address of the machine or runner that makes the call |
| Internal tools and scripts | Admin panels, support tools, and one-off scripts | The owner of each one, and the IP address it calls from |
| Staging and QA | Test environments that use a staging workspace | The IP addresses of the test systems, kept in separate rules in the staging workspace |
| Agencies and contractors | Anyone who holds one of your API keys | Their outbound IP addresses, from them |
| Automation and BI tools | Workflow tools and dashboards that read analytics through the API | The tool's published IP address list, or the IP addresses of the server that runs it |
Your developers can find these callers in two ways:
* Search code, scheduled jobs, and configuration for your MoEngage API host from Step 1.
* Review the API keys under **Settings** > **Account** > **APIs**, and in the API Key Dashboard if you have it, then ask each key's owner what uses it.
Keep the following in mind before you collect IP addresses:
* **Fixed IP addresses only.** The API Firewall accepts single IP addresses and IP ranges, not domain names or wildcards. A caller with no fixed outbound IP address, such as a serverless function, must first route its traffic through a NAT gateway or proxy that has one.
* **Mobile and web apps aren't affected.** The API Firewall covers server-to-server API traffic and doesn't affect SDK traffic from your app or website, so you don't list user devices.
* **Both IP versions work.** You can enter IPv4 and IPv6 addresses, CIDR ranges, and IPv4 ranges with a start and an end address.
## Step 4: Match Each Caller to an API Category
API Firewall rules apply per API category across the whole workspace, so for each caller in your worksheet, you need to know which category its calls fall into. There are five fixed categories.
| Category | What it covers |
| - | - |
| Data | User profiles, event tracking, bulk import, device management, GDPR and CCPA requests, and analytics dashboard data |
| Segmentation | File segments, filter segments, and archiving or unarchiving segments |
| Campaigns | Campaign management, test sends, stats and reports, business events, subscriptions, push (V2.1), cards, Inform alerts, Live Activities, Personalize, message archival, and flows |
| Partner Integration | Cohort sync, partner file imports, app install tracking, and the connection test |
| Content | In-app, on-site, SMS, email, and push templates, content blocks, recommendations, coupons, catalog, and offerings |
Ask your developers which API each of their calls uses, then place it in a category. For the full list of APIs in each category, refer to [API Categories](/docs/user-guide/settings/account/security/api-firewall#api-categories).
Keep the following exceptions in mind:
* **The legacy push API isn't covered.** The [Send Push Notification (Legacy)](/docs/api/push/push-api-legacy) v2 API ignores whitelist rules. To restrict push requests by IP address, move to [Send Push Notification (V2.1)](/docs/api/push/push-api).
* **A few accounts are exempt for Inform.** The API Firewall supports the Send Transactional Alert (Inform) API, except for a small number of accounts. If you think your account is exempt, contact your CSM.
* **Rules apply per category, not per API key.** You can't limit one key to one IP address. Any caller on the whitelist can use any key for that category.
* **Workspace-to-workspace traffic needs MoEngage's IP addresses.** If you use Connected Segments, Streams, or Connector campaigns to send data from one MoEngage workspace to another, add MoEngage's own IP addresses to the receiving workspace's rules. For the list, refer to [IP Whitelisting in MoEngage](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage).
## Step 5: Get the IP Addresses From Each Owner
No single person holds every IP address, so send each request to the owner of that caller. Send one complete message per owner so they can answer without a follow-up.
| Who | What they own | What to ask them |
| - | - | - |
| Your developers, DevOps, or IT security team | Your servers, NAT gateways, proxies, and CI tools | The static outbound IP addresses or CIDR ranges of every caller in Step 3 |
| Each partner vendor | The servers the partner calls MoEngage from | The public IP addresses or CIDR ranges it uses, and whether they're fixed |
| Your MoEngage CSM or the Support team | Account-level answers | The IP addresses from which MoEngage received successful API requests (through a support ticket), which of your partners are affected, whether your account is exempt for Inform, and help if a partner can't give fixed IP addresses |
### Find a Partner's IP Addresses
* **Search the partner's help center** for "IP allowlist", "IP whitelist", "static IP", "egress IP", or "webhook IPs". Many vendors publish a page.
* **Read the partner's MoEngage integration guide** in the [Partner Guide](/docs/partner-guide/introduction).
* **Ask the partner's support team or account manager** for the IP addresses it calls MoEngage from.
* **Ask your developers about middleware or tools you host yourself.** They can give you the public IP address of your NAT gateway or load balancer from your cloud console. A NAT gateway is the single public address that many internal servers share when they call out to the internet.
* **Record every IP address in your worksheet** with its source and the date you got it.
### What to Expect From Vendors
* **Some vendors publish fixed lists.** Klaviyo, Iterable, and Optimove publish IP address lists for the traffic they send, and Iterable lets you fetch its list programmatically.
* **Some vendors give shared regional ranges only.** Twilio Segment publishes ranges by region and doesn't offer dedicated IP addresses to individual customers.
* **Some vendors gate fixed IP addresses by plan.** Segment's IP allowlisting for Functions traffic is on its Business tier.
* **Some vendors can't give fixed IP addresses for all traffic.** Iterable tells customers to allow domains, not IP addresses, for API and CDN traffic.
> [!WARNING]
>
> If a partner can't give you fixed IP addresses, talk to your CSM before you publish a rule for that partner's category. Once the rule is published, MoEngage blocks the partner's calls from any IP address that isn't in the rule.
## Step 6: Create the Rules, Then Publish Them Together
The main risk is blocking your own traffic, so add every rule first and turn on enforcement last. You must be a workspace Admin to add rules.
### Create the Rules
1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Account** > **Security**, and select the **API firewall** tab.
2. Select **Enable API Firewall**. The **Add API firewall rule** dialog box opens.
3. In **Rule name**, enter a name that says who the rule is for, such as "Production backend" or "Hightouch".
4. Under **Whitelist categories**, select every category that the caller uses from Step 4. You must select at least one.
5. In **Condition**, select the type that matches the IP address you have: a single IPv4 or IPv6 address, a CIDR range, or an IPv4 range.
6. In **Value**, enter the IP address or range, and then select **Add rule**.
7. Repeat these steps for every caller in your worksheet. To add more rules, select **+ Add rule** on the API firewall list page.

MoEngage saves each new rule as **Unpublished**, which means it's recorded but not enforced. For field details and screenshots, refer to [Create and Publish API Firewall Rules](/docs/user-guide/settings/account/security/api-firewall#create-and-publish-api-firewall-rules).
### Publish the Rules
Publishing a rule enforces it for every category it covers, and MoEngage applies it within about 15 minutes. From then on, a call from an IP address that isn't in a published rule for that category gets a `403` response.
Before you publish, confirm the following:
* Every caller from Steps 2 and 3 has a rule.
* Every partner marked **Yes** in [Impact on Partner Integrations](/docs/user-guide/settings/account/security/api-firewall#impact-on-partner-integrations) that you use has its IP addresses in a rule for the right category.
* Every rule is saved as **Unpublished**.
* You read the **First rule for this category** warning in the dialog box and checked that no caller is missing.
* Your team knows the publish time, and someone watches for `403` errors from your servers and partners that day.
* Your worksheet lists each IP address with its source and date.
Then select all the unpublished rules and publish them in one action, not one at a time, so no caller is blocked while its rule waits.

MoEngage doesn't send a dashboard notification when it blocks a request. The blocked caller sees the `403` response directly, so ask your developers and partners to set up alerts for it.
### Roll Back and Review
To stop enforcing a rule, select it and then select **Unpublish**. If you unpublish every rule for a category, that category accepts calls from any IP address again. Deleting the last published rule for a category has the same effect, and the dashboard warns you first.
[Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs) record every rule change, with who made it, when, and from which IP address.
If the API Firewall itself has an internal failure, it's designed to fail open. It lets traffic through so that data collection continues.
## Troubleshooting
| What you see | Likely cause | What to do |
| - | - | - |
| A partner tool gets `403` errors from MoEngage. | Its IP addresses are missing from a published rule, or the rule covers the wrong category. | Get the partner's IP addresses, add them to a rule for the category from Step 4, and publish it. |
| Your own server gets `403` errors after you publish. | The server's public IP address, often a NAT gateway, isn't in a published rule for that category. | Ask your developers for the real outbound IP address, add it, and allow about 15 minutes after publishing. |
| Calls worked for a while, and then started failing. | The partner or your infrastructure changed its IP addresses. | Ask the owner for the new IP addresses, add them, and publish the rule. |
| One category works and another fails. | A published rule exists for only one of the categories the caller uses. Categories with no published rule stay open, and covered categories are enforced. | Add the caller's IP addresses to a rule for the failing category. |
| You added a rule, but calls from other IP addresses still succeed. | The rule is saved as **Unpublished**, so it doesn't affect traffic. | Check the rule's status, and publish it if you meant to enforce it. |
| Calls are blocked with no dashboard alert. | MoEngage doesn't notify the dashboard when it blocks a request. | Check the logs on the caller's side for the `403` response. |
| You need to restrict one API key to one IP address. | Rules apply per category for the workspace, not per key. | [Submit a product idea](/docs/user-guide/contact-support/suggest-a-feature) from **Need help** in the dashboard. |
| A partner can't give fixed IP addresses. | The vendor shares or rotates its IP addresses. | Talk to your CSM before you publish a rule for that partner's category. |
| Push requests aren't restricted. | The Send Push Notification (Legacy) v2 API ignores whitelist rules. | Move to [Send Push Notification (V2.1)](/docs/api/push/push-api). |
| Your servers see time-out or network errors when they call MoEngage. | Your own outbound firewall blocks the MoEngage address, or it allows an old IP address that has since changed. | Allow the domain `api-0X.moengage.com` for your data center instead of MoEngage IP addresses, and don't cache IP addresses. |
## FAQs
> [accordion] Do I have to turn on the API Firewall?
>
> No. The API Firewall is inactive by default, and MoEngage accepts API calls from any IP address until you publish a rule for a category.
> [accordion] Who can create rules?
>
> A workspace Admin. Developers and partners can supply the IP addresses, but an Admin enters and publishes the rules.
> [accordion] Can I enter a domain name or a wildcard?
>
> No. Rules accept single IP addresses, CIDR ranges, and IPv4 ranges only.
> [accordion] Does the API Firewall affect my mobile app or website?
>
> No. The API Firewall applies to server-to-server API traffic and doesn't affect SDK traffic from end users.
> [accordion] Why should I add all rules before I publish them?
>
> Publishing enforces each category within about 15 minutes. If you publish rules one at a time, a caller whose rule isn't published yet can get `403` errors.
> [accordion] Will I know if the API Firewall blocks something?
>
> Not from the dashboard. The blocked caller receives a `403` response, so monitor for it on the caller's side.
> [accordion] Where can I see who changed a rule?
>
> In [Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs), which record each rule change, who made it, when, and from which IP address.
> [accordion] Who do I contact if I don't have a CSM?
>
> Contact the MoEngage Support team.
> [accordion] A partner is set up in its own tool and I can't find it in MoEngage. What do I do?
>
> Refer to [Partners That Connect From Their Own Side](#partners-that-connect-from-their-own-side). Check **Settings** > **Account** > **APIs**, the API Key Dashboard if you have it, and the destinations list in the partner's own tool.
# Access Roles
Source: https://moengage.com/docs/user-guide/settings/account/team-management/access-roles
Set up role-based access control in MoEngage to manage team permissions for dashboard components, including default and custom roles.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
MoEngage offers role-based access control for account admins to enable different levels of access permissions (to dashboard components) for your team members.
You can view the access roles by navigating to **Settings** > **Account** > **Team management** > **Roles**.
# Types of Access Roles
MoEngage provides two types of access roles to manage MoEngage UI permissions:
* [Default roles](/docs/user-guide/settings/account/team-management/access-roles#default-roles): Predefined roles with fixed permission sets that are available for every account. These roles cannot be modified.
* [Custom roles](/docs/user-guide/settings/account/team-management/access-roles#custom-roles): User-defined roles that you can configure with specific permission sets based on your organization's requirements.
## Default Roles
These are the default roles with fixed permissions and are available for every account. These roles cannot be edited. MoEngage provides the following default roles:
### Admin
The person who creates the workspace is assigned the Admin role by default. The role has all permissions for the account
* Creating campaigns
* Changing account settings
* Inviting team members
Admins are allowed to invite other users as Admin or Manager or Marketer and so on. Only admins are allowed to create or edit or delete new Teams.
For more information about team management, refer to [Teams in MoEngage](/docs/user-guide/settings/account/team-management/teams-in-moengage).
### Manager
The person who will run marketing campaigns for live users, and manage the account and all settings. This member has all permissions on the dashboard similar to Admin, barring the permission to Create/Edit/Delete Teams. There can be multiple managers in one account. Managers can invite team members to roles of Manager and below.
### Marketer
The person who will create the campaigns for live users has access to segmentation but cannot access billing info. With Campaign approval flow, a marketer's campaigns will go live ONLY upon approval from the Manage or Admin. For more information, refer to [Campaign Approval Flow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow).
### Developer
The person who will integrate your app/web with MoEngage. This member can access/test all features in the TEST environment but has restricted access in the LIVE environment. The access details are as follows:
* Can not view Billing details and can only add Developers to the account
* Can not view campaigns created by Admin/Manager team members
* Can not change Push FC and DND settings
> [!WARNING]
>
> **Developer Role Campaigns Reach Test Users Only**
>
> On a live app, MoEngage delivers a campaign created by a user with the Developer role only to users marked as test users or test devices, rather than to everyone in the selected segment. This restriction keeps your production audience protected while developers test.
>
> The campaign audience is the intersection of the selected segment and your test users. When the segment contains no test users, the campaign resolves to 0 recipients even though the segment itself returns users. Segmentation works as expected here and returns an accurate count that reflects the test-user restriction.
To reach the full segment, choose one of the following options:
* Ask a user with a role that publishes to live users — Admin, Manager, or Marketer — to create the campaign, or to duplicate the existing campaign and send it.
* Mark the users you want to reach as test users before you send the campaign from a Developer account.
* Send the campaign from a test app when the intent is Developer testing.
When the campaign goes through the [campaign approval workflow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow), an approver who edits the campaign before approving it passes their own role to the campaign, which also changes who the campaign targets. For more information, refer to [How an Approver's Edit Changes Campaign Targeting](/docs/user-guide/settings/account/team-management/campaign-approval-workflow#how-an-approvers-edit-changes-campaign-targeting).
### Analyst
The person who has access to view/export campaign data, user segmentation data, and set up daily reports. This member can not create any campaigns or change any settings (except for setting up Reports).
To summarise, the following are the default roles and their access permissions.
| Component | Permission | Admin | Manager | Marketer | Developer | Analyst |
| :- | :- | :-: | :-: | :-: | :-: | :-: |
| **Recommendations & Catalog** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | No | No |
| **Dashboard & Analyze** | View | Yes | Yes | Yes | Yes | Yes |
| | Run query | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | Yes | Yes |
| **Segments (All / RFM / Warehouse / AI / Sync)** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | No | Yes |
| **Campaigns, Inform, Flows & Personalize** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | No |
| | Create, manage and publish | Yes | Yes | If [approval flow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow) is enabled - No / If [approval flow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow) is disabled - Yes: Yes | No | No |
| | Edit Templates | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | No | Yes |
| **Drafts** | View | Yes | Yes | Yes | No | No |
| | Create and manage | Yes | Yes | Yes | No | No |
| **Reports** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | Yes | No |
| **App configuration** | View | Yes | Yes | Yes | No | No |
| | Setup and manage | Yes | Yes | No | No | No |
| **App Marketplace** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | No | No | No |
| **Channel configuration** | View | Yes | Yes | Yes | Yes | No |
| | Manage message templates | Yes | Yes | Yes | No | No |
| | Setup and manage | Yes | Yes | No | No | No |
| **Security Settings** | Manage (Note: Login Settings renamed to Security Settings) | Yes | No | No | No | No |
| **Team management** | View | Yes | Yes | Yes | Yes | No |
| | Create and manage | Yes | Yes | Yes | Yes | No |
| | Create and manage all roles | Yes | No | No | No | No |
| **[Teams](/docs/user-guide/settings/account/team-management/teams-in-moengage)** | View | Yes | Yes | Yes | No | No |
| | Setup and manage | Yes | No | No | No | No |
| **Usage and Billing** | View | Yes | No | No | No | No |
| | Create and manage | Yes | No | No | No | No |
| | Download | Yes | No | No | No | No |
| **Alert Manager - Out of the Box (OOTB) Alerts** | View | Yes | Yes | Yes | Yes | Yes |
| | Edit | Yes | No | No | No | No |
| | Subscribe | Yes | Yes | Yes | No | No |
| | Subscribe Others | Yes | Yes | No | No | No |
| | Unsubscribe | Yes | Yes | Yes | No | No |
| | Delete | Yes | No | No | No | No |
| **Alert Manager - Custom Alerts** | View | Yes | Yes | Yes | Yes | Yes |
| | Edit / Create / Duplicate | Yes | Yes | Yes | No | No |
| | Subscribe / Subscribe Others | Yes | Yes | Yes | No | No |
| | Unsubscribe / Delete | Yes | Yes | Yes | No | No |
| **Content** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | No | No |
| | Create, manage, and publish | Yes | Yes | Yes | No | No |
| | Delete | Yes | Yes | Yes | No | No |
| | Lock/Unlock Row | Yes | Yes | No | No | No |
| **Landing Pages** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | No |
| | Create, manage and publish | Yes | Yes | No | No | No |
| **Imports** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | No | No |
| **Coupons** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage / Publish | Yes | Yes | Yes | No | No |
| | Download | Yes | No | No | No | No |
| **Predict** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | Yes | Yes |
| | Download | Yes | Yes | Yes | Yes | Yes |
| **Offerings** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | No | No |
| | Create, manage and publish | Yes | Yes | Yes | No | No |
| | Download | Yes | No | No | No | No |
| **Decision Policy** | View | Yes | Yes | Yes | Yes | Yes |
| | Create and manage | Yes | Yes | Yes | No | No |
| | Create, manage and publish | Yes | Yes | Yes | No | No |
| | Download | Yes | No | No | No | No |
| **User Profile Management** | Create and manage | Yes | Yes | No | No | No |
## Custom roles
These allow you to create new roles with your desired permission sets. You can also clone existing roles and assign permission sets as desired.
> [!NOTE]
>
> Only admins have access to create/update roles.
### Steps to create a new role
1. Navigate to **Settings > Account > Team management > Roles**. 
2. Click **Create role** on the top right of the header. 
3. Provide a role name and description. You can choose to copy permission sets from an existing role or create one from scratch. 
4. Click **Create**.
5. You can now check/uncheck permissions as per your requirement. The changes will be autosaved.
Read more about the various permissions on the MoEngage dashboard.
# Permissions
| Components | Permissions | Description |
| - | - | - |
| Recommendations & Catalog | View | Can view list of published recommendations, and catalog items and feeds. |
| | Create and manage | Can edit, archive or publish new recommendations, catalogs, or add/delete catalog feeds |
| | Download | Can download catalog feeds or item processing failure report |
| Dashboard & Analyze | View | Can view custom dashboards, analyze sections |
| | Run query | Can run analyze queries and view results |
| | Create and manage | Can create new charts and dashboards and edit/delete existing ones |
| | Download | Can download charts and CSV data |
| All Segments, RFM Segments, Warehouse Segments, Seg AI, Sync Segments | View | Can view users & created segments |
| | Create and manage | Can run segment queries, create new segments, and edit/delete existing ones |
| | Download | Can download users and CSV data from user profile |
| Campaigns, Inform, Flows & Personalize | View | Can view all campaigns and campaign info pages |
| | Create and manage | Can create new campaigns, and edit/update existing campaigns; but cannot publish the campaign. If you are using campaign approval flow - the user with the permission can only send the campaign for approval. |
| | Create, manage, and publish | Can create new campaigns, edit/update existing campaigns, and also publish the campaign. If you are using campaign approval flow - the user with the permission can approve/reject the campaign. |
| | Edit templates | Can edit templates |
| | Download | Can export campaigns |
| Drafts | View | Can view drafts |
| | Create and manage | Can create and update drafts |
| Reports | View | Can view all reports |
| | Create and manage | Can create new reports, update/delete existing reports |
| | Download | Can download the reports |
| App configuration | View | - Can view general, API, Analytics, and Control group settings - **Data Management:** Can view the data management dashboard and download reports - **Identity Resolution:** Can view the identity resolution dashboard - **Tag Management:** Can view tags |
| | Setup and manage | - Can configure and update App settings - **Data Management:** Can perform actions on the data management dashboard (for example, block/hide events) - **Identity Resolution:** Can perform actions on the identity resolution dashboard (for example, add identifiers, change merge settings, pause identifiers) - **Tag Management:** Can create/edit tags - **Portfolio:** Can add projects to a Portfolio |
| App Marketplace | Create and manage | Can create & edit the integrations. |
| Channel configuration | View | Can view channel settings |
| | Setup and manage | - Can configure and update channel settings - **PII Masking & Encryption:** Can mask attributes |
| | Create and manage all roles | Can invite new members, change the role of existing members and revoke access of members irrespective of their roles, enable/disable "Campaign Approval Flow", and download dashboard users |
| Teams (know more) | View | Can view all teams and their members |
| | Setup and manage | Can create new teams, edit/update existing teams |
| Usage and Billing | View | Can view and enter subscription information, view organisation information, and view billing card information |
| | Create and manage | Can view and enter subscription information, edit organisation info, edit billing card information, and view & export audit logs |
| | Download | Can download charts and CSV data for workspace's usage |
| Alert Manager - Out of the Box Alerts (OOTB Alerts) and Custom Alerts | View | Can view alerts |
| | Edit | Can edit alerts |
| | Subscribe | Can subscribe to alerts |
| | Subscribe Others | Can subscribe others to receive alerts |
| | Unsubscribe | Can unsubscribe from receiving alerts that they are subscribed to |
| | Delete | Can delete alerts |
| | Create | Can create a custom alert. OOTB alerts cannot be created. |
| | Duplicate | Can duplicate a custom alert. OOTB alerts cannot be duplicated. |
| App Marketplace | View | Can view the available integrations |
| | Create and manage | Can create & edit the integrations |
| Landing Pages | View | Can view all landing pages and landing page info pages |
| | Create and manage | Can create new landing pages, edit/update existing landing pages |
| Imports | View | Can view the created data imports |
| | Create and manage | Can create & manage new data imports |
| | Download | Can download users from the created data imports |
| Coupons | View | Can view the listed Coupon List in Coupon List listing page and the added files and metadata of coupon files added in a Coupon List |
| | Create and manage | Can set up a new Coupon List within the MoEngage platform, modify or update a Coupon List details, archive/unarchive a Coupon List name, add new coupon files to top-up the Coupon List, and delete a coupon files from a Coupon List |
| | Publish | Can select the coupon list in a campaign such that the campaigns are sent with coupons as per functionality |
| | Download | Can download the coupon list usage report for audit |
| Content | View | Can view templates |
| | Create and manage | Can create templates and save as draft |
| | Create, manage, and publish | Can publish templates |
| | Delete | Can delete templates |
| Lock/Unlock Row | Controls the ability to lock or unlock design rows within the template builder to protect brand elements (e.g., standard headers/footers).Note: Enabling this sub-permission automatically inherits View, Create and Manage, and Create, Manage & Publish row access. |
| Offerings | View | Can view created offerings |
| | Create and manage | Can view new offerings and edit/update existing offerings |
| | Create, manage and publish | Can create new offerings, edit/update existing offerings, and publish them |
| | Download | Can export reports for offerings |
| Decision Policy | View | Can view created decision policies |
| | Create and manage | Can view new decision policies and edit/update existing decision policies |
| | Create, manage and publish | Can create new decision policies, edit/update existing decision policies, and publish them |
| | Download | Can export reports for decision policies |
| User Profile Management | Create and manage | Can delete a user or edit their permissions. |
# Campaign Approval Workflow
Source: https://moengage.com/docs/user-guide/settings/account/team-management/campaign-approval-workflow
Enable a creator-approver workflow in MoEngage to review and approve campaigns before they go live, ensuring marketing quality control.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Campaign approval allows marketing teams to control/review the campaigns that are going live by putting in place a creator-approver (maker-checker) approach. Marketing teams can decide which users are allowed to create the campaigns and which users have the privilege to approve them.

## Enable Campaign Approval Workflow for Campaigns
> [!NOTE]
>
> **Permissions**: Any roles authorized to create, manage, and publish campaigns are available in the approver list. They can approve or reject the campaigns.
>
> **Activation Time**: Once the toggle is turned on, it may take up to 5 minutes for the Campaign Approval features to become visible and active across the dashboard.
1. Navigate to MoEngage Dashboard > **Settings** > **Account** > **Team management**. The Team management page is displayed.
2. On the **Members** tab, turn the **Approval Flow** toggle on to enable the campaign approval flow. The toggle is disabled by default.

After the toggle is enabled, any roles authorized to create, manage, and publish will have approver rights. Only on approval, campaigns will become live.
## Assign Roles
#### Approver Role
Any roles authorized to create, manage, and publish will have approver rights when the **Approval Flow** toggle is turned on.
#### Marketer Role
Campaigns created by Marketers must be sent for approval.
Because the Marketer role is new, you need to add users to the Marketer role or change roles for existing users.
## Send a Campaign for Approval
After the **Approval Flow** toggle is turned on, marketers can create a campaign and send it to a list of approvers.


## Approved/Rejected
When the marketer clicks **Send For Approval**, all the assigned approvers will get the email for reviewing the campaign. Approvers can click the campaign link in the email and they will get redirected to the specified campaign.

Now, they can review the campaign and choose to reject or approve it before the campaign sent time is passed.
* If *approved*, the campaign will become Live.
* If *rejected*, the marketers can edit the campaigns as per the Approver's comments and send them again for approval.
Any roles authorized to create, manage, and publish can also choose to edit the campaigns *Under Review*and make them Live with all the necessary changes.
> [!NOTE]
>
> * Marketers cannot edit the campaigns when campaigns are *Under Review*.
> * Only the approvers who were asked to review the campaigns can Approve/Reject them.
> * The *Rejected* campaigns cannot be edited.
> * Under the campaigns section, any custom role (excluding the Marketer role) that lacks Create, manage, and publish permissions will be required to send their campaigns for approval.
## How an Approver's Edit Changes Campaign Targeting
A campaign carries the [access role](/docs/user-guide/settings/account/team-management/access-roles) of the user who creates it, and that role determines who the campaign targets. When an approver edits a campaign before approving it, the campaign inherits the approver's role.
The audience changes whenever the creator and the approver hold different targeting scopes. For example:
* A user with the Developer role creates a campaign. Role-based targeting for the [Developer role](/docs/user-guide/settings/account/team-management/access-roles#developer) limits the campaign to the test users in the selected segment.
* A Manager-role approver edits the same campaign before approving it. The campaign inherits the Manager role and targets all users in the selected segment.
Before you edit a campaign that is *Under Review*, confirm the audience you expect the campaign to reach, especially when your role differs from the creator's role.
# Supported Channels
| Channels | Supported |
| - | - |
| Push | Yes |
| Email | Yes |
| SMS | Yes |
| Flows | Yes |
| WhatsApp | Yes |
| In-app | Yes |
| On-site Messaging | Yes |
| Facebook Audience | No |
| Google Ads | No |
| Connector | Yes |
| Flows | Yes |
| Cards | No |
| Web personalization | No |
# Manage Members
Source: https://moengage.com/docs/user-guide/settings/account/team-management/manage-members
Invite, manage, and assign access roles to team members in your MoEngage workspace through the Team management settings dashboard page.
This feature enables you to invite a member to a workspace in MoEngage and define each member's level of access to the workspace.
# View Members
To view members, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** >**Team management**.
2. On the Team management page, you are on the **Members** tab by default.

On the Team management page, the data is displayed in a tabular format, with columns containing details related to each member.
| Columns | Description |
| - | - |
| Member(s) | This specifies the name and email ID of the member. |
| Status | This specifies the member's status, such as Joined, Pending, or Access revoked.
The **Pending** status means the member has received an invitation but has not joined the workspace
The **Joined** status means the member has received an invitation and joined the workspace
The **Access revoked** status means the member's access is revoked from the workspace
|
| Role | This specifies the role of the member, such as Admin, Marketer, or Analyst. |
| Action | This enables admins to perform actions such as granting access, revoking access, or editing the role of a member. |
# Invite Members
> [!NOTE]
>
> * Members with the **Create & Manage** permission level in the **Team Members** component can invite other members to the workspace.
> * You can add a maximum of 100 users to a single workspace.
> * If a member is already part of a workspace, their role cannot be changed.
> * You can assign roles in bulk to members without affecting the existing members.
To invite members to a workspace, perform the following steps:
1. On the **Members** tab, click + **Invite Member** in the upper-right corner.

The Invite members pop-up window appears.

2. In the **Email addresses** box, type the email address of the member you want to invite.
> [!NOTE]
>
> You can add multiple email addresses, separate them with a comma, and press Enter.
3. Click **Next**. The Invite members pop-up window is updated.
4. Under **Assign Role and teams**, enter the following details:
| Field | Description |
| - | - |
| Member(s) | Edit the member's name, which is populated based on the email address you added. |
| Role | Select the role for an individual member. |
| Edit role | Change the role of all members. |
|  |
5. Click **Invite**.
# Filter Members
You can filter the members in two ways:
### Search Members
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** >**Team management**. The **Team management** page appears.
2. In the **Search members(s)** box, type the name or email ID of the member. 
### Filter Members
1. Click the **Filter members** icon.
2. On the Filter dialog box, enter the following details:
| Field | Description |
| - | - |
| Role | Select the role of the member. |
| Status | Select the status of the member, such as Joined or Pending. |
|  |
3. Click **Apply**.
# Edit Individual Members
For each member you have invited to the workspace, you can perform the following tasks in the **Action** column.
* [Edit a Member’s Role](/docs/user-guide/settings/account/team-management/manage-members#edit-a-member’s-role)
* [Revoke Access from a Member](/docs/user-guide/settings/account/team-management/manage-members#revoke-a-member’s-access)
* [Grant Access to a Member](/docs/user-guide/settings/account/team-management/manage-members#grant-access-to-a-member)
* [Resend Invite to a Member](/docs/user-guide/settings/account/team-management/manage-members#resend-invite-to-a-member)
* [Delete a Member](/docs/user-guide/settings/account/team-management/manage-members#delete-a-member)
## Edit a Member’s Role
> [!NOTE]
>
> The **Edit role** option is displayed for members whose status is **Pending** or **Joined**.
To edit a member’s role, perform the following steps:
1. On the **Members** tab, click the ellipsis icon adjacent to the member you want to edit under the **Action** column.

2. Click **Edit role**.  The **Edit role(s)** pop-up window appears.
3. In the **Select Role** list, select the desired role.
4. Click **Done**.

The member role is now assigned successfully.
> [!NOTE]
>
> After the role change, the member will be automatically logged out of the dashboard.
## Revoke a Member’s Access
> [!NOTE]
>
> * The **Revoke access** option is displayed for members whose status is **Pending** or **Joined**.
> * When user access is revoked, any data created by that user, such as campaigns, reports, or segments, is not deleted from the system.
To revoke a member’s access to a workspace, perform the following steps:
1. On the **Members** tab, click the ellipsis icon adjacent to the member you want to revoke access from, under the **Action** column. 
2. Click **Revoke access**.  The **Revoke access** pop-up window appears, prompting for confirmation to revoke the member's access.
3. Click **Revoke**.

The member's access has been successfully revoked.
## Grant Access to a Member
> [!NOTE]
>
> The **Grant access** is displayed for members whose status is **Access revoked**.
To grant a member access to a workspace, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Members** tab, click the ellipsis icon adjacent to the member you want to grant access to, under the **Action** column.

3. Click **Grant access**.

The member's access has been successfully granted.
## Resend Invite to a Member
> [!NOTE]
>
> The **Resend invite** is displayed for members whose status is **Pending**.
To resend the invite to a member, perform the following steps:
1. On the **Members** tab, click the ellipsis icon adjacent to the member you want to reinvite, under the **Action** column.

2. Click **Resend invite**. 
The invite has been successfully sent to the member.
## Delete a Member
> [!NOTE]
>
> * The **Delete user** option is displayed for members whose status is **Pending**, **Joined**, or **Access Revoked**. Deleting a member permanently removes their profile from the workspace. Any data created by that user, such as campaigns, reports, or segments, remains in the system.
> * You can delete a member only if they have a role with permissions less than or equal to your role. For example, only a user with the Admin role can delete another user with the Admin role.
To delete a member, perform the following steps:
1. On the **Members** tab, click the ellipsis icon adjacent to the member you want to delete, under the **Action** column.

2. Click **Delete user**. \
The **Delete User** pop-up window appears, prompting for confirmation to delete the member.
3. Click **Delete**.

You deleted the member successfully.
# Bulk Edit Members
This feature enables you to perform bulk edits for multiple users. The bulk edit actions available in the **Action** column vary based on the members' statuses.
### Members with the Same Status
When you select one or more members of the same status, you can perform the following bulk edits.
Status
Options
Description
**Pending**
Edit
This enables you to edit the role of any member.
Resend invite
This enables you to invite the particular member to join the workspace again.
Export Members
This enables you to export members in a CSV file format.
Revoke access
This enables you to revoke the member's access and remove the user from the account.
Delete user
This enables you to permanently remove a member from the workspace.
**Joined**
Edit
This enables you to edit the role of any member.
Export Members
This enables you to export members in a CSV file format.
Revoke access
This enables you to revoke the member's access and remove the user from the account.
Delete user
This enables you to permanently remove a member from the workspace.
**Access revoked**
Grant access
This enables you to grant access to the members.
Export Members
This enables you to export members in a CSV file format.
Delete user
This enables you to permanently remove a member from the workspace.
### Members with Different Statuses
When you select one or more members of different statuses, you can perform the following bulk edits.
Status
Options
Joined and Pending
Edit
Export Members
Revoke access
Delete user
Joined and Access revoked
Edit
Export Members
Delete user
Pending and Access revoked
Edit
Export Members
Resend invite
Delete user
All members on a page
Edit
Export Members
Resend invite
Delete user
You can perform the following bulk edits on team members in the **Action** column:
* [Edit Roles of Members](/docs/user-guide/settings/account/team-management/manage-members#edit-roles-of-members)
* [Export Members](/docs/user-guide/settings/account/team-management/manage-members#export-members)
* [Revoke Access](/docs/user-guide/settings/account/team-management/manage-members#revoke-access)
* [Grant Access](/docs/user-guide/settings/account/team-management/manage-members#grant-access)
* [Resend Invite](/docs/user-guide/settings/account/team-management/manage-members#resend-invite)
* [Delete Members](/docs/user-guide/settings/account/team-management/manage-members#delete-members)
## Edit Roles of Members
To bulk edit members, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, you will be in the **Members** tab by default.

3. Select the check boxes adjacent to one or more members that you want to bulk edit.
4. To view the list of selected members, turn the **Show Selected** toggle on.

5. Click the ellipsis icon, and then click **Edit**.

The Edit Members pop-up window appears.
6. Click **Edit Role** and change the role for the members. The same role will be assigned to all members.
7. Click **Done**.

The members are updated successfully.
## Export Members
To bulk export members, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, by default, you will be in the **Members** tab. 
3. Select the check boxes adjacent to one or more members that you want to bulk export.
4. To view the list of selected members, turn the **Show Selected** toggle on.
5. Click the ellipsis icon and then click **Export members**. \
The members' list is successfully emailed to you in CSV file format.
## Revoke Access
To perform bulk revoke access, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, by default, you will be in the **Members** tab. 
3. Select the check boxes adjacent to one or more members for which you want to perform bulk revoke access.
4. To view the list of selected members, turn the **Show Selected** toggle on.
5. Click the ellipsis icon and then click **Revoke access**. 
6. The **Revoke access** pop-up window will appear, prompting for confirmation to revoke the access of the members.
7. Click **Revoke**.

The members' access is now successfully revoked.
## Grant Access
To perform bulk grant access, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, by default, you will be in the **Members** tab. 
3. Select the check boxes adjacent to one or more members for which you want to perform bulk grant access.
4. To view the list of selected members, turn the **Show Selected** toggle on.
5. Click the ellipsis icon and then click **Grant access**. \
The members' access is now successfully granted.
## Resend Invite
> [!NOTE]
>
> The **Resend invite** is displayed for members whose status is **Pending**.
To bulk resend invites, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, by default, you will be in the **Members** tab. 
3. Select the check boxes adjacent to one or more members for which you want to perform bulk resend invites.
4. To view the list of selected members, turn the **Show Selected** toggle on.
5. Click the ellipsis icon and then click **Resend Invite**. \
The members are re-invited successfully.
## Delete Members
To bulk delete members, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Account** > **Team Management** > **Members**.
2. On the **Team management** page, by default, you are on the **Members** tab by default. 
3. Select the check boxes adjacent to one or more members whom you want to bulk delete.
4. To view the list of selected members, turn the **Show Selected** toggle on.
5. Click the ellipsis icon next to the **Show Selected** toggle, and then click **Delete user**.  The **Delete User** pop-up window appears, prompting for confirmation to delete the members.
6. Click **Delete**.

You deleted the members successfully.
# FAQ
**How to recover Admin access and assign it to a new user if the original Admin account is deactivated?**\
Suppose your organization’s sole admin account has been deactivated, and you no longer have access to it. In that case, you can still recover admin access and assign new admin privileges by following these steps:
* Contact your organization’s IT administrator or domain owner to temporarily reactivate and grant access to the email account of the workspace's admin.
* Once the account is reactivated, use the Forgot Password option on the MoEngage login page to reset the password for that admin user account.
* After resetting the password, log in to the account and assign admin access to an existing user within your workspace or invite a new user with Admin access. This new admin will then have access to the MoEngage dashboard for that project.
* *(Optional)* Revoke the former admin's access from the workspace.
To prevent similar issues in the future, MoEngage recommends assigning admin roles to at least two users. This ensures that if one admin leaves or becomes unavailable, the other can still manage the workspace and perform necessary administrative tasks.
# Teams 2.0 in MoEngage
Source: https://moengage.com/docs/user-guide/settings/account/team-management/teams-20-in-moengage
Organize teams by location, language, or custom attributes in MoEngage Teams 2.0 to control access to campaigns, analytics, and user data.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
Teams can be set up across your customers based on location, language, and custom attributes. This allows you to view and access campaigns, analytics, and customer databases specific to the customers you are handling. Teams in MoEngage support team selection and team-based filters for segmentation, campaigns, and analytics.
For example, businesses operating in multiple countries often require their marketers to have access to data and audiences specific to their respective countries and brands. Teams in MoEngage provide marketers with this particular access, ensuring that customers of a particular brand from a country are not mistakenly targeted with promotions intended for another country. It also allows leadership to view analytics dashboards restricted to their specific region or brand.
# Create a New Team
Users with access to the *Create and Manage* permission under the permission set **Teams** can create, edit, and delete a team. Perform the following steps to create a new team:
1. Navigate to **Settings** > **Account** > **Team management** > **Teams**.
2. Click **+ Create Team**. The **Create Team** screen is displayed.

3. Enter the following details:
| Field | Description |
| - | - |
| **Team Name** | Specify a unique name for your team. |
| **Description** | Add details about the purpose of the team. |
| **Define the targeting criteria for the team** | In the select attribute drop-down list, select the user property to filter the users to be targeted by the team being created. You can add up to 5 user properties to define the team. For example, if your team runs campaigns targeted at users in a specific city, such as New York, you can add the filter condition, as in the following image:  |
4. Click **Create**. You get a success message upon successful creation, as shown in the following image.

5. The newly created team is available at the end in the left menu on the **Teams** page.
# Edit a Team
You can edit the name and description of a team. To edit a team:
1. Navigate to **Settings** **-> Account -> Team management -> Teams**.
2. Select the relevant team from the left navigation menu that you want to edit.
3. Click on the vertical ellipsis icon beside **Description**.

4. Click **Edit team**. The **Edit team** page is displayed.
5. You can edit the **Team Name**, **Description**, and targeting criteria.
6. Click **Save**. You will be prompted for confirmation.

7. Note that editing a team's targeting criteria impacts active campaigns in their next run. For example, your current target segment for the team is users in two countries, France and Belgium. If you remove users in Belgium from this target user set by editing the segment criteria, the user base targeted in the next run of your active campaigns will be impacted (only users in France will be targeted for the campaigns run by the team).
# Remove a Team
Follow the steps below to remove a team:
1. Navigate to **Settings** > **Account** > **Team management** > **Teams**.
2. Select the relevant team from the left navigation menu that you want to delete.
3. Click on the vertical ellipsis icon beside **Description**.
4. Click **Delete team**. You are prompted for confirmation and notified of the following:
* When you delete a team, its campaigns and custom segments are moved to the default team.
* The team members of your team will be moved to the default team.
* All campaigns in the active state for your current team will be paused.
* A list of active campaigns for the team is listed. You can download this list as a CSV file by clicking **Download**. You can click the individual hyperlinks for each of the active campaigns to see the campaign's analytics and info.

5. Click **Delete** to delete the team.
# Team Select and Filter with Segments
## Create Segments with a Team-Based Filter
After [creating Teams](/docs/user-guide/settings/account/team-management/teams-in-moengage#create-a-new-team), follow the below steps to create segments based on the teams you created.
1. Log in to the MoEngage dashboard.
2. Navigate to **Segments** > **Create Segments**.
3. You can select the teams you are a member of from the **Create segment for** drop-down list at the top. When selected, the team-based filter is applied to the segment you are creating. The team name can be any.\
For example, in the image below, the Team *Test brand* is selected, and the targeting criteria for the *Test-brand* team are automatically applied to the segment. This creates a segment targeted to *Test-brand,* which also fulfills the **Filter users by** condition.
4. If you select **All users**, the segment targets users in the selected Team.

5. Proceed to the next steps of creating the segment. For more information, refer to [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
## View Segments Based on Selected Team
MoEngage allows you to view the segments based on teams created. Follow the steps below to view segments based on the team selected.
1. Log in to the MoEngage dashboard.
2. Navigate to **Segments** > **All Segments**.
3. You can select Teams in which you are a member from the **All Segments for** drop-down at the top. All the segments valid for that Team are listed.

# Team Select and Filter with Analytics
## Create Analysis with a Team-Based Filter
After [creating Teams](/docs/user-guide/settings/account/team-management/teams-in-moengage), follow these steps to create and view analyses based on the teams you are part of.
1. Navigate to **Analyze** and select any Analytics category (for example, **Behavior**, **Funnels**, or **Retention**).
2. At the top of the page, select a team from the list. Only teams you are a member of are visible.

After you select a team, its targeting criteria are applied as a filter to your analysis. Any analysis you create considers only users who match the selected team's definition.

## Impact on Custom Dashboards
You can filter custom dashboards by the selected team.
* **Viewing dashboards**: When you select a team, you see the Workspace, Private, and Shared dashboards associated with that team. You cannot view a dashboard created for a team you are not a part of.
* **Workspace dashboards**: These dashboards have the team's criteria automatically applied. You can be view, edit, and share them among members of the same team.
* **Private dashboards**: These dashboards also have the team criteria automatically applied. You can share a private dashboard only with members of the same team.
* **Dashboard filters**: Applying a dashboard-level filter works with the team filter. The dashboard filter overrides any existing analysis-level filters, but the team's core targeting criteria are always applied.
## Impact on Dashboard Subscriptions
The Dashboard subscriptions page also has a Teams selector. Here, you can view the list of subscriptions for workspace and private dashboards filtered by teams.

## Impact on My Studio
You can view the analyses filtered by teams in the My Studio page.
* A team drop-down is available at the top of the **My Studio** page. The view in the **Saved Analysis**, **Drafts**, and **Shared with you** tabs is updated based on the selected team.

* When you save an analysis, it is associated with the currently selected team.
* You can share saved analysis or add collaborators only from within the same team.
> [!NOTE]
>
> When the Teams feature is enabled, all existing saved analyses, shared analyses, and custom dashboards are automatically assigned to the **Default team** configured in the **Team management** section of the **Settings** page.
# Team Select and Filter with Campaigns
## Create Campaigns with Team-Based Filter
After [creating Teams](/docs/user-guide/settings/account/team-management/teams-in-moengage), follow the below steps to create campaigns based on the Teams you created.
1. Log in to MoEngage **Create New** > **Campaign**.
2. Select any campaign you want to create. For the channels with team support, refer to [Channels with Teams Support](/docs/user-guide/settings/account/team-management/teams-20-in-moengage#impact-on-my-studio).
3. In the Step 1-**Target Users** page, select a team from the **Teams** drop-down list.\
 After the team is selected, the team-based filter is applied to the campaign you are creating. For example, in the image below, the Team *Test brand* is selected, and the targeting criteria for the *Test brand* team are automatically applied to the campaign. This creates a campaign that is targeted to *core-users* which fulfills the **Filter users by** condition under the **Select users** section.
4. If you select **All users**, the campaign targets users on the selected team.

5. Proceed to the next steps of creating campaigns based on the campaign type.
## View Campaigns Based on the Selected Team
MoEngage allows you to view the campaigns based on teams created. Follow the steps below to view campaigns based on the team selected.
1. Log in to the MoEngage dashboard.
2. Navigate to **Engage** > **Campaigns**.
3. On the **All campaigns** page, select teams in which you are a member from the **All campaigns for** drop-down list at the top. All the campaigns valid for that team are listed.

# Features with Teams Support
The table below lists the support for Teams 2.0 across different features.
| Feature/Channel | Support for Teams 2.0 |
| - | - |
| Analytics (Behavior, Funnels, Retention, Session & Source, User Paths, RFM) | Yes |
| Custom Dashboards | Yes |
| My Studio | Yes |
| Push | Yes |
| SMS & RCS | Yes |
| Email | Yes |
| WhatsApp | Yes |
| In-app | Yes |
| OSM | Yes |
| Flows | Yes |
| Default Dashboards (Key Metrics, Campaign Stats, etc.) | No |
| Analytics (Uninstall, Acquisition) | No |
| Cards | No |
| Facebook | No |
| Google Ads | No |
| Connectors | No |
# Teams in MoEngage
Source: https://moengage.com/docs/user-guide/settings/account/team-management/teams-in-moengage
Create and manage multiple teams in your MoEngage workspace, define audience scope, and control which end users each team can target.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
MoEngage supports the management of multiple teams for a workspace. A team is a group of MoEngage users using the MoEngage dashboard and collaborating on the same campaigns. You can create teams out of users from the same geography or from the same vertical within the enterprise. You can define the end user/audience scope for your team by defining the users who can be targeted for campaigns run by them.
# Create a New Team
Users with access to the *Create and Manage* permission under the permission set "Teams" can create, edit, and delete a team.
To add a new team:
1. Navigate to **Settings** -> **Account** -> **Team management -> Teams**.
2. Click **+ Create Team**. The **Create Team** screen is displayed.

3. Enter the following fields:
| Field | Description |
| - | - |
| **Team Name** | Specify a unique name for your team. |
| **Description** | Add details about the purpose of the team. |
4. Click **Create**. You get a success message upon successful creation, as shown in the following image.

5. The newly created team is available at the end in the left menu on the **Teams** page.
> [!NOTE]
>
> * You can create teams in both Test and Live environments by switching between the environments.
> * The number of teams a user is allowed to create for a workspace on MoEngage is not restricted.
> * The Team Management capability is disabled by default. When the option is enabled, all the existing campaigns and users become part of one team with the same name as the workspace.
> * You can add other teams later on to the workspace. The default team cannot be deleted or edited.
> * Any newly created team automatically includes all the admins.
# Edit a Team
You can edit the name and description of a team. To edit a team:
1. Navigate to **Settings** **-> Account -> Team management -> Teams**.
2. Select the relevant team from the left navigation menu that you want to edit.
3. Click the ellipsis beside the **Description**.

4. Click **Edit team**. The **Edit team** page is displayed.
5. You can edit the **Team Name** and **Description.**
6. Click **Save**.
# Remove a Team
To remove a team:
1. Navigate to **Settings** -> **Account** -> **Team management** -> **Teams**.
2. Select the relevant team from the left navigation menu that you want to delete.
3. Click the ellipsis next to the **Description**.
1. When you delete a team, its campaigns and custom segments are moved to the default team.
2. Your team members will be moved to the default team. Click **Delete team**. You are prompted for confirmation.
4. Click \*\*Delete \*\*to delete the team.
# Add Users to a Team
Existing team members with access to the “Create and Manage” permission under the permission set "Teams" can invite users to a team.
Users can be part of multiple teams but will have permissions for the same role across all the teams that they are part of. Each team can have users with all the possible roles. For more information about different access roles, refer to [Different Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
To add a user,
1. Navigate to **Settings -> Account -> Team management -> Teams**.
2. Select the relevant team from the left navigation menu to which you want to add the user.
3. Click **+ Add Team Member(s)**.

4. Select the relevant users you want to add from the **Email** drop-down.

5. Click **Add**.
Admins are part of all teams created for a workspace. A workspace can have multiple Admins.
# Remove Users from a Team
To remove a user:
1. Navigate to **Settings** -> **Account** -> **Team management** -> **Teams**.
2. Select the relevant team from the left navigation menu from which you want to remove the user.
3. Click on the vertical ellipsis icon next to the user you want to remove.

4. Click **Remove member**.
An Admin cannot be removed from a team.
# Manage Members of a Team
## Team View
Users who are part of multiple teams can switch between them using the Teams drop-down list in the team management section of the dashboard. The team view lists the members of that team only.
## Edit a User Role
Team members can edit the roles of other team members based on the role hierarchy. A user with the same or superior role as theirs can change each user's role.
## Team Access Management
Each user's access to the team can be removed by a user with the same or superior role to theirs. When removed, the user will lose access to that team's dashboard but will continue to have access to other teams' dashboards. If the user is part of only one team, they will lose access to the workspace altogether.
This is in addition to the option of revoking a user's access to the workspace, which will cause the user to lose access to all the teams he is part of for that workspace.
# Channels with Teams Support
| Channels | Teams |
| - | - |
| Push | Yes |
| SMS & RCS | Yes |
| Email | Yes |
| WhatsApp | Yes |
| In-app | Yes |
| OSM | Yes |
| Cards | No |
| Facebook | Yes |
| Google Ads | Yes |
| Connectors | Yes |
| Flows | No |
# Campaign Creation and Campaign Visibility for Team Members
## Campaign Creation
Every team member can create campaigns only for the teams they are part of. Team members who are part of multiple teams must select the team they want to create the campaign for as the mandatory first step in the campaign creation process. The team selection step is as follows:

### Change the Team Name in a Published Campaign
If you change the team while editing a published campaign:
* If the team name is edited before the start time of the campaign, you are notified that the segmentation and reachability will be recalculated based on the newly selected team (the new team's segmentation filters apply to the campaign's target audience now), as shown in the following image. 
* If the campaign sending is in progress, you cannot edit the team. You can only edit the team for a campaign before the Scheduled and Active campaigns start.
## Campaign Visibility
Team members can only see the campaigns created for their team, either by themselves or by other team members.
Team members who are part of multiple teams or admins who are part of all teams see campaigns from all teams they are part of on the All campaigns page on the dashboard. Team members can choose to filter the campaigns using the team from the **All campaigns for** drop-down list available at the top of the page, as depicted in the image below. The same applies to campaign drafts as well.

> [!WARNING]
>
> When the Team Management feature is enabled for a workspace, existing campaigns and team members are moved to the default team.
# Add a Content API
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/add-a-content-api
Add and configure a content API in MoEngage to use dynamic external data in your campaigns. Personalize API parameters with user properties.
To set up an API to be used during MoEngage campaigns, perform the following steps:
1. Navigate to the MoEngage Dashboard > **Settings** > **Advanced Settings**.
2. Click **Content API**.
3. Click **+ Add content API**. The Add content API screen pops up.

4. Fill in the following details:
| Field | Description |
| - | - |
| API name | Add the name for the content API here. |
| Method | The following methods are supported for Content APIs:
GET
POST
PUT
Select the HTTP Request method of the content API being configured. **Note**: The POST option will be enabled on request. Contact your CSM or the MoEngage Support team to enable it. |
| Enable OAuth | Enable this toggle if the Content API requires OAuth 2.0 authentication. A dropdown menu appears, allowing you to select a pre-configured OAuth setting. To learn how to create and manage OAuth settings, refer to [Authorization Configuration with OAuth 2.0](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20). \[!NOTE]
Only OAuth configurations with an "*Active*" status will be available for selection in the dropdown.
If an active OAuth configuration used by your API expires, its status will change to "Failed". When you edit the Content API, an error message is displayed, and you will need to select a new, active OAuth configuration.
**Note**: The OAuth option will be enabled on request. Contact your CSM or the MoEngage Support team to enable it. |
| URL | Add the URL of the Content API to which the request will be sent. |
| URL Parameters | Add the URL parameters to be passed in the request. Click *+KV pair* if more than one URL parameter is required. |
| Headers | Add the Headers to be added to the request. Click *+KV pair* if more than one header is required. |
| Dynamic values | Provide a sample value for the parameters to ensure that the API is set up properly. You can select any user profile or event to populate these values. |
5. To [personalize the parameters](/docs/user-guide/campaigns-and-channels/getting-started/message-personalization), type @ and use the user properties for personalization.\
For more information, refer to [Derived Events & Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes).

# Add UTM Parameters to Campaigns
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/add-utm-parameters-to-campaigns
Add UTM parameters to your MoEngage campaigns to track traffic sources, user engagement, and campaign performance in analytics platforms.
# Overview
Urchin Tracking Module (UTM) parameters are tags or simple snippet codes added to the end of a URL. You can customise these parameters based on your requirements to accurately track user engagement from different traffic sources in your analytics software.
When your audience visits the URL appended with these parameters, your analytics software can track information, such as where clicks came from, what campaign directed the clicks to your website, how visitors came to your website, and whether visitors interacted with any content associated with a campaign.
# Feature Support Matrix
The following table outlines where the UTM parameters are supported across different channels and features within MoEngage.
| Channel / Module | Supported |
| - | - |
| **Email** | ✅ |
| **Push** | ✅ |
| **SMS** | ✅ |
| **WhatsApp** | ✅ |
| **In-App** | ✅ |
| **OSM** | ✅ |
| **Inform** | ❌ |
| **Flows** | ✅ |
| **Connectors** | NA |
| **RCS** | ❌ |
| **Cards** | ✅ |
You can set UTM parameters for each campaign individually. The changes you make in the UTM parameters at the campaign level override the general UTM parameters configured at the account level. These changes are applicable only to the specific campaign you are creating or editing and do not impact the general UTM parameters. For more information, refer to [Configure General UTM Parameters at Account Level](/docs/user-guide/settings/advanced-settings/configure-general-utm-parameters-at-account-level).
> [!NOTE]
>
> * MoEngage automatically inserts the general UTM parameters at the end of the links used in all the campaigns.
> * If you manually pass any UTM parameters as part of the URL for the current campaign, MoEngage skips the general UTM parameters.
> * Only the roles that are allowed to create campaigns and flows (Marketer, Manager, and Admin when CAF is OFF) can turn on or off the **UTM parameters** toggle.
# Configure UTM Parameters for Campaigns
In the example below, we have outlined the steps to add UTM parameters to an Email campaign:
1. Ensure that the general UTM parameters are turned on at **Settings** > **App** > **UTM tracking**. 
2. In the email template editor, go to the **UTM parameters** section. 
3. Click the accordion to expand the parameters.
> [!NOTE]
>
> If the UTM parameters are enabled in the general settings, the **UTM parameters** toggle for the current campaign is turned on. By default, the UTM parameters configured in general settings are carried over to the campaign.

4. Edit the value of UTM parameters. In all value fields, you can enter a static value or select a dynamic value. When you enter '@', a searchable drop-down list of values is displayed. The value field cannot be empty.
5. Enable or disable individual parameters. You cannot disable the *utm_source* and *utm_medium* parameters. 
6. Click **+ Create custom parameter** to add a custom UTM parameter as a key-value pair.
7. Click the delete icon for the custom parameter that is no longer required. You can delete custom UTM parameters that are carried over from the general settings. 
8. Turn off the **UTM parameters** toggle to disable the usage of UTM parameters in the current campaign. In that case, MoEngage does not insert UTM parameters in the links used in the current campaign. 
# Configure UTM Parameters for Campaigns in Flows
In addition to standalone campaigns, you can set specific UTM parameters for campaigns that are part of a MoEngage Flow. For a campaign created inside a Flow, the general UTM parameters configured for flows at the account level are populated by default. You can override these values and add more custom parameters to them.
In the example below, we have outlined the steps to add UTM parameters for Emails in Flows:
1. Ensure that the general UTM parameters are turned on at **Settings** > **App** > **UTM tracking**. For example: 
2. In the canvas of the flow, click **+**.
3. On the **Add Stage** page, select the **Actions** > **Messaging** > **Email**. 
4. Hover over **Email** and click the **Edit** icon.
5. In the email template editor, go to the **UTM parameters** section. 
6. The process for editing these parameters now follows the same method as the one for a standalone campaign. You can:
* Edit the value of any parameter.
* Enable or disable individual parameters.
* Add new custom parameters using **+ Create custom parameter**.
* Delete custom parameters.
For a detailed guide on each of these actions, refer to steps 4-7 in the [Configure UTM Parameters for Campaigns](/docs/user-guide/settings/advanced-settings/add-utm-parameters-to-campaigns#feature-support-matrix) section above.
> [!NOTE]
>
> * The links you add in the email will be wrapped up with UTM parameters. When the user clicks the links, they can see the UTM parameters with their values in the URL.
> * In the case of SMS and WhatsApp, you can add the UTM parameters only to the shortened links.
> * When shortened links are used in SMS and WhatsApp, the UTM parameters are visible once you click the link and land on the destination page.
> * Dynamic values will be fetched during runtime. If a dynamic parameter is not available for any campaign, the UTM parameter using that dynamic value is not appended to the link.
> * URLs fetched from the Content API are added to the link with UTM parameters at runtime.
> * If you use any space or special character while sending the UTM parameters as part of the link, URL encoding is supported.
# Authorization Configuration with OAuth 2.0
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20
Configure OAuth 2.0 authentication in MoEngage to centrally manage access tokens for custom connectors and content API integrations.
MoEngage allows you to configure and centrally manage OAuth 2.0 authentication services that fetch and refresh access tokens. Once configured, these authentication settings can be easily selected from a dropdown menu when setting up various services, such as Custom Connectors or Content APIs.
As a marketer, while creating a custom connector campaign (in step 2 Content) or configuring a custom SMS connector, you can use OAuth 2.0 as authentication. For more information, refer to [Create a Connector Campaign](/docs/user-guide/campaigns-and-channels/connectors/create/create-a-connector-campaign) and [Configure Custom Connector (Service Provider)](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/sms/getting-started-with-sms/configure-custom-connector-for-sms).
This article explains how to configure and manage OAuth 2.0 settings.
# Add an OAuth 2.0 Configuration
1. Navigate to the MoEngage Dashboard and select **Settings** > **Advanced settings** > **Authorization configuration**. The Authorization configuration page is displayed.
2. Click **+ Add OAuth config**. The Setup Authorization page is displayed. 
Adding an OAuth 2.0 configuration involves the following steps:
1. [OAuth details](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20#step-1-oauth-details): Define the target audience for the campaign.
2. [Response settings](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20#step-2-response-settings): Define the content of the connector campaign to be sent or the custom SMS connector.
## Step 1: OAuth Details
On the OAuth details tab, enter the following details:
1. **OAuth name**: Enter a name for OAuth configuration. These settings would be available for selection during campaign creation.
2. **Grant type**: Currently Client Credential grant type is supported. If you are using any other grant types, for further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
3. **Token type**: Select a token type. Supported values are:
* Opaque: Select this option if the token issuer uses Opaque tokens. Here the response from the issuer will contain the expiry time alongside the opaque access token.
* JWT: If you select this option, the access token and the expiry time is encoded in the response as JSON Web Token (JWT) in Step 2 Response settings. You must decode the response to get the expiry time.
4. Under **API details**, provide the details required to fetch the access token. Please check the API documentation of the OAuth service you plan to implement.
5. **API URL**: Enter the API URL.
6. **Method**: Select the API method. The following are the supported methods and available fields for each method:
| Method | Supported Fields |
| - | - |
| GET |
URL parameters
Headers
|
| POST |
URL parameters
Headers
Body type
|
| PUT |
URL parameters
Headers
Body type
|
| DELETE |
URL parameters
Headers
Body type
|
7. **URL parameters**: Click **+ KV pair** and enter the parameters for the API.
8. **Headers**: Click **+ KV pair** and enter the headers for the API.
9. **Body type**: Configure the body for your requests using the following options:
> [tab] Form
>
> Create the body based on the form-encoded serialization for the webhook. .
> [tab] JSON
>
> Create the body using the JSON format. Click **+ KV pair** to add more JSON content. 
> [tab] Raw
>
> Create the body using the raw text format. 
10. Click **Send test & continue** to test the configuration and move to the second step "Response settings".
> [!NOTE]
>
> If you face error after you click **Send test & continue**, please check the API configuration with your OAuth service provider documentation.
## Step 2: Response Settings
On the Response settings tab, enter the following details:
1. **OAuth delivery response**: The fields in this section depend on the token type chosen in Step 1 OAuth details.
> [tab] Opaque
>
> * If you have selected "Opaque" from the **Token type** drop-down list in Step 1 OAuth details, you will see only one **OAuth delivery response** field. The OAuth delivery response has a key with an expiry time, which is not encoded.
> * You can also see when was the response received. 
> * Select an expiry option from the **Expiry** drop-down list and select a value from the second drop-down list.
> * The values on the **Expiry** drop-down list depend on the kind of response received. 
> [tab] JWT
>
> * If you have selected "JWT" from the Token type drop-down list in Step 1 OAuth details, you will see two **OAuth delivery response** fields. 
> * In the first **OAuth delivery response** field, the response has a key with an expiry time, but the expiry time is encoded.
> * You can also see when was the response received.
> * From the **Access token** drop-down list, select a key that has the expiry time and click **Decode token type**. After the token type is decoded, you will receive one more response in the second **OAuth delivery response** field.
> * Select an expiry option from the **Expiry** drop-down list and select a value from the second drop-down list. The values on the **Expiry** drop-down list depend on the kind of response received. 
2. **Preferred prefix**: Select the preferred prefix of the OAuth setting.\
Marketers can create custom prefixes in addition to the default options. These prefixes can be used when creating a custom connector or configuring a custom SMS connector, and can be overridden at a campaign level.
3. **Preferred error codes**: In the **OAuth error code** field, enter the preferred error code of the Oauth setting for an authorization failure because of an expired token. This error code can be used to reattempt the connector campaign or custom SMS connector.
4. Click **Save**. Now this Oauth setting is active. You can now use this Oauth configuration while [creating a custom connector campaign](/docs/user-guide/campaigns-and-channels/connectors/create/create-a-connector-campaign) or [configuring a custom SMS connector](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/sms/getting-started-with-sms/configure-custom-connector-for-sms).
# Manage OAuth Settings
1. Navigate to the MoEngage Dashboard and select **Settings** > **Advanced settings** > **Authorization configuration**. The Authorization configuration page is displayed. You can see the existing OAuth settings configured. 
2. To see where a specific OAuth setting is used, click the View list for the required setting. A list of associated Content APIs, PII configurations, and Connector Campaigns is displayed. 
> [!NOTE]
>
> * A "Failed" OAuth setting means your OAuth configuration is unable to fetch a response. You must edit your OAuth configuration and send test again. Do not use failed OAuth settings while creating connector campaigns or configuring custom SMS connectors.
> * Only configurations with an "Active" status will be available for selection in dropdowns when setting up connectors or campaigns.
> * If an active OAuth configuration expires, its status will change to "Failed." When you edit a campaign or connector that uses this expired configuration, an error message will be displayed, and you will need to select a new, active OAuth configuration.
3. To edit an OAuth setting, click the ellipsis icon for the required OAuth setting and click **Edit**.
4. To delete an OAuth setting, click the ellipsis icon for the required OAuth setting and click **Delete**. If there are any campaigns associated with the OAuth setting, you will not be able to delete it. A warning is displayed with the list of associated campaigns. 
# Support Matrix
You can use the OAuth 2.0 configurations you set up here to authenticate requests in the following features:
* **Connector Campaigns**: Secure your connector campaigns. For more information, refer to [Create a Connector Campaign.](/docs/user-guide/campaigns-and-channels/connectors/create/create-a-connector-campaign)
* Custom Connectors: Secure your custom SMS campaigns.. For more information, refer to [Configure Custom Connectors for SMS](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/sms/getting-started-with-sms/configure-custom-connector-for-sms).
* **Content APIs**: Authenticate API calls used for real-time personalization. For more information, refer to [Add Content APIs](/docs/user-guide/settings/advanced-settings/add-a-content-api).
* **PII Tokenized Sending**: Secure the API used to fetch customer PII during campaign dispatch. For more information, refer to [PII Tokenized Sending](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-tokenized-sending).
* **Streams**: Authenticate the API endpoint that MoEngage Streams forwards event data to. For more information, refer to [Streams](/docs/api/data/moengage-streams).
# Campaign Attribution Settings
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/campaign-attribution-settings
Configure campaign attribution settings in MoEngage to define conversion windows, attribution models, and how campaign stats are calculated.
# Configure Attribution Settings
To configure the attribution settings:
1. Navigate to **Settings** -> **Advanced settings** -> **Conversion and attribution**.
2. The following fields are available:
| Field Name | Description |
| - | - |
| **Default Attribution Model** | Choose the attribution model for your campaigns and flows by selecting one of the following:
**All Interactions**
**Last Interaction**
For more information about how each of these models works, refer to [All Interactions model](/docs/user-guide/campaigns-and-channels/campaign-management-and-reports/conversion-and-attribution#all-interactions-model) and [Last Interaction model](/docs/user-guide/campaigns-and-channels/campaign-management-and-reports/conversion-and-attribution#how-the-all-interactions-model-works). |
| [**Conversion view**](/docs/user-guide/campaigns-and-channels/campaign-management-and-reports/conversion-and-attribution#all-interactions-model) | Each attribution model has certain attribution types associated with it. Based on the attribution model chosen, you get the following options in this dropdown list:
The All Interactions model has the following options: **View Through Attribution**, **Click Through Attribution**, and **In Session Attribution**.
The Last Interaction model has the following options: **Click Through Conversion** and **Total Conversions**.
|
3. Click **Save**. You are prompted for confirmation about changing the attribution model or type.
4. Click **Done**. You get a success message, as shown in the following image. 
## Switching Between Attribution Models
You can switch between the **All Interactions** and **Last Interaction** attribution models directly at **Settings** > **Advanced Settings** > **Conversion and Attribution**.
### Switching for the First Time
Say you are on the Last Interactions model and switch to the All Interaction model. The two models attribute conversions differently: All Interactions credits every campaign whose attribution window overlaps with a conversion, while Last Interaction credits only the campaign with the deepest and most recent engagement. Therefore, some campaigns may show a dip in conversion metrics after the switch. Switching in the other direction—from All Interaction to Last Interactions—can cause an apparent inflation in conversion numbers. For more information on how each model works, refer to [All Interactions Model](/docs/user-guide/campaigns-and-channels/campaign-management-and-reports/conversion-and-attribution#all-interactions-model) and [Last Interaction Model](/docs/user-guide/campaigns-and-channels/campaign-management-and-reports/conversion-and-attribution#last-interaction-model).

The first time you switch models, a 12-day comparison window starts automatically. During this window:
* MoEngage stores conversion data for both models simultaneously for the duration of the window.
* You can review and compare data across both models at any point during the 12 days.
* You can switch back to your original model within the window. MoEngage continues storing data for both models throughout the 12-day period.
Once you select a model after the comparison window, MoEngage stores data only for the selected model from that day onward.
### Switching After the Comparison Window
After the 12-day window ends, you can still switch models at any time. However, MoEngage retains data only for the actively selected model. If you switch back to a previously used model, conversion data from the period when that model was inactive will not be available. For example, if you switch from All Interaction to Last Interactions on day 15, conversions from days 13 and 14 will not be recorded under the Last Interaction model.

> [!WARNING]
>
> Switching models repeatedly after the comparison window ends creates gaps in your conversion data. Once you have decided on a model, MoEngage recommends staying with it.
### Impact on Reports and Analytics
When you switch attribution models, conversion data in your campaign and flow analytics changes immediately:
* Conversion data before the switch date shows as zero for the newly selected model. MoEngage starts collecting data for that model from the switch date onward.
* Banners appear on Campaign Analytics pages, Flow pages, and all campaign pages to inform you of the switch date and explain why historical conversion data shows zero.

* Existing scheduled and periodic reports that include conversion columns for the previously active model will show zero for any period after the switch date. Update those reports to include the conversion columns for the newly selected model.
## Switching Between Conversion Views
The conversion view you select here determines how conversion data is displayed across the All Campaigns page, All Flows page, and Campaign Analytics and Info pages.

For example, when the attribution model is All Interactions, and the default attribution type is View through attribution, the Campaign Analytics page shows calculated based on view through attribution. When you change the default to click-through, the statistics shown are for click-through attribution.
You can, however, change the attribution type in the **Attribution Type** filter in the Analytics section to see the metrics for other attribution types, as shown in the image below.

# Frequently Asked Questions
> [accordion] What if I switch models by mistake? Can I get my data back?
>
> It depends on when you catch the mistake. If you are still within the 12-day comparison window, switch back to your original model—MoEngage has been storing data for both models throughout the window, so no data is lost. If the comparison window has already ended, you cannot recover data from the period when the model was inactive. Switching back will create a gap for that period.
> [accordion] Does the attribution model apply to all campaigns and flows, or can I set it per campaign?
>
> The attribution model is an account-level setting. All campaigns and flows in your account use the model selected in **Settings** > **Advanced Settings** > **Conversion and Attribution**. You cannot set a different attribution model for individual campaigns or flows.
> [accordion] Does switching models affect campaigns that are already running?
>
> Yes. The change takes effect immediately across your entire account. Active campaigns will show zero conversions under the newly selected model for any period before the switch date. Conversions recorded after the switch date will be attributed under the new model going forward.
> [accordion] Does the 12-day comparison window restart if I switch models again after it ends?
>
> No. The 12-day comparison window only starts the first time you switch to a different model. Once the window ends, any subsequent model switch does not trigger a new comparison window. MoEngage stores data only for the actively selected model from that point, so switching after the window ends will create gaps in your data.
# Configure Custom Domain (Link Branding)
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/configure-custom-domain-link-branding
Set up custom domain link branding in MoEngage to replace default URLs with your branded domain in campaign messages and tracking links.
# Overview
This feature enables you to configure a custom domain to be used in the messages instead of the standard MoEngage Domain. A custom domain is a personalized domain name that lends your brand credibility and authority and differentiates you from the competition. Oftentimes, it becomes your brand's online identity. For example, it is common for customers to say Google it when they mean Google Search. Google's domain name is Google.com, and it is everyone's favorite moniker for the company's search feature!
The custom domain feature enables you to use your custom domain in the URLs sent in the message body of SMS, WhatsApp, or Email.
> [!NOTE]
>
> In the MoEngage Email context, Custom Domain is referred to as Link Branding.
For SMS & WhatsApp campaigns, any URL or link added to your message body is shortened with the chosen brand in the settings. For example, if the link used in the SMS or WhatsApp campaign is [*www.xyz.com/products/mobiles*](http://www.xyz.com/products/mobiles) and the custom domain selected is yourbrand.com, then the link will be displayed as *yourbrand.com/1234.*
For Email campaigns, any URL or link in the Email’s body is wrapped with the chosen Custom Domain. For example, if the selected domain is *yourbrand.com* in the Email Campaign and the Email has a link as [*www.xyz.com/products/mobiles*](http://www.xyz.com/products/mobiles), then the URL will be rendered as [*www.yourbrand.com/abc*](http://www.yourbrand.com/abc).
# Glossary
| Terms and Definitions | Applicable for SMS & WhatsApp, Email | Notes |
| - | - | - |
| **Domain**: A domain is that part of the URL that directs your users to a web server to fetch the web page content they are looking for. To visit your webpage, users must type the domain name containing the location of your site's files. A domain is the principal part of the URL that denotes to whom this URL belongs. This helps the user identify the brand sending them this URL in their communication. | All | |
| **Domain Name**: a unique string owned by the brand that can reflect the brand name without confusing the user. Examples: moengage.com, google.com, wikipedia.org. A **custom domain** is a purchased domain that allows you the flexibility to choose the name. For example, if you wish to name your domain YourBrand.com, you must purchase the domain name. | All | |
| **DNS**: Domain Name System. It is popularly referred to as the phonebook of the internet. It maps the domain name to the actual address of the resource and helps the browser load the requested web page. For example, if you were to type google.com on your browser, the DNS server would look up the actual location where the website's pages are located and return them to the browser. The browser would then fire a request for that specific location and get the webpage to be displayed. For more information, refer to [DNS](https://en.wikipedia.org/wiki/Domain_Name_System). | All | |
| **CNAME**: A canonical name or CNAME record is a type of DNS record that maps an alias name to a true domain name. For more information, refer to [CNAME Record](https://en.wikipedia.org/wiki/CNAME_record). | All | |
| **Click Tracking**: A feature that tracks which users have clicked on the links added in the message. MoEngage's proprietary technology facilitates this. When a user clicks on a URL in the message body, the click action is tracked, and this event is logged. This is helpful in understanding click behavior and engagement. | All | |
| MoEngage Standard Tracking Domain | SMS & WhatsApp | ux.mnge.co The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping [here](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
| | Email | For DC1: email-10.moengage.com For DC2,3,4,5,6, and 100: api-0X.moengage.com The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping [here](https://moengage.com/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
# How do CNAME Records work?
> [tab] SMS & Whatsapp
>
> If your domain name is *yourbrand.com* and you add the following link to your SMS or WhatsApp message body: [*http://www.yourbrand.com/producregistrationpage*](http://www.yourbrand.com/producregistrationpage) and shorten it using MoEngage’s default URL shortening, the URL will appear as *ux.moengage.com/register*. If you want your shortened URL to be *YourBrand* instead of *ux.mnge.co*, you should add a CNAME DNS record to your DNS, as shown below. The shortened URL would then be: *yourbrand.com/register*.
>
> | | | |
> | - | - | - |
> | Name | Type | Value |
> | YourBrand | CNAME | ux.mnge.co The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping [here](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
>
> When you request a web page, here’s what happens:
>
> 1. A DNS request is created to look up the actual location where the resource is located for the domain name in the URL.
> 2. The DNS resolver finds the actual location mapped to the domain name (this is called resolving the DNS) by fetching the CNAME record.
> 3. This CNAME is returned to the browser. The CNAME helps the user's app/browser understand the server domain that needs to be requested.
> 4. The browser sends a new DNS request for the IP/domain mapped to the CNAME, and the web page for the requested resource is located and returned
> [tab] Email
>
> If your domain name is *yourbrand.com* and you add the following link to your Email body: [*www.xyz.com/products/mobiles*](http://www.xyz.com/products/mobiles), the URL will appear as *api-0x.moengage.com/abc*. If you want your URL to be *YourBrand* instead of *api-0x.moengage.com*, you should add a CNAME DNS record to your DNS, as shown below. The URL would then be: *yourbrand.com/register. The URL would then be: yourbrand.com/abc*
>
> | | | |
> | - | - | - |
> | Name | Type | Value |
> | YourBrand | CNAME | bapi-0X.moengage.com The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping [here](/docs/user-guide/data/key-concepts/data-centers-in-moengage). |
>
> When you request a web page, here’s what happens:
>
> 1. A DNS request is created to look up the actual location where the resource is located for the domain name in the URL.
> 2. The DNS resolver finds the actual location mapped to the domain name (this is called resolving the DNS) by fetching the CNAME record.
> 3. This CNAME is returned to the browser. The CNAME helps the user's app/browser understand the server domain that needs to be requested.
> 4. The browser sends a new DNS request for the IP/domain mapped to the CNAME, and the web page for the requested resource is located and returned.
# Prerequisites
> [!NOTE]
>
> If you have Certificate Authority Authorization (CAA) records set up for your domain to control the Certificate Authorities (CAs) that can issue SSL certificates for their domain, please add [http://sectigo.com/](http://sectigo.com/) to the same before trying to set up a custom domain in MoEngage.
You need to set up a custom domain before configuring it in MoEngage. To set it up, do the following:
1. Look up a popular domain registrar (A domain name registrar provides domain name registrations to the general public. For example, GoDaddy and Google Domains)and look for a domain name that is not used.
2. Purchase the domain name. You can also purchase a custom domain from your web hosting provider. In case you have a custom domain, you can go ahead and skip to the next step.
3. Add a CNAME Record in your DNS to point to the MoEngage domain. For more information, refer to [How CNAME Records Work.](https://en.wikipedia.org/wiki/CNAME_record)
4. Set the Time To Live (TTL) to 30 minutes for this record.\
**Note**: If your DNS provider doesn’t support 30 min TTL, select the minimal TTL time frame supported by your DNS provider.
5. After the records and details are successfully added and verified on your DNS, you can add the custom domain in MoEngage.
> [!NOTE]
>
> You can use the same custom domain for SMS and WhatsApp. For Email, you need to set up a different custom domain.
# Configure a Custom Domain
To configure a Custom Domain for the SMS, WhatsApp, and Email channels:
Navigate to the MoEngage Dashboard and select **Settings** -> **Advanced settings** -> **Custom domain**. You can create custom domains for **SMS & WhatsApp** or **Email** by clicking the respective tabs on the **Custom domain** screen.
> [tab] SMS & WhatsApp
>
> Follow the below steps to configure custom domain for SMS & Whatsapp:
>
> 1. Make sure to follow the provided **Pre-requisites** to ensure that your custom domain is verified.
> 2. Add the custom domain name in the **Custom domain name** field and click **Verify.** You must not add *http\://*,*https\://* or [*www*](http://www)*.* to the domain name. Add the name as added in the CNAME record.
> 3. After verification, you get a message stating that the custom domain is verified, as shown below. 
> 4. Toggle **Shorten and track URL** **by default** to enable shortening and tracking of links added to SMS and WhatsApp messages using the custom domain. This will turn on the shortening and tracking of the URL for all SMS and WhatsApp campaigns. This ensures that tracking is automated and never missed. Also, it can be unchecked in the campaigns or turned off in the settings here when you do not wish to track clicks.
> [tab] Email
>
> You can add multiple link branding domains for email campaigns. Follow the below steps to configure a link branding domain for an email campaign:
>
> 1. To add a link branding domain, click the **+** **Add link branding**.
> 2. On the **Add link branding** page, you can select any one of the following options to add a link branding domain:
> 1. **Self managed**: Select this option if you don't want MoEngage to procure SSL certificates on your behalf. You must monitor and manage the SSL certificates, particularly when they are approaching expiration, and ensure their timely renewal.
> 2. **MoEngage managed**: Select this option if you want MoEngage to procure SSL certificates on your behalf. In this case, MoEngage procures and manages the SSL certificate when they are approaching expiration, and ensure their timely renewal.
> > [!NOTE]
> >
> > If you decide to proceed with the MoEngage managed option and have CAA enabled for the link branding domain, you must include Sectigo.com in the CAA, as MoEngage procures SSL certificates from Sectigo.com. If you do not prefer this, you can opt for the self-managed option.
> 3. Make sure the following **Prerequisites** are met based on the option you selected to manage the SSL certificates.
>
> > [!TIP]
> >
> > **Prerequisites**
> >
> > 1. If you choose to proceed with the Self managed option, the following are the prerequisites to be met to ensure that the custom domain is verified inside MoEngage:
> > * Add a CNAME record to your DNS that points to MoEngage. The details to be added include:
> > * Type: CNAME
> > * Name: Your preferred link domain (url.example.com). Refrain from adding https\:// or http\://
> > * Value: api-0x.moengage.com
> > * Set the Time To Live (TTL) to 30 minutes for this record. If your DNS provider does not support a 30-minute TTL, select the minimum TTL timeframe supported by your DNS provider.
> > 2. If you choose to proceed with the MoEngage managed option, the following are the prerequisites to be met to ensure that the custom domain is verified inside MoEngage:
> > * Add a CNAME record to your DNS that points to MoEngage. The details to be added includes:
> > * Type: CNAME
> > * Name: Your preferred link domain (url.example.com). Refrain from adding https\:// or http\://
> > * Value: ``.bapi-0x.moengage.com
> > * Set the Time To Live (TTL) to 30 minutes for this record. If your DNS provider does not support a 30-minute TTL, select the minimum TTL timeframe supported by your DNS provider.
> 4. Type the custom domain name in the **Custom domain name** field.
> 5. Select **Mark this domain as default** option, if you want this domain as your default domain.
> 6. Select the acknowledge option to recognize that the prerequisites are met, and click tracking is turned off in your ESP settings.
> 7. Click **Save**.
> > [!NOTE]
> >
> > * The maximum supported depth of the domain that can be added is six. For example, the depth of the sub1.sub2.sub3.sub4.sub5.sub6.com domain is six.
> > * Configuring a custom domain for Email will brand your links with your own domain instead of the standard MoEngage domain. Unlike its usage in SMS and WhatsApp, this feature does not result in link shortening; it is used exclusively to apply your brand to the URL without impacting the link's length.
> 8. After successfully verified and saved, your custom domain is listed under the **Custom domain** screen with a **Verified** tag against that custom domain. 
> 9. Click the ellipsis icon ( ) against any of your custom domains to mark it as **Default** or **Delete**.
> * If you have only one default link brand domain configured and delete the same, you cannot add this branding domain while creating the email campaign.
> * If you have configured multiple default link branding domains and delete one, any active campaign that uses the deleted link branding domain falls back to the new default link branding domain.\
> For more information on how to use a link branding domain while creating an email campaign, refer to [Create an Email Campaign](/docs/user-guide/campaigns-and-channels/email/create/create-an-email-campaign).
If you want to configure a deep linking domain for your brand, MoEngage recommends its Deep linking feature. For more information, refer to [Configure a Deep Linking Domain](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/configure-a-deep-linking-domain).
# Campaign Previews
For SMS & WhatsApp, when you add a link to the message body and the **Shorten and Track URLs option** is selected, the preview will display a shortened link, as shown below.
> [tab] SMS
>
> 
> [tab] WhatsApp
>
> 
> [!NOTE]
>
> * The URL displayed in the preview is only an example of how the real message body would look and is not the real URL that would be sent in the campaign.
> * To test how a user would receive the SMS, WhatsApp message, or Email use the Test Message(SMS), Test Campaign (WhatsApp, Email) feature and send a test message. You can view the URL as it would appear in your live campaign.
# Troubleshooting
If you get the error "Unable to verify. Check domain settings where this domain is managed and retry," make sure the DNS & CNAME mapping is done correctly in your specific Domain Registrar. To verify this, follow the steps your registrar has mentioned. If you don't have the required access, you can share these details with your IT admin, and they can help you in setting these up:
* [GoDaddy](https://ie.godaddy.com/help/add-a-cname-record-19236)
* [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records)
* [Microsoft Azure](https://azure.microsoft.com/en-us/blog/a-records-cname-and-using-dns-with-windows-azure-web-sites-waws/#:~:text=into%20the%20picture.-,CNAME%20record,-In%20a%20situation)
* [Google Domains](https://support.google.com/a/answer/47283?hl=en)
* [Shopify](https://help.shopify.com/en/manual/domains/managing-domains/edit-dns-settings#add-dns-record)
> [!NOTE]
>
> The **Unsubscribe URL** added in the **Email Settings** will not be a branded link if the unsubscribe URL is customized and not MoEngage’s default unsubscribe URL.
# Configure General UTM Parameters at Account Level
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/configure-general-utm-parameters-at-account-level
Define account-level UTM parameters in MoEngage to automatically append tracking codes to campaign URLs across all channels and campaigns.
Urchin Tracking Module (UTM) parameters are tags or simple snippet codes added to the end of a URL. You can customise these parameters based on your requirements to accurately track user engagement from different traffic sources in your analytics software.
When your audience visits the URL appended with these parameters, your analytics software can track information, such as where clicks came from, what campaign directed the clicks to your website, how visitors came to your website, and whether visitors interacted with any content associated with a campaign.
You can configure general UTM parameters at the account level, which are carried over to campaigns and flows. However, the marketer can override the general UTM parameters at the campaign level. For more information, refer to [Add UTM Parameters to Campaigns](/docs/user-guide/settings/advanced-settings/add-utm-parameters-to-campaigns).
> [!NOTE]
>
> The ability to enable, disable, or edit UTM parameters depends on your role. If the **Setup & manage** permission is enabled in the **App Configuration** component for your role, you can enable, disable, or edit UTM parameters. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
## Enable UTM Parameters
1. On the left navigation menu in the MoEngage UI, go to **Settings** > **Advanced Settings** > **UTM tracking**. The UTM tracking page is displayed.

2. Turn the **UTM parameters** toggle on.

The following non-deletable list of UTM parameters with campaign and flow values is displayed.
| UTM Parameter | Description | Default Campaign Value | Default Flow Value |
| - | - | - | - |
| utm_source | It determines the source of the traffic and helps to track where the traffic came from. The source can be a website, app, or link. For example, YouTube, Instagram, or Google. | MoEngage | MoEngage |
| utm_medium | It determines the type of channel and helps to track what type of traffic the visitor came from. For example, Push, SMS, and Email. | `{{channel}}` | `{{Flow Campaign Channel}}` |
| utm_campaign | It determines the name of the campaign and helps to track the performance of a specific campaign. For example, Newyear and Bigbillionday. | `{{Campaign Name}}` | `{{Flow Name}}` |
| utm_term | It determines search terms for paid traffic and helps track the keyword or term that led to the audience visiting your site. For example, Mobile+sale. | NA | NA |
| utm_content | It determines the content. It is the element that differentiates links pointing to the same URL. It helps identify the exact element on your campaign that was clicked. It is useful for for A/B testing. For example, banner, video, product image. | NA | NA |
## Configure UTM Parameters
1. Enable the **UTM parameters** toggle.
2. Configure the parameters as follows:
| UTM Parameter | Notes |
| - | - |
| utm_source | This is a mandatory parameter, so you cannot disable it. When the **UTM parameters** toggle button is enabled, this parameter is available with every link. The values for campaign and flow are populated by default. You can edit them if required. |
| utm_medium | This is a mandatory parameter, so you cannot disable it. When the **UTM parameters** toggle button is enabled, this parameter is available with every link. The values for campaign and flow are populated by default. You can edit them if required. |
| utm_campaign | You can use the toggle button to enable or disable the parameter. The values for campaign and flow are populated by default. You can edit them if required. |
| utm_term | This parameter is disabled by default. It does not have default values for campaign and flow. You can enable it based on the client's usage. Use the toggle button to enable or disable the parameter. |
| utm_content | This parameter is disabled by default. It does not have default values for campaign and flow. You can enable it based on the client's usage. Use the toggle button to enable or disable the parameter. |
3. Click **Save**.
> [!NOTE]
>
> * For utm_source and utm_medium, both campaign value and flow value are mandatory, so they cannot be empty.
> * For other fields, both values cannot be empty. Enter a value in one of the fields.
> * In all fields, you can enter a static value or select a dynamic value. When you enter '@', a searchable drop-down list of values is displayed.
> * The following are the dynamic values supported:
>
> | For Campaigns | For Flows |
> | - | - |
> | Campaign Id, Parent Campaign Id, Platform, Conversion Goal, Campaign Delivery Type, Campaign description, Custom segment, Campaign Name, Campaign Tags, Campaign Tags id, Locale Name, Variation Name, Campaign Channel. | Flow Name, Flow Child Campaign Name, Flow Id, Platform, Flow Delivery Type, Flow description, Custom segment, Flow Tags, Flow Conversion Goal, Flow Tags Id, Locale Name, Variation Name, Flow Campaign Channel. |
>
> * You can select multiple dynamic values in the **Campaign value** and **Flow value** fields for all parameters.
> * Double curly brackets are mandatory at the start and the end of a dynamic value. They are added by default when you select a dynamic value. For example, `{{Campaign Id}}`.
## Create a Custom UTM Parameter
Apart from the fixed parameters available by default, you can create custom UTM parameters based on your requirements.
1. Enable the **UTM parameters** toggle.
2. Click **+ Create custom parameter**. At the end of the list, a fresh key-value pair with empty values is generated.

3. Enter the following details:
1. In the **Utm parameters** column, enter a name for the UTM parameter.
* The parameter name can have a maximum of 50 characters.
* This is a mandatory field, so you cannot leave it blank.
* The name must be unique. If you enter a name that already exists, an error is displayed.
2. In the **Campaign value** column, enter a value for the parameter to be used in campaigns.
3. In the **Flow value** column, enter a value for the parameter to be used in flows.
4. Turn the toggle button off to disable a custom parameter.
5. Click the delete icon for the custom parameter that is no longer required.
* After you save the UTM parameters for the first time, if you try to delete a custom parameter, the Delete UTM parameter pop-up is displayed. Click **Delete**.

* After you delete a custom parameter, its values will not be automatically appended to the links in your campaigns or flows.
6. Click **Save**.
> [!NOTE]
>
> You can add a maximum of five custom parameters. After adding five params, the **+ Create custom parameter** button is disabled.
>
> 
## Edit UTM Parameters
After you save the UTM parameters for the first time, you can edit them whenever required.
1. Update the campaign values or flow values.
2. Turn the toggle button on or off to enable or disable a parameter. You cannot disable the utm_source and utm_medium parameters.
3. Click the custom parameter name and edit it. This field becomes editable when you hover over it.

4. Click **Save**. The Modify UTM parameter pop-up is displayed.
* Click **Modify** to update the changes only in the general settings. Future campaigns will have these changes.
* Click **Modify & update campaigns** to update these changes in existing campaigns.

> [!WARNING]
>
> **Critical**
>
> You must click **Modify & update campaigns** only if you are sure that you want to update all the running campaigns. Because it will impact all the existing standalone campaigns and campaigns created as part of flows.
## Disable UTM Parameters
You can disable UTM parameters if you no longer want to insert them automatically in the links used across campaigns.
1. Navigate to **Settings** > **Advanced Settings** > **UTM tracking**.
2. Turn the **UTM parameters** toggle off to disable it. The Disable UTM parameters pop-up is displayed.
* Click **Disable** to disable the changes only in general settings. After you disable UTM parameters, the values will not be automatically appended to the links in your future campaigns.
* Click **Disable & update campaigns** to update these changes in existing campaigns. All the running campaigns will be impacted.

> [!WARNING]
>
> **Critical**
>
> You must click **Disable & update campaigns** only if you are sure that you want to update all the running campaigns, because it will impact all the existing standalone campaigns and campaigns created as part of flows.
When the toggle is off, all previous data is hidden in the UTM parameters. When you enable the toggle next time, the previous data that you had entered is reflected again.
# E.164 Phone Number Format
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/e164-phone-number-format
Understand the E.164 phone number format used by MoEngage for SMS and WhatsApp, including country codes, structure, and formatting rules.
# Introduction
The E.164 phone number format is an international standard for phone number representation. The International Telecommunication Union - Telecommunication Standardization Sector (ITU-T) defines this format. E.164 numbers can have a maximum of 15 digits and include a country code, but do not include international call prefixes.
# Key Components of E.164 Format
E.164 formatted phone numbers contain:
* The prefix ”+”.
* **Country Code**: This is a one- to three-digit code that identifies the country. For example, "1" is the country code for the United States and Canada, and "91" is the country code for India. For the full list of country codes, refer to [Country Codes.](https://en.wikipedia.org/wiki/List_of_telephone_country_codes)
* **National Destination Code (NDC)**: This code identifies a specific region or network within the country.
* **Subscriber Number (SN)**: This is the unique number assigned to the subscriber.
Following is an example of a phone number in E.164 format:
An E.164 formatted phone number for a US number might look like this: +12125551234
* "+" indicates the prefix of the E.164 format.
* "1" is the country code for the US.
* "212" is the NDC (area code in this case).
* "5551234" is the subscriber number.
> [!NOTE]
>
> * When including the country code, omit any leading zeros from the national phone number.
> * Hyphens, spaces, and parentheses are not included in the E.164 format.
# Convert Local Formats to E.164
If you know the country code, you can easily convert a locally formatted phone number to an E.164 formatted number. Perform the following steps:
1. Remove any spaces, parenthesis or other punctuation.
2. If the number begins with a zero, remove the leading zero.
3. Prepend the country code.
4. Prepend a ”+”.
> [!WARNING]
>
> Phone numbers ingested into MoEngage must be in E.164 format. Invalid phone number format may lead to low deliverability of campaigns.
# Global Control Group
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/global-control-group
Create and manage a global control group in MoEngage to exclude a user segment from all marketing campaigns and measure true campaign lift.
# Overview
The global control group is a list of users who will not receive any of your marketing campaigns. It is a strategically selected subset of the entire user base that is intentionally excluded from receiving any marketing campaigns across all available channels. For more information, refer to [Control Groups](/docs/user-guide/campaigns-and-channels/getting-started/introduction/control-groups).
The global control group is established at the account level, encompassing a segment of your entire user base. You can create only one global control group for each workspace. This group remains consistently excluded from all marketing campaigns across all channels and campaign types. Its primary objective is to provide a holistic, account-wide benchmark for measuring the overall incremental impact of your marketing activities.
The concurrent execution of numerous marketing campaigns introduces a challenge in accurately quantifying the incremental uplift attributable to specific initiatives. While an end-user may be intentionally excluded from receiving communication within one particular campaign (via a campaign-level control group), they may still be exposed to and influenced by communications from other simultaneously active campaigns, potentially leading to conversion. Consequently, to obtain a precise measurement of the true overall impact of marketing efforts, a global-level control group is necessary. This group, by design, remains entirely unexposed to any campaign communication, providing a reliable baseline for comparison and enabling the accurate determination of actual uplift.
> [!TIP]
>
> **Prerequisite**
>
> To manage the global control group, you need an Admin role with the **Setup & manage** permission for the **Channel Configuration** component. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
# Enable the Global Control Group
1. On the left navigation menu in your MoEngage dashboard, click **Settings** > **Advanced settings** > **Control groups**. The Control groups page appears.
2. In the **Global control group** section, turn the **Status** toggle on to enable the global control group. \
The global control group is enabled for the current workspace. A confirmation message appears in the lower-right corner.

3. Click **Edit** to add details to the global control group. The following page appears, where you can define the control group:

4. You can create global control groups in two ways:
* **Random Allocation:** This method randomly allocates a fixed percentage of all your users to the global control group.
1. Click the **Random allocation** option.
2. In the text box below, type the percentage of all users whom you want to be allocated to the global control group. You can allocate a maximum of 10% of all users to the global control group.

> [!NOTE]
>
> * When the global control group is created with random allocation, it is created for all the users in the workspace at that time. For example, if a control group is defined as having 10% of all users, one in every 10 users will be a part of this control group.
> * The user allocation to the global control group is completely random.
> * New users who are added to the workspace after the control group is created will also be included in the group, as per the defined percentage of all users in the random allocation. That is, one in every 10 new users will be included in the control group.
* **Uploading user list:** In this method, you can upload a CSV file with a list of user IDs to create the global control group. All the users in the list will be added to the control group automatically.
1. Click the **Upload users list** option.
2. Click **Upload file or drag and drop here** to upload your CSV file.

**Note:** You can upload only a CSV file. The maximum file size for upload is 50 MB.
5. Select the **Apply global control group in all existing campaigns** check box if you want to apply the global control group to all existing campaigns. This will impact the existing scheduled or upcoming periodic campaigns.

6. Select the **Allow marketers to send campaigns to these users** check box if you want to allow marketers to decide during campaign creation whether to send campaigns to the users in the global control group. This is particularly useful when sending transaction communications or important messages such as mandatory app updates.\
By default, the global control group applies to all new campaigns. Selecting this check box will allow marketers to decide whether to use the control group when creating campaigns.

7. Click **Save changes**. The Save changes to control group pop-up window appears, prompting you for confirmation. After you save the changes, they will be applicable to all the existing campaigns.
8. Click **Confirm**.
> [!NOTE]
>
> * On completion of global control group creation, the system may take up to 24 hours to enable your global control group. You will be notified as soon as your control group is ready for use.
> * When a user is added to a control group, MoEngage raises an event named *User added to control group* with the attribute **Control Group** **type**, which has the value *Global*.
> * If the campaign qualifies a very small user base, there may be a condition that no user from the qualified user base is a part of the global control group. In that case, MoEngage will not showcase the control group stats for that campaign in [Uplift](/docs/user-guide/campaigns-and-channels/getting-started/introduction/control-groups).
9. Click **Download users** to download all users in the global control group. MoEngage generates a report and sends to your email ID.

10. To delete a control group:
1. Click **Delete**. The Delete control group pop-up window appears, prompting you for confirmation. After you delete a control group, MoEngage releases all its users. They will start receiving campaign messages henceforth.

2. Click **Delete** for confirmation.
# Add or Remove Users via API
After you have established a global control group using the **Uploading user list** method, you can programmatically manage the user base using the MoEngage APIs. The [Global Control Group API](https://www.moengage.com/docs/api/update-campaigns/update-global-control-group) allows you to append new users to the exclusion list or remove existing users so they can start receiving campaigns again.
> [!NOTE]
>
> The API management is only available if the Global Control Group was created using the **Uploading user list** method. You cannot use the API to add or remove users if the group is configured using **Random Allocation**.
To manage users via API, ensure the following requirements are met:
* **File Format:** The input must be a CSV file. It must contain a single header row with the column name `uid`, followed by the user IDs in the subsequent rows.
* **File Hosting:** The CSV file must be hosted on a publicly accessible URL. Currently, only **Amazon S3** public URLs are supported.
* **File Size:** The CSV file must be under 150 MB.
* **Processing:** API requests are processed sequentially. You must wait for one file processing request to complete before initiating another add or remove request.
**Notifications and Status**\
When you trigger an API call to add or remove users, the system processes the file asynchronously. After processing is complete, an email notification is sent to the email ID provided in the API request (`updated_by` field). This report includes:
* The number of users successfully processed.
* The number of users failed.
* Possible reasons for any failures.
**Impact on Campaigns**\
Updates made via the API take effect immediately upon successful processing.
* **Adding Users:** If a user is added to the control group via API, they stop receiving messages in any future runs of existing or new campaigns.
* **Removing Users:** If a user is removed from the control group, they become eligible to receive messages in future campaign runs.
> [!NOTE]
>
> For technical details, endpoint URLs, and JSON payload examples, please refer to the [Global Control Group API Documentation](https://www.moengage.com/docs/api/update-campaigns/update-global-control-group).
# Disable the Global Control Group
After you have enabled the global control group for a workspace, you can disable it anytime.
1. On the left navigation menu in your MoEngage dashboard, click **Settings** > **Advanced settings** > **Control groups**. The Control groups page appears.
2. In the **Global control group** section, turn the **Status** toggle off to disable the global control group.\
The global control group is disabled for the current workspace. A confirmation message appears in the lower-right corner.

When you disable the global control group, the users who were part of it will start receiving campaigns. This will impact the existing scheduled or upcoming periodic campaigns.
# Locales
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/locales
Add and manage locales in MoEngage to localize campaign messages across languages and regions, driving better engagement and conversions.
You can localize your campaign messages to engage users across different languages, cultures, and regions. Localization helps you tailor your communication to meet specific linguistic and cultural expectations, which drives better engagement. By delivering highly relevant content through locales, brands can significantly improve conversion rates, boost customer loyalty, and ultimately increase customer lifetime value (LTV). For more information, refer to [Localize Campaign Messages](/docs/user-guide/campaigns-and-channels/getting-started/campaign-content/localize-campaign-messages).
## Add a New Locale
Perform the following steps to add a new locale:
> [!NOTE]
>
> There is no limit to the number of locales you can create in your workspace.
1. On the left navigation of your MoEngage dashboard, click **Settings** > **Advanced settings** > **Locales**. The Locales page appears.
2. In the upper-right corner, click **+ Create locale**.

3. On the Add new locale dialog box, enter the following details:
| Field | Description |
| - | - |
| Locale name | Enter a name for the locale. |
| User property | Define the locale's properties. For example, you can add *English* as a locale with the *Last Known Country* as the *US*. |
| + Filter | To define a locale, you can use a single attribute or a combination of attributes (AND or OR). |
| Exclude Users | Select this checkbox and define the filter criteria for users to be excluded from the campaign. |

4. Click **Add**. The locale is created and visible on the Locales page.
## View Locales
1. On the left navigation of your MoEngage dashboard, click **Settings** > **Advanced settings** > **Locales**. On the Locales page, the data is displayed in a tabular format, with columns containing details related to each locale.
| Column | Description |
| - | - |
| Name | Name of the locale |
| Definition | Definition of the locale |
| Created on | Date and time of the locale creation |
| Locale number | A unique number MoEngage assigned to the locale. |
| Campaigns associated | The number of campaigns with which the locale is associated. |

2. You can search locales by their name as shown below:

# Manage Tags
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/manage-tags
Organize campaigns, flows, and content blocks in MoEngage using tags and categories. Create, edit, search, and manage tags from settings.
> [!NOTE]
>
> Tags are separate from [Content Labels](/docs/user-guide/decisioning/campaign-decisioning/ai-campaign-decisioning/content-labels), which AI Campaign Decisioning uses to auto-label message copy. The two are not shared.
Perform the following steps to manage all your tags and categories:
1. Navigate to **Settings > Advanced Settings > Tags**.\\

2. Under **View by**, click **Tag** or **Category** to view all the tags listed individually or grouped by their categories.
* **Tag**: When you select this option, each tag contains information about the number of campaigns, flows, and content blocks in which it is used. You can search for a tag by its name, edit it, or delete it.
* **Category**: When you select this option, you can search for a category by its name, edit it, or delete it.
The following actions are supported on tags:
### Create a Tag
1. Click **+ New Tag** to create a new tag.
2. Enter the tag name and category.

Note: The tags will be moved to Uncategorized if the category is empty.
### Edit/Delete a Tag
You are only allowed to edit the tag name or change tag categories. Click on the action button in the tag row. You can choose to edit/delete tags. 
Note: Default tags cannot be modified.
### Edit/Delete Multiple Tags
1. Select all the tags that you want to update.
2. You can choose to edit/delete selected tags on the top row.

### Edit/Delete a Category
You are only allowed to edit the category's name. Click on the action button in the category row. You can choose to edit/delete a category.
If there are tags present in the category being deleted, you will have two options:
* Delete tags along with the category.

* Move the tags to a different category.

# Mobile Number Standardization
Source: https://moengage.com/docs/user-guide/settings/advanced-settings/mobile-number-standardization
Standardize mobile numbers in MoEngage to E.164 format for reliable SMS and WhatsApp delivery. Configure country codes and number formatting.
# Overview
As a marketer, you can set up a standard format for submitting mobile numbers to MoEngage and select the required details, such as adding + and country code so that MoEngage can submit mobile numbers in E.164 format, i.e., +countrycodemobilenumber to WhatsApp and SMS connectors.
We recommend using one of the following formats to store a mobile number in MoEngage. Examples of a mobile number to be sent to a customer in the US / Canada are mentioned below:
* [E.164 Format](/docs/user-guide/settings/advanced-settings/e164-phone-number-format) i.e. +countrycodemobilenumber, for example, +1999999999
* Numbers without a + (plus ) sign, for example, 19999999999
* Mobile numbers without country code and + sign, for example, 999999999
> [!NOTE]
>
> MoEngage currently adds +91 as the default country code for all mobile numbers when submitting them to SMS and WhatsApp connectors.
# Configure the Mobile Number Format
Perform the following steps to configure the country code:
1. Go to **Settings** > **Advanced settings** > **Mobile number management**. The **Mobile number management** page is displayed.
2. Turn the **Add '+' sign to mobile number if missing** toggle on to add a plus (+) sign to the mobile number if your mobile number does not have a plus (+).
> [!NOTE]
>
> Under **Preview as per above set standard**, you can see the format of the mobile number MoEngage expects from you. It has the country code and mobile number without a plus.
>
> 
3. Turn the **Include a default country code if missing** toggle on to add a country code to the mobile number if your mobile number does not have a country code.
4. When you turn the **Include a default country code if missing** toggle on, The **Select the country code** drop-down is visible. Select your country code from the drop-down list.
> [!NOTE]
>
> Under **Preview as per above set standard**, you can see the format of the mobile number MoEngage expects from you. It has only mobile number without a plus and country code.
>
> 
5. Click **Save**. The Confirm Changes pop-up is displayed.
6. Click **Confirm** to save the changes.
> [!NOTE]
>
> This feature is not supported for Twilio connector.
# Acquisition Tracking
Source: https://moengage.com/docs/user-guide/settings/analytics-and-segmentation/acquisition-tracking
Enable acquisition tracking in MoEngage to measure install attribution, campaign effectiveness, and per-user conversion and revenue metrics.
Acquisition tracking allows you to measure the effectiveness of your user acquisition campaigns by attributing installs and subsequent user actions back to specific campaigns and sources. Enabling this setting helps populate data on the **Acquisition** page in MoEngage Analytics.
Acquisition analytics helps to understand user acquisition campaign performance. You can track valuable user metrics such as conversions per user, revenue per user, and sessions per user. For more information on acquisition analytics, refer [here](/docs/user-guide/analyze/analytics/acquisition).

Perform the following steps to enable acquisition tracking and get the MoEngage attribution key:
1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Analytics** > **Acquisition tracking**.
2. On the Acquisition tracking page, turn the **Acquisition tracking** toggle on.

3. From the **Attribution Platform** list, select the required platform.

4. In the **Attribution Key** box, copy the key. You will need this key to configure MoEngage as a destination or partner on your chosen attribution platform's dashboard.

5. Click **Save**.
6. If you need to generate a new attribution key for security reasons, click the regenerate icon. Remember to update the key on your attribution platform if you regenerate it.

# Query Settings
Source: https://moengage.com/docs/user-guide/settings/analytics-and-segmentation/query-settings
Turn on Analytics user merging, real-time event deduplication, and real-time delete and merge propagation to control how MoEngage counts users and events in analytics and segmentation queries.
Use Query settings to control how MoEngage handles merged users, duplicate events, and deleted users when it runs Analytics and Segmentation queries. Each setting improves count accuracy, and each can make queries take longer, so you choose which ones your workspace needs.
To open Query settings, on the left navigation menu in the MoEngage dashboard, go to **Settings** > **Analytics & Segmentation** > **Query settings**.

The page has three toggles:
| Setting | What it changes | Applies to |
| - | - | - |
| [Analytics user merging](#analytics-user-merging) | Counts an anonymous profile and the registered profile it merges into as one user. | Analytics |
| [Real-time event dedup](#real-time-event-deduplication) | Removes duplicate copies of events that MoEngage saved twice. | Segmentation |
| [Real-time delete and merge propagation](#real-time-delete-and-merge-propagation) | Applies user deletes and identity merges to segments within seconds. | Segmentation |
After you turn on a toggle, the change can take up to 15 minutes to take effect.
## Analytics User Merging
MoEngage merges an anonymous user profile with the registered user profile after the user logs in, so each user has a single user ID across devices and sessions. For more information, refer to [User Merging](/docs/user-guide/data/user-data/anonymous-to-registered-user-merge).
When you turn on **Analytics user merging**, MoEngage Analytics applies the same merging logic, so the anonymous and logged-in activity of a user counts as one user in reports such as [Behavior Analysis](/docs/user-guide/analyze/analytics/behavior/behavior-overview). It can slightly increase query load time.
> [!NOTE]
>
> Segmentation has its own user merging logic. If Analytics user merging is turned off, Analytics treats anonymous and logged-in sessions as separate users, so user counts for the same criteria can differ between Segmentation queries and Analytics reports. Turn on Analytics user merging to align these counts.
## Real-Time Event Deduplication
In rare cases, MoEngage can record the same event more than once. MoEngage prioritizes never losing your data, so occasionally an event is saved twice. When this happens, a user who performed an event once appears to have done it twice. Filters that count occurrences, such as **has executed** an event **exactly** a number of times, can then include or exclude users who don't meet the condition.
When you turn on **Real-time event dedup**, MoEngage finds and removes these duplicate copies. It identifies duplicates using an internal ID that MoEngage assigns to each event, which is separate from `event_id` and your event attributes, so genuine repeat events from your users are never removed. Duplicates are cleaned up during MoEngage's regular data optimization process, and Segmentation counts each event only once.
> [!WARNING]
>
> Segmentation queries take longer to run when this setting is on.
## Real-Time Delete and Merge Propagation
When MoEngage deletes a user or merges an anonymous profile into a registered one, segments reflect the change at the next scheduled rebuild. Until then, a deleted user can stay in a segment, and a merged user can count as two users.
When you turn on **Real-time delete and merge propagation**, deleted users leave every segment immediately, and merged identities count as one user everywhere.
Because queries do additional work to apply these changes, query time can increase. The increase depends on the monthly active users (MAU) in your workspace. Workspaces with a small MAU typically see little to no change, while workspaces with a large MAU can see a noticeable increase in query time. Turn on this setting if having the latest deletes and merges reflected immediately matters more to you than query speed.
# Uninstall Tracking
Source: https://moengage.com/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking
Enable Android uninstall tracking in MoEngage, understand how uninstalls are detected through silent push, and interpret the Device UnInstall event.
Uninstall tracking helps you understand user churn by capturing uninstall events for your Android app. Enabling this setting populates data on the **Uninstalls** page in MoEngage Analytics, which shows when users uninstall your app. For more information on uninstall analytics, refer to [Uninstall](/docs/user-guide/analyze/analytics/uninstall).

## Prerequisites
Before you enable Android uninstall tracking, ensure that your app handles Android silent pushes. If you [handle push display in your application](/docs/developer-guide/android-sdk/push/advanced/push-display-handled-by-application), confirm that it handles silent pushes as well.
If you see blank notifications with no text or logo in your app, your custom push handling is likely not handling silent pushes. Turn uninstall tracking off until your app handles them correctly.
## Enable Android Uninstall Tracking
Perform the following steps to enable uninstall tracking:
1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Analytics** > **Uninstall tracking**.
2. On the Uninstall tracking page, turn the **Android Uninstall Tracking** toggle on.

3. Click **Test Android silent push** to confirm that your app handles silent pushes without displaying them to the user.
## How MoEngage Detects Uninstalls
MoEngage sends silent push notifications daily to every device associated with your users and captures the responses. A device is marked as uninstalled when Firebase Cloud Messaging (FCM) returns an explicit uninstall error (`Not Registered`).
For other error codes that do not explicitly indicate that the device is unregistered, MoEngage does not mark the device as uninstalled and continues to send silent pushes to it.
If uninstall tracking is turned off on the dashboard, MoEngage does not proactively check for uninstalls by sending silent pushes. Failed delivery attempts of push campaign messages still show up as uninstalls.
> [!NOTE]
>
> Uninstall tracking for iOS was deprecated on August 10, 2023, following significant adoption of iOS 15 and iOS 16, which do not support tracking failed delivery attempts through silent push. Failed delivery attempts of regular push campaign messages still show up as uninstalls for iOS devices.
## When an Uninstall Is Detected
The date and time recorded on the **Device UnInstall** event in a user profile is the time MoEngage **detected** that the app was uninstalled, not the time the user uninstalled it. MoEngage cannot determine the actual time of the uninstall.
# Bot Detection for Email Opens and Clicks
Source: https://moengage.com/docs/user-guide/settings/channels/bot-detection-settings/bot-detection-for-email-opens-and-clicks
Identify and filter bot-generated opens and clicks on your Email campaigns so your engagement metrics accurately reflect genuine user behavior.
## Overview
Not every open or click recorded by your Email campaigns comes from an actual human recipient. Sources such as [Apple Mail Privacy Protection (MPP)](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/mail-privacy-protection-mpp-and-email-analytics), corporate security scanners, and automated link-checking proxies can trigger opens and clicks automatically. Left unfiltered, this activity inflates your metrics, skews Key Performance Indicators (KPIs) like Open rates, Click rates, and Click-to-Open Rate (CTOR) that can incorrectly trigger engagement-based automations (for example, retargeting based on email opens and clicks).
Bot Detection allows you to define specific rules to identify non-human activity, including blocklists for known bot user agents and IP addresses, and heuristic rules that flag opens and clicks based on timing and click patterns. You can configure rules separately for **Bot opens** and **Bot clicks**, and choose how MoEngage should display these metrics in your campaign analytics and reports.
> [!NOTE]
>
> * Bot detection feature is currently available only for Email channel.
> * MoEngage has been continuously monitoring opens and clicks across the platform in the background, identifying new bot IPs and bot user agents and keeping the default rules up to date. Additionally, this setting gives you the ability to add your own custom rules on top of these defaults.
> * Bot detection feature of MoEngage is built to catch the vast majority of bot activity and is continuously refined for greater accuracy. As with any detection system, some bot activity may go undetected, and some genuine activity may be flagged as a bot.
## Use Cases
* **Accurate campaign performance reporting**: Marketing and analytics teams can rely on Open Rate, Click Rate, and CTOR that reflect genuine recipient behavior, instead of being inflated by Apple MPP pre-fetching, image proxies, or automated security scanners.
* **Reliable engagement-based segmentation and journeys**: Since bot opens and clicks no longer falsely qualify a contact as "engaged," users aren't incorrectly moved into engaged segments, win-back flows, or automation branches meant only for real recipient actions.
* **Flexibility to handle bot-flagged unsubscribes your way**: Bot detection works on a best-effort basis, so a genuine unsubscribe click can occasionally be misclassified as a bot click. This setting puts that decision in your hands: choose to always honor the unsubscribe request even when it's flagged as a bot, so you never risk retaining someone who wanted out, or choose to ignore bot-flagged unsubscribe clicks so genuine subscribers aren't suppressed by mistake.
* **Cleaner data for downstream reporting**: Because bot-adjusted metrics can be viewed separately from totals, teams exporting engagement data to BI tools, dashboards, or CRMs can work with human-only numbers for more accurate customer engagement scoring.
## Enable Bot Detection
To start filtering bot activity, perform the following steps:

1. Log in to your MoEngage dashboard.
2. Navigate to **Settings** > **Channels** > **Bot Detection Settings**.
3. On the **Bot Detection Settings** page, under the **Email** tab, turn on the **Detect bots for email opens and clicks** toggle so it displays as **Enabled**.
After enabling, there will be two sub-tabs: **Bot opens** and **Bot clicks**. You can configure specific detection rules within each.
## Configure Bot Opens
Navigate to the **Bot opens** tab to define how MoEngage identifies and handles bot-driven email opens.

### Detection Rules
* **Detect opens from Apple Mail Privacy Protection**: For recipients who have enabled [Apple Mail Privacy Protection (MPP)](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/mail-privacy-protection-mpp-and-email-analytics), Apple preloads remote content, including tracking pixels, through its own relay servers before the recipient actually opens the email. This preload can happen immediately or after a delay, and it registers as an "open" even though no human has read the email, producing a false engagement signal. Check this box to automatically identify these proxy-generated opens.

* **Classify as bot activity if**: Use these heuristic rules to flag opens based on when they occur relative to email delivery. Select the checkbox next to a rule to enable it. For a rule with a time threshold, the value and unit fields stay disabled until you select the rule. For details on how MoEngage evaluates these rules, refer to [How Heuristic Rules Work](#how-heuristic-rules-work).

* **An open is detected within \[value] \[unit] of the email being delivered.**: Classifies an open as bot activity if it occurs within the specified time after the email is delivered. Security scanners and image proxies typically fetch the tracking pixel within seconds of delivery, well before a human recipient could read the email.
* **Value**: Enter the threshold duration.
* **Unit**: Select **seconds** or **minutes**.
* The maximum threshold is 10 minutes (600 seconds). If you enter a higher value, MoEngage displays the error **Opens can be classified as bot opens for up to 10 minutes after the email is delivered.** You can't save your settings until you correct the value.
* For example, if you set the threshold to 10 minutes and an email is delivered at 5:48 PM, an open recorded at 5:52 PM is classified as a bot open. An open recorded at 6:00 PM is treated as a genuine open.
* **An open is detected before the email being delivered.**: Classifies an open as bot activity if it occurs before the email is delivered. A recipient can't open an email that hasn't reached their inbox, so an open recorded ahead of delivery indicates automated activity. If MoEngage receives the open event before the delivery event, it compares the event timestamps shared by your email service provider (ESP) to determine which actually occurred first.
* **Bot user-agent blocklist**: Expand this section to manage the list of user-agent signatures used to detect bots.

* **MoEngage Default**: Rules tagged with **"MoEngage default"** are maintained automatically by MoEngage to cover known bots.These rules cannot be deleted. However, if you find that traffic from a specific default user agent or IP is actually genuine for your brand, you can disable that individual rule at any time using its **Enabled** checkbox.
* **Search**: Use the **Search bot user-agent by name** field to find specific rules.
* **Add bot user-agent**: Click the **+ Add bot user-agent** button to create custom rules. You can add up to 200 entries. This creates a new input row where you must define the following fields:

* **Detection logic**:
* Select **Exact match** if you want MoEngage to block an open only when the incoming user-agent string matches your entry perfectly, character for character (e.g., 123456).
* Select **Partial match** if you want to block an open when the incoming user-agent string simply contains your entry as a substring (e.g., entering random will block any user-agent string that includes the word "random").
> [!WARNING]
>
> Use **Partial match** carefully, an overly broad value can unintentionally match legitimate traffic and misclassify real users as bots. For example, entering **Mozilla/5.0** as a partial match would match almost every real browser's user-agent string, since most legitimate browsers include this substring causing the majority of your genuine opens to be categorized as bots.
* Both **Exact match** and **Partial match** are case-insensitive, so entries like *Random* and *random* are treated the same.
* **Bot user-agent name**: Type the exact or partial string you want to detect. Note: You must enter a string here before saving, otherwise MoEngage displays a **Please enter a user agent string before saving** error.
* **Enabled**: This checkbox determines the active status of the rule. Leave it checked to activate the rule immediately upon saving. Uncheck it if you want to save the rule to your list but keep it inactive for now.
* **Actions**: While adding a new rule, click the checkmark icon to save and apply the new entry, or click the cross (X) icon to cancel and discard the row. After a rule is saved, these icons change to a pencil for editing and a trash can for deleting.
* **IP Address blocklist**: Expand this section to block opens originating from specific IP addresses or ranges (e.g., corporate proxies or data centers).

* Click **+ Add IP address** to define the **Type** (**Single IP** or **IP Range**), the **Standard** (**IPv4** or **IPv6**), and the exact address/range.
* While adding a new IP address, click the checkmark icon to save and apply the new entry, or click the cross (X) icon to cancel and discard the row. After an IP address is saved, these icons change to a pencil for editing and a trash can for deleting.

### Post Detection Actions
Under the **Post detection actions** section on the **Bot opens** tab, choose your preferred **Campaign metrics display settings**:

* **Show both total and adjusted opens**: Your campaign reports will display the raw, unfiltered open counts alongside the adjusted (human-only) open counts.
* **Show bot adjusted opens only**: Your campaign reports will entirely exclude detected bot opens, showing only the adjusted metrics.
For more information, refer to the Engagement Metrics section in [Campaign Performance Stats](/docs/user-guide/campaigns-and-channels/email/analyze/email-analytics-and-info#campaign-performance-stats).
> [!NOTE]
>
> Important Note: To prevent discrepancies, this display adjustment applies to both Opens and Clicks. Any changes made to this setting will reflect uniformly across all metric adjustment dashboards.
## Configure Bot Clicks
Navigate to the **Bot clicks** tab to define how MoEngage identifies and handles automated link-checking bots. Because bots often crawl every link in an email to check for malicious content, they can falsely inflate your Click-Through Rates (CTR) and accidentally trigger unsubscribe links.

### Detection Rules
This tab utilizes the same blocklist structures as the **Bot opens** tab, but applies them specifically to link clicks. If you are configuring this for the first time, you will see empty state illustrations prompting you to begin.
* **Classify as bot activity if**: Use these heuristic rules to flag clicks based on their timing and pattern. Link-scanning bots often follow every link in an email within seconds of delivery, often without loading the email itself. Select the checkbox next to a rule to enable it. For a rule with a time threshold, the value and unit fields stay disabled until you select the rule. For details on how MoEngage evaluates these rules, refer to [How Heuristic Rules Work](#how-heuristic-rules-work).

* **The first click is detected within \[value] \[unit] of the email being delivered.**: Classifies a click as bot activity if the first click on the email occurs within the specified time after delivery.
* **Value**: Enter the threshold duration.
* **Unit**: Select **seconds** or **minutes**.
* The maximum threshold is 10 minutes (600 seconds). If you enter a higher value, MoEngage displays the error **Clicks can be classified as bot clicks for up to 10 minutes after the email is opened.** You can't save your settings until you correct the value.
* For example, if you set the threshold to 3 seconds, a click recorded 2 seconds after delivery is classified as a bot click.
* **Two or more links are clicked within \[value] \[unit] of each other.**: Classifies clicks as bot activity if two or more links in the same email are clicked within the specified time of each other. Rapid clicks across multiple links are typical of automated link checkers rather than human readers.
* **Value**: Enter the maximum time between clicks.
* **Unit**: Select **seconds** or **minutes**.
* The maximum threshold is 10 minutes (600 seconds). If you enter a higher value, MoEngage displays the error **Clicks can be classified as bot clicks for up to 10 minutes after the email is opened.** You can't save your settings until you correct the value.
* For example, if you set the threshold to 3 seconds and one link is clicked and then a second link 1 second later, both clicks are classified as bot clicks.
* **All the links in an email are clicked.**: Classifies clicks as bot activity if every link in the email is clicked. Security bots commonly scan every URL in an email for malicious content, while human recipients rarely click every link. This rule has no configurable threshold.
* **A click is detected without the email being opened.**: Classifies a click as bot activity if no open has been recorded for the email before the click. Automated link checkers follow links without loading the email's tracking pixel, so their clicks arrive without a preceding open. If an open is recorded after the click, the click's classification doesn't change.
> [!WARNING]
>
> Do not enable this rule if your database includes contacts subject to CNIL (France/Italy) or similar open-tracking consent regulations, or if a significant portion of your audience uses email clients that block tracking pixels by default. For these contacts, opens aren't tracked, so their genuine clicks are classified as bot clicks.
* **A click is detected before the email being delivered.**: Classifies a click as bot activity if it occurs before the email is delivered. If MoEngage receives the click event before the delivery event, it compares the event timestamps shared by your ESP to determine which actually occurred first.
* **Bot user-agent blocklist**: Click **+ Add bot user-agent** to input user-agent signatures for known link-crawling bots. You will use the exact same inline inputs (**Detection logic**, **Bot user-agent name**, **Enabled** checkbox, and checkmark/cross **Actions**) as described in the [Bot Opens](#configure-bot-opens) section.

* **IP Address blocklist**: Click **+ Add IP address** to block click activity originating from specific servers or data center IP ranges.

### Post Detection Actions

#### Campaign Metrics Display Settings
Choose how your campaign dashboards present click data:
* **Show both total and adjusted clicks**: Displays raw counts alongside adjusted (human-only) click counts.
* **Show bot adjusted clicks only**: Completely excludes detected bot clicks from your reports. (Note: Updating this will also update the setting on the **Bot opens** tab).
For more information, refer to the Engagement Metrics section in [Campaign Performance Stats](/docs/user-guide/campaigns-and-channels/email/analyze/email-analytics-and-info#campaign-performance-stats).
#### On Detecting Unsubscribe Bot Clicks
Because security bots test every link, they will inevitably click your unsubscribe link. This setting protects genuine users from accidental opt-outs.
* **Unsubscribe the user**: MoEngage will process the opt-out request normally, even if the system suspects it was triggered by a bot.
* **Ignore unsubscribe bot clicks**: MoEngage will block the opt-out request if a bot click is detected, ensuring the genuine user remains subscribed and reachable.
> [!WARNING]
>
> Choosing to ignore unsubscribe bot clicks carries a compliance risk. If a detected "bot click" was actually a genuine user trying to opt out, that user's unsubscribe request won't go through, and they'll continue receiving emails they intended to stop. Depending on your region and audience, this can have compliance implications under regulations such as GDPR and CAN-SPAM, both of which require honoring opt-out requests. While our bot detection is robust, it is impossible to identify 100% of all bot activities, so some genuine unsubscribe clicks may still be misclassified as bot activity. Review your compliance obligations before selecting this option, and consider periodically auditing suppressed unsubscribe attempts to detect any false positives.
## How Heuristic Rules Work
The heuristic rules under **Classify as bot activity if** on the **Bot opens** and **Bot clicks** tabs work as follows:
* **Seven rules in total**: The **Bot opens** tab has two heuristic rules and the **Bot clicks** tab has five. Three of these rules let you set a time threshold: one on **Bot opens** and two on **Bot clicks**.
* **Threshold limit**: A threshold can't exceed 10 minutes (600 seconds). If you enter a higher value, MoEngage displays a validation error below the rule and you can't save your settings until you correct the value:
* On the **Bot opens** tab: **Opens can be classified as bot opens for up to 10 minutes after the email is delivered.**
* On the **Bot clicks** tab: **Clicks can be classified as bot clicks for up to 10 minutes after the email is opened.**
* **Multiple matching rules**: Each enabled rule is evaluated independently, so a single open or click can match more than one rule. MoEngage records every matching rule as a reason on the event. For example, if a bot clicks all three links in an email within seconds of delivery and no open was recorded, the click is flagged for **The first click is detected within**, **All the links in an email are clicked.**, and **A click is detected without the email being opened.**
* **Classification is final**: MoEngage classifies an open or click when the event is processed. Events that arrive later don't change an earlier classification. For example, an open recorded after a click doesn't reclassify that click.
* **Only enabled rules affect your metrics**: Opens and clicks are classified as bot activity in your campaign metrics only for the rules you enable.
* **Delivery-based rules**: Four rules depend on the email's delivery event: **An open is detected within \[value] \[unit] of the email being delivered.**, **An open is detected before the email being delivered.**, **The first click is detected within \[value] \[unit] of the email being delivered.**, and **A click is detected before the email being delivered.** How MoEngage evaluates these rules depends on whether it has the delivery event for the email:
* **Delivery event is available**: MoEngage compares the event timestamps shared by your ESP. If the open or click occurred before the delivery, it's classified as bot activity under the corresponding "before the email being delivered" rule. The order in which MoEngage receives the events doesn't matter; the ESP timestamps decide.
* **Delivery event isn't available**: If the delivery event was never received, or was received too late to be evaluated, MoEngage skips the delivery-based rules for that open or click. MoEngage never classifies an open or click as bot activity just because its delivery event is missing. Other enabled rules, such as the blocklists, Apple MPP detection, and heuristic rules that don't depend on delivery, still apply.
* **ESPs that don't send delivery events**: Some ESPs, such as Mandrill and SparkPost, don't send delivery events to MoEngage, so delivery-based rules are never applied to their emails. For more information, refer to the [FAQs](#faqs).
> [!NOTE]
>
> For the delivery-based rules, MoEngage looks back up to 24 hours from the time of an open or click to find the email's delivery event.
### Choose a Threshold
Timing-based rules can't distinguish a fast bot from a fast human. Any genuine recipient who opens or clicks within your threshold is also classified as a bot, even when the action is manual. Before you set a threshold, review how quickly your recipients typically engage after delivery. Start with a short threshold, monitor your adjusted metrics, and increase it gradually if bot activity is still getting through.
## Save or Disable Bot Detection Settings
**Saving**: Click the **Save** button at the bottom right of the screen to apply your configurations. Changes to the **Bot opens** and **Bot clicks** tabs are saved independently. If you attempt to navigate away with unsaved changes, MoEngage will prompt you to confirm before discarding them.
**Disabling**: To turn the feature off entirely, switch off the **Detect bots for email opens and clicks** master toggle. MoEngage will display a confirmation dialog summarizing the impact on your metrics before disabling the rules.
## FAQs
> [accordion] Does bot detection apply retroactively to past campaigns?
>
> No. Bot detection rules apply only to opens and clicks moving forward from the moment they are saved. Changing a rule or a display setting does not reprocess historical campaign data recorded prior to the change.
> [accordion] Can I use different detection rules for opens and clicks?
>
> Yes. The **Bot opens** and **Bot clicks** tabs feature independent blocklists, allowing you to configure different User-Agent or IP Address rules based on the specific type of bot activity you are observing for each interaction type.
> [accordion] Can I choose different display settings for opens and clicks?
>
> No. To maintain reporting consistency, the "Campaign metrics display settings" apply uniformly. If you choose to "Show bot adjusted opens only", your reports will also automatically show bot adjusted clicks only.
> [accordion] Will this affect channels other than Email?
>
> No. Bot detection currently applies strictly to the Email channel.
> [accordion] Why are genuine opens or clicks being flagged as bot activity?
>
> Timing-based rules flag every open or click that falls within the threshold, including manual actions by real recipients. The **A click is detected without the email being opened.** rule can also flag genuine clicks from contacts whose opens aren't tracked, such as contacts subject to CNIL or similar open-tracking consent regulations, or recipients whose email clients block tracking pixels by default. Review your thresholds and the rules you have enabled. For guidance, refer to [Choose a Threshold](#choose-a-threshold).
> [accordion] Can one open or click be flagged by more than one heuristic rule?
>
> Yes. Each enabled rule is evaluated independently, and every matching rule is recorded as a reason on the event.
> [accordion] What is the maximum threshold I can set for a heuristic rule?
>
> 10 minutes (600 seconds). If you enter a higher value, MoEngage displays a validation error and doesn't let you save your settings.
> [accordion] What will get classified as machine opens and clicks?
>
> Opens and clicks are classified as machine activity if they match any rule you enable on the **Bot opens** or **Bot clicks** tab. This includes Apple Mail Privacy Protection opens, opens and clicks from blocklisted user agents or IP addresses, and opens and clicks that match a heuristic rule under **Classify as bot activity if**. The default user-agent list is compiled and maintained by MoEngage based on ongoing platform monitoring.
> [accordion] What if I want neither suppression nor a split view?
>
> If you believe your email opens and clicks aren't affected by bot activity, turn off the **Detect bots for email opens and clicks** toggle at the top of the **Bot Detection Settings** page (**Settings** > **Channels** > **Bot Detection Settings** > **Email** tab). When the toggle is off, MoEngage doesn't evaluate email opens and clicks for bot activity, and your campaign reports show all open and click metrics without any adjustment. For more information, refer to [Save or Disable Bot Detection Settings](#save-or-disable-bot-detection-settings).
> [accordion] Is this solution future-proof?
>
> Over the past few quarters, MoEngage has done extensive research and troubleshooting on email opens and clicks and has a good understanding of the various moving parts involved. However, detecting and labeling bot opens and clicks is a shifting landscape that requires continuous identification and resolution of issues. MoEngage will continue to do the same in the future.
> [accordion] Does this cover all machine activity?
>
> No, machine activity impacts clicks, unsubscribes, and spam complaints in addition to email opens. Current solution of MoEngage classifies email opens/clicks only.
> [accordion] For which campaigns will this apply?
>
> The split of total vs. adjusted opens will be available for all campaigns created after 16 December 2024. Campaigns created before that will not have this data.
> [accordion] What will this do to my conversions?
>
> Given its impact on business reporting and marketers' KPIs, the conversion logic will remain as it is and will factor in all email opens/clicks as before. MoEngage is monitoring the adoption and response from our customers and will then decide whether the conversion logic should also be updated. Excluding bot-classified events from conversion attribution and from features such as [Best Time to Send](/docs/user-guide/ai-and-intelligence/timing/best-time-to-send), [Most Preferred Channel](/docs/user-guide/ai-and-intelligence/most-preferred-channel/most-preferred-channel), and [Next Best Action](/docs/user-guide/flows-cross-channel-messaging/create/intelligence-in-flows/next-best-action-in-flows) is planned for a future release.
> [accordion] What will happen to analytics and reports / key metrics dashboards?
>
> Reports will show options to include both total and adjusted metrics. Key metrics will show all opens or adjusted opens based on the user's selection.
> [accordion] Is this supported on Inform?
>
> Currently, No. This will be extended to Inform Analytics in the future.
> [accordion] Is this supported for Flows?
>
> Yes, it is.
> [accordion] Do delivery-based bot detection rules apply to emails sent through ESPs that don't send delivery events?
>
> No. Some ESPs, such as Mandrill and SparkPost, don't send a delivery event to MoEngage. For emails sent through these ESPs, MoEngage skips the following delivery-based rules:
>
> * **An open is detected within \[value] \[unit] of the email being delivered.**
> * **An open is detected before the email being delivered.**
> * **The first click is detected within \[value] \[unit] of the email being delivered.**
> * **A click is detected before the email being delivered.**
>
> Opens and clicks on these emails aren't classified as bot activity only because the delivery event is missing. All other enabled rules still apply.
# Campaign Audience Limit
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/campaign-audience-limit
Cap the number of users who receive a campaign in MoEngage based on engagement metrics like sent, delivered, impressions, or conversions.
# Overview
In marketing, controlling campaign reach and expenditure is crucial for effective resource allocation and achieving specific business goals. The **Campaign audience limit** feature in MoEngage empowers you with this control by allowing you to cap the number of users who receive a campaign based on key engagement metrics such as Sent, Impressions, Open, Delivered, and Conversions. This functionality directly addresses the need to manage promotional offers, limit redemptions, and gate access to exclusive content for a defined audience size, ensuring optimal budget utilization.
Furthermore, for recurring campaigns targeting large user segments, the Campaign audience limit enables you to manage the maximum number of users engaged per instance (particularly with the daily and instance-level options), contributing to broader reach over time, even though the system randomly selects users for each instance and some overlap may occur.
# Use Case
Are you looking to stay within your campaign budget cap? The Campaign audience limit feature is just what you need. By setting a specific threshold for the number of users who will receive your campaign, you can ensure that your budget remains intact and avoid exceeding your spending limits. Once the designated number of users has been reached, the campaign will automatically pause, preventing budget breaches.
# Configure Campaign Audience Limit
The **Campaign audience limit** option is available in the **Target Users** step while creating a campaign. You can turn on the toggle to trigger the user limit based on the configuration. 
This feature allows you to set the following campaign audience limits based on the delivery types:
## Total
The campaign will be paused when the events (Sent, Impressions, Open, Delivered, Conversions) have reached the desired limit.
## Daily
The campaign will be paused when the day's events (Sent, Impressions, Open, Delivered, Conversions) reach the desired limit for that day.
## Instance
The campaign will be paused when the events (Sent, Impressions, Open, Delivered, Conversions) from the specific instance have reached the desired limit.
The following table displays the campaign audience limits supported for channels based on campaign delivery types:
| Channel | Delivery Type | Total | Daily | Instance Level |
| - | - | - | - | - |
|
Push
Email
SMS
WhatsApp
Cards
Connectors
RCS
| One time | Yes | No | No |
|
Push
Email
SMS
WhatsApp
Cards
Connectors
RCS
| Periodic | Yes | No | Yes |
|
Push
Email
SMS
WhatsApp
Cards
Connectors
RCS
| Event Triggered | Yes | Yes | No |
|
Push
Email
SMS
RCS
| Business Event Triggered | Yes | Yes | Yes |
|
In-app
On-site messaging
| One Time (Continuously Active in duration) | Yes | Yes | No |
|
| Business Event Triggered Flows | Yes | Yes | No |
|
Push
SMS
WhatsApp
RCS
Connected Apps
| On Flow Exit Flows | Yes | Yes | No |
|
Push
SMS
WhatsApp
RCS
Connected Apps
| One-time / Periodic Flows | Yes | No | No |
# How Does the Campaign Audience Limit Work?
You can configure the campaign audience limit to total, daily, or instance level. The metrics used to calculate and enforce these limits are:
* Sent
* Impressions
* Open
* Delivered
* Conversions
> [!NOTE]
>
> For Card campaigns, the limit is enforced when a user's device fetches the card, which is when the card counts as **Delivered**, not when the card is queued for sending. The **Sent** count can therefore exceed your limit, while the number of users who receive the card stays within it. For more information, refer to [Create a Card Campaign](/docs/user-guide/campaigns-and-channels/cards/create/create-a-card-campaign#campaign-audience-limit).
> [!NOTE]
>
> When setting a campaign audience limit based on Impressions or Conversions, note that the campaign might not pause precisely at the specified limit. You may observe a few additional impressions or conversions beyond the set value.
### Total
You can set the total campaign audience limit to pause the campaign when the impressions, sent, conversions have reached a desired limit. The following scenarios will help you better understand the total campaign audience limit.
**Scenario 1**
An event-triggered Push campaign must be paused when the total sent count reaches 2000 users.
**User action**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Select **sent** and **total** from the lists.
3. Enter the limit, which is 2000, in the space provided. 
**Observed campaign behavior**
| Total Sent | Behavior |
| - | - |
| 1500 | Campaign proceeds |
| 2000 (limit reached) | Campaign is paused |
**Scenario 2**
A one-time Email campaign limit is 4500 users. When it exceeds, the status will be changed to **SENT.**
**User action**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Enter the limit, which is 4500, in the space provided. 
**Observed campaign behavior**
| Total Sent | Behavior |
| - | - |
| 1500 | Campaign proceeds |
| 4500 (limit reached) | Status changes to SENT |
### Daily
You can set the daily campaign audience limit to pause the campaign when the impressions, sent, conversions for the day have reached the desired limit. The following scenarios will help you better understand the daily campaign audience limit.
> [!NOTE]
>
> The campaign will automatically pause when the limit is reached and will resume precisely at midnight (12:00 AM) in your campaign timezone.
**Scenario 1**
An event-triggered SMS campaign must be paused when the daily conversion count reaches 3000 users.
**User action**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Select **conversions** and **daily** from the lists.
3. Enter the limit, which is 3000, in the space provided. 
**Observed campaign behavior**
| Total Conversions | Behavior |
| - | - |
| 1500 | Campaign proceeds |
| 3000 (limit reached) | Campaign is paused |
**Scenario 2**
A business event-triggered Email campaign must be paused when the daily sent count reaches 2500 users.
**User action**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Select **daily** from the list.
3. Enter the limit, which is 2500, in the space provided. 
**Observed campaign behavior**
| Total Sent | Behavior |
| - | - |
| 1500 | Campaign proceeds |
| 2500 (limit reached) | Campaign is paused |
### Instance Level
You can set the instance-level campaign audience limit to pause the campaign when the impressions, sent, conversions for the specific instance have reached the desired limit. The following scenarios will help you better understand the instance-level campaign audience limit.
> [!NOTE]
>
> At the instance level, the parent campaign will remain active, while the child campaign will be marked as SENT because it has reached its limit.
**Scenario 1**
A business event-triggered Push campaign must be paused when the sent count for an instance reaches 1000 users.
**User action:**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Select **instance** from the list.
3. Enter the limit, which is 1000, in the space provided. 
**Observed campaign behavior**
| Total Sent | Behavior |
| - | - |
| 500 | Campaign proceeds |
| 1000 (limit reached) | Campaign is paused |
**Scenario 2**
A periodic Push campaign must be paused when the sent count for an instance reaches 4000 users.
**User action:**
1. In the **Target users** step during campaign creation, turn on the **Campaign audience limit** toggle.
2. Select **instance** from the list.
3. Enter the limit, which is 4000, in the space provided. 
**Observed campaign behavior**
| Total Sent | Behavior |
| - | - |
| 1500 | Campaign proceeds |
| 4000 (limit reached) | Campaign is paused |
If you attempt to resume a campaign that has been automatically paused after reaching its campaign audience limit, the following error message will appear.

# Editing Campaign Audience Limit
You can edit the campaign audience limit of a campaign to a higher or lower number whenever necessary. The campaign resumes based on the updated limit. The following table outlines the campaign behavior in response to increasing or decreasing campaign audience limits at different levels.
| Level | Scenario | Behavior When Increasing Limit | Behavior When Decreasing Limit |
| - | - | - | - |
| Total Level | Limit is breached | The campaign resumes to reach the new limit. | You cannot decrease the limit if it has already been reached. |
| Limit is not breached | The campaign continues until the new limit is reached. | The campaign pauses when the new limit is reached. | |
| Daily Level | Limit is breached | The campaign resumes to reach the new limit. | The campaign pauses, and the new limit applies the next day. |
| Limit is not breached | The campaign continues until the new limit is reached. | The campaign pauses based on the new limit. | |
| Instance Level | NA | The updated limit applies from the next instance. | The updated limit applies from the next instance. |
### Example Scenarios
**Scenario 1: When the Campaign audience limit is increased**
A campaign with a total limit of 2000 users is performing well. The better performance incurred a higher budget for the campaign, which demands a 3000-user count as the total limit.
**User action**
Edit the total limit of 2000 to 3000.
**Observed behavior**
The campaign resumes to reach an additional 1000 users.
**Scenario 2: When the Campaign audience limit is increased**
Due to a budget shortage, the campaign's total limit needs to be reduced from 4000 users to 2000 users.
**User action**
Edit the total limit from 4000 to 2000.
**Observed campaign behavior**
The campaign pauses when the total limit reaches 2000 users.
> [!NOTE]
>
> You can also disable the campaign audience limit if required. After the campaign audience limit is disabled, the campaign will be sent to the entire segment from the following instance.
# Campaign Analytics and Info
On the Campaign Analytics page, you can:
* View the campaign performance stats. To do so, navigate to **Engage** > **Campaigns**. In the **All Campaigns** page, search for your campaign. Click the campaign name to access the **Campaign analytics and info** page. In the **Campaign analytics and info** page, navigate to **Analytics > Campaign performance stats**.
* Identify if the campaign has the campaign audience limit enabled. If enabled, the info icon on the **Analytics** tab will have the following message: This campaign has campaign audience limit enabled. This will limit the number of users who will receive the campaign. 
> [!NOTE]
>
> The Failed count does not include users removed due to the campaign audience limit and the drop is expected. You can view the count of removed users in the error breakdown table.
>
> 
On the Campaign Info page:
* You can view the campaign audience limit defined during campaign creation. To do so, navigate to **Engage** > **Campaigns**. In the **All Campaigns** page, search for your campaign. Click the campaign name to access the **Campaign analytics and info** page. In the **Campaign analytics and info** page, navigate to **Info** > **Audience** > **Target**. 
> [!NOTE]
>
> In the **Campaign Info** page of WhatsApp campaigns, you can view the campaign audience limit defined during campaign creation in the **Segmentation** card.
>
> 
* If you edit the campaign audience limit, a new version will be created. The old or new limit will be displayed based on your current version.
> [!NOTE]
>
> The campaign audience limit will be applied at the overall campaign level, not individually to each version.
# Do Not Disturb
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/do-not-disturb
Configure Do Not Disturb hours in MoEngage to prevent trigger campaign notifications from reaching users during idle or off-peak hours.
Do Not Disturb (DND) allows marketers to configure idle hours, at which time trigger notifications should not be sent to users.
*Trigger campaigns* are sent to users when they do a defined action within a defined time, for example, "Added a product to cart" but "Not Purchased" in 2 hours. Since the messages are sent based on user activity (with a delay set by the marketer), it is possible that some of these notifications (Push/Email/SMS, MMS & RCS) are triggered at odd hours. For example, if the user has added a product at 10 PM, the respective notification/message will be sent at midnight.
DND can be configured on the following channels and their respective delivery types. Channels other than those mentioned here do not support DND.
| Channel Name | Campaign type with DND support |
| - | - |
| Push | All **Note**: For *One-Time*, *Periodic,* and *Business event-triggered* campaigns, the DND can be configured only when the [Message Queuing](/docs/user-guide/settings/channels/delivery-controls/message-queuing) feature is enabled. |
| Email | Event Triggered |
| SMS, MMS & RCS | Event Triggered |
| WhatsApp | Event Triggered |
| Connectors | Event Triggered |
## Configure DND for Channels
To configure DND for the above-mentioned channels:
1. Navigate to **Settings** > **Channels** > **Delivery Controls** > **Do not disturb** tab.
2. Turn on the toggle for the channels for which you want to set up DND.
3. Once you enable DND settings for a channel, the following fields are enabled:
* **Do not disturb timing (User’s time zone)** - You can specify the time interval in the user's time zone - the starting time for the DND interval and the ending time for the same in the *From* and *To* fields. 
* **Action for messages generated during DND** - After setting up the DND time interval, you can choose how you want to handle the messages generated during the DND period. The following actions are available: 
| Action | Description |
| - | - |
| **Discard these messages and do not send them later** | This option will discard the messages generated during the DND window. |
| **Save and send all the queued messages** | Select this option if you want to send all the notifications/emails/messages to the user after the DND period is over. If the user performs the trigger action for a campaign multiple times and satisfies all other configured conditions (e.g., target audience), they would be receiving the notification/email/message from a single campaign those many times. |
| **Save and send message from only one campaign** | Select this option if you want to send only one notification/email/message from each campaign. In this case, even if the user performs the trigger action for a particular campaign multiple times, they would receive only one notification/email/message from one campaign. This option would ensure that the user will not receive more than 'x' notifications (where 'x' campaigns are active on a day for the given channel). |
| **Save and send only one message across \ campaigns** | Select this option if you want to send at most one notification/message/email to the user. You might consider this option if you have campaigns running in other channels running as well, and you want to limit the total number of notifications/messages/emails that the user should receive. |
* **Order in which queued messages should be sent** - This option allows you to control the order in which the notifications will be delivered to the users. It's applicable to all actions except the Discard message option. The options available here are Send the most recent message first (Last in first out) and Send least recent message first (First in first out).
* Consider the example that a user becomes eligible for the following push notifications (PN):
* PN1 at 11 PM
* PN2 at 12.30 AM
* PN3 at 5 AM
* PN4 at 6.30 AM
* **Send the most recent message first (Last in first out)**: If you select this option, the user will first receive PN4, followed by PN3, then PN2, and then PN1 after the DND period is over. If the action selected is *Send only one message across Push Campaigns*, then the user will only receive PN4 (the most recent notification).
* **Send least recent message first (First in first out)**: If you select this option, the user will first receive PN1, followed by PN2, then PN3, and then PN4 after the DND period is over. If the action selected *Send only one message across Push Campaigns*, then the user will only receive PN1 (the least recent notification).
* **Gap between messages** - This option allows you to set the delay or gap between multiple notifications/messages/emails. It is only applicable when you select either *Send only one message from each campaign".*
* **Send all messages at once:** Select this option if you want to deliver all the notifications/messages/emails in one go without any gap between two notifications.
* **Send messages at a gap of x mins:** Using this option, you can set the time gap between the delivery of two notifications/messages/emails. For example, if you set the gap to five minutes, the second notification/message/email will be delivered five mins after the first one.
## DND for Push/Email/SMS, MMS & RCS/WhatsApp sent using Flows
These DND Settings are applicable to the campaigns created inside a MoEngage Flow as well. Read more about how it works [here](/docs/user-guide/flows-cross-channel-messaging/create/configure-flows/frequency-capping-fc-and-do-not-disturb-dnd-for-flows#frequency-capping).
# Frequency capping
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/frequency-capping
Control how often users receive campaign messages across channels with MoEngage frequency capping, configured by channel or tag-based rules.
# Overview
Frequency capping (FC) lets you control your campaign's communication frequency with users. This significantly prevents customers from receiving bursts of communication from multiple channels simultaneously and improves user engagement and brand value in the market.
You can configure Frequency capping in two ways,
* **Channel and Campaign Delivery:** You can configure frequency capping for your campaign's communication based on delivery types, such as one-time, event-triggered, etc., from any channel.
* **Tag-based Frequency capping:** You can configure frequency capping for your campaign's communication with **tags** such as promotional, engagement, etc., which allows you to control the communication of your campaigns that have the tags you selected.
> [!NOTE]
>
> Availability of **tag-based frequency capping** depends on your plan. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/).
## Channels Supported for Campaign Delivery Type-based FC and Tag-based FC
| Channel name | Campaign Delivery types | Supported for Delivery type FC | Supported for Tag-based FC |
| - | - | - | - |
| Push |
One time/Periodic
Event triggered
Device triggered
Location triggered
Flows - Push API
| Yes | Yes |
| SMS, MMS & RCS |
One time/Periodic
Event triggered
Flows (SMS only)
| Yes | Yes |
| Email |
One time/Periodic
Event triggered
Flows
| Yes | Yes |
| WhatsApp |
One time/Periodic
Event triggered
Flows
| Yes | Yes |
| Connector |
One time/Periodic
Event triggered
Flows
| Yes | Yes |
| In-App |
On Session start
On Screen load
On Custom Event - Flows
| Yes | Yes |
| On-Site Messaging |
On Page load
On Exit Intent
On Custom Event
| Yes | Yes |
## Configure Frequency Capping
The Frequency Capping settings page is divided into **Outbound Channels** and **Inbound Channels**. You can configure FC for multiple channels and delivery types within their respective sections.
> [!NOTE]
>
> The frequency capping you configure applies only to the upcoming campaigns and does not affect existing ones.
1. Log in to the MoEngage dashboard.
2. On the left navigation menu in the MoEngage dashboard, select **Settings > Channels.**
3. In the **Channels** section, select **Delivery controls.**
4. On the **Delivery controls** page, click the **Frequency capping** tab.
5. The page is divided into **Outbound Channels** (Push, SMS, Email, etc.) and **Inbound Channels** (In-App, On-Site Messaging). Navigate to the desired section to configure the rules.
You can set frequency capping values for outbound channels either globally using **cross-channel configuration** or for individual channels. Inbound channels have their own dedicated configuration sections.
## Configure FC in Outbound Channels
For outbound channels, you can configure FC globally or for each channel specifically. Cross-channel configuration only applies to outbound channels.
* **Cross-channel configuration:** Turn on the **All channels** toggle and specify the limit for the number of communications that must be sent to users from all channels. This is the maximum limit for the total number of communications that must be sent to a customer within the specified number of days. For example, if you set the cap at four communications in 6 days, you can send only four communications in total from all the channels in the next 6 days. This is performed on a first-come, first-served basis.
> [tab] Push
>
> To enable Frequency capping for the Push notifications:
>
> * Turn on the **Push** toggle.
> * Enter the maximum number of communications you wish to send over a specified number of days (for example, two push notifications in one day). This configuration applies to all **Push** campaigns by default. For example, if the FC for **Push** is set as six communications for the next 6 days, a maximum of six communications are sent in the next 6 days. This is done on a first-come, first-served basis.
> * To set FC based on the campaign's delivery type, add a rule below by clicking the plus sign (+) at the end of each configuration and configure the delivery type to one time/periodic, event triggered, etc.
> * You can configure FC based on tags by adding another rule with the option, **select from** *campaigns with any/all of the selected tags* and select the tags to send communications accordingly.
>
> Example: To send only six **Push** communications to your users in the next 6 days from **all push campaigns** and send only two push notifications in the next 6 days from *campaigns with all the selected tags (Tags: all users, engagement, and promotion)* and not more than twice to the users from location-triggered campaigns in the next 6 days, you can set frequency capping as follows.
>
> 1. Send a maximum of 6 Web and App push from all push campaigns to a user in 6 days.
> 2. Send a maximum of 2 Web and App push from all campaigns with all the selected tags (Tags: all users, engagement, promotion) to a user in 6 days.
> 3. Send a maximum of 2 Web and App pushes from location-triggered campaigns to a user in 6 days. 
>
> ### Working of FC in Push
>
> Frequency capping limits the number of push notifications a user receives within a specified timeframe, based on the platform they are using. This capping operates at the user and platform level, not at the individual device level.
>
> For example, consider a frequency cap set at two notifications over two days, the configuration will be:
>
> * Android: 2 notifications
> * iOS: 2 notifications
> * Web: 2 notifications
>
> Scenario:
>
> * If a campaign targets Android, iOS, and Web, a user receives 1 notification per platform on Day 1. The frequency cap for each platform then reduces to 1.
>
> * If a subsequent campaign targets only Android and iOS on Day 2, users receive 1 notification per platform, assuming the two-day cap hasn't been reached for those platforms from other campaigns.
>
> * If a campaign later targets Android and Web, only Web users receive a notification if the Android frequency cap for that user was already met by previous campaigns within the two-day window.
>
> > [!NOTE]
> >
> > If a user has multiple devices on the same platform (e.g., three Android devices) and the frequency cap is one per day, each of their Android devices may still receive one notification.
> [tab] SMS, MMS, & RCS
>
> To configure Frequency capping for the SMS,MMS & RCS:
>
> * Turn on the **SMS, MMS & RCS** toggle.
> * Enter the maximum number of **SMS,MMS & RCS** you wish to send over a specified number of days (for example, one message in one day).
> * If the FC for **SMS, MMS & RCS** is set to three for the next 7 days, a maximum of three communications can be sent in those 7 days. This is done on a first-come, first-served basis.
> * This configuration applies to all **SMS, MMS & RCS** campaigns by default. By adding a rule below by clicking the plus sign (+) at the end of each configuration, you can configure FC based on campaign delivery type, such as one time or event triggered.
> * While configuring the **SMS, MMS & RCS** campaign, you can set FC based on tags by adding another rule with the option to select from campaigns with (any/all) of the selected tags and select the tags to send communications accordingly.
>
> Example: To send **SMS, MMS & RCS** to your users thrice a week and only twice from the *campaigns* with *all the selected tags (Tags: engagement, promotion)*, you can set frequency capping as follows.
>
> 1. Send a maximum of 3 SMS, MMS & RCS from all SMS, MMS & RCS campaigns to a user in 7 days.
> 2. Send a maximum of 2 SMS, MMS & RCS from the campaign with all the selected tags (Engagement, promotion) to a user in 7 days. 
> [tab] Email
>
> To configure Frequency capping for the Email:
>
> * Turn on the **Email** toggle.
> * Enter the maximum number of Emails you wish to send over a specified number of days (for example, five Emails in 6 days).
> * If the FC for **Email** is set to five for the next 6 days, a maximum of five communications can be sent in those 6 days. This is done on a first-come, first-served basis.
> * This configuration applies to all **Email** campaigns by default. By adding a rule below by clicking the Plus sign (+) at the end of each configuration, you can configure FC based on campaign delivery type, such as one time, event triggered, etc.
>
> Example: To send five **Email** communications to the users from all email campaigns and not more than three **Email** communications to the users from an *event triggered campaign* in the next 6 days. You can set the frequency capping as follows.
>
> 1. Send a maximum of 5 Emails from all email campaigns to a user in 6 days.
> 2. Send a maximum of 3 Emails from an event-triggered campaign to a user in 6 days. 
> [tab] WhatsApp
>
> To configure Frequency capping for the WhatsApp:
>
> * Turn on the **WhatsApp** toggle.
> * Enter the maximum number of WhatsApp messages you wish to send over a specified number of days (for example, one message in 2 days).
> * If the FC for **WhatsApp** is set to four for the next 6 days, a maximum of four communications can be sent in those 6 days. This is done on a first-come, first-served basis.
> * This configuration applies to all **WhatsApp** campaigns by default. By adding a rule below by clicking the plus sign (+) at the end of each configuration, you can configure FC based on campaign delivery type, such as one time, event triggered, etc.
>
> **Example:** To send a maximum of four **WhatsApp** communications from **all** **WhatsApp** campaigns in the next 6 days, two from *one time/periodic campaign*, you can set the frequency cap as follows.
>
> 1. Send a maximum of 4 WhatsApp messages from all WhatsApp campaigns to a user in 6 days.
> 2. Send a maximum of 2 WhatsApp from one/time periodic campaign to a user in 6 days 
> [tab] Connector
>
> To configure Frequency Capping for Connectors:
>
> * Turn on the **Connector** toggle.
> * Enter the maximum number of messages you wish to send over a specified number of days (for example, three messages in 2 days).
> * If the cross-channel FC is set to three for the next 5 days, a maximum of three communications can be sent in those 5 days. This would be done on a first-come, first-served basis.
> * This configuration applies to all connector campaigns by default. By adding a rule below by clicking the Plus sign (+) at the end of each configuration, you can configure FC based on campaign delivery type such as one time, event triggered, etc.
> * While configuring the **Connectors**, you can set FC for campaigns based on delivery types. By adding another rule with the option *select form campaigns with (any/all) of the selected tags,* you can send communications to the selected tags.
>
> Example: To send a maximum of six communications from **all Connector** campaigns, two communications from *one-time/periodic campaigns,* and two communications from *campaigns with any of the selected tags (activation, engagement, promotion)* in the next 6 days, you can set the frequency cap as follows.
>
> 1. Send a maximum of 6 Connector requests from all Connector campaigns to a user in 6 days.
> 2. Send a maximum of 2 Connector requests from an event-triggered campaign to a user in 6 days.
> 3. Send a maximum of 2 Connector requests from campaigns with any of the following tags. (Tags: activation, engagement, promotion) to a user in 6 days.
## Configure FC in Inbound Channels
Frequency capping for inbound channels (In-App and On-Site Messaging) helps you control how often users see messages in your app or on your website. You must configure the rules for each channel, based on trigger types and tags.

> [tab] In-App
>
> To configure Frequency Capping for In-App messages:
>
> 1. In the **Inbound Channels** section, turn on the **In-App** toggle.
> 2. A default rule is present to cap messages from **all In-App campaigns**. You can set the maximum number of messages a user receives in a given **session**, **hour(s)**, or **day(s)**. The duration uses a rolling window (for example, "in the last 7 days").
> 3. You can add multiple rules, which are combined using an **AND** condition. A workspace can have a maximum of 10 In-App frequency-capping rules in total, including up to 3 tag-based rules. Click the plus sign (+) to add a new rule.
> 4. You can create rules based on:
> * **Trigger Type**: Limit messages for specific triggers like *On Session start*, *On Screen load*, or *On Custom Event*. You can only use each trigger type once in your set of rules.
> * **Tags**: Limit messages from campaigns that have *any* or *all* of the selected tags.
>
> Example: To show a user a maximum of five In-App messages in 3 days, but ensure they see no more than one message per session that is triggered on a screen load.
>
> 1. Set the default rule to: Send a maximum of **5** In-App messages from **all In-App campaigns** to a user in **3 Days**.
> 2. Add a new rule: Send a maximum of **1** In-App message from **On Screen load campaigns** to a user in **1 Session**.
> [tab] On-Site Messaging
>
> To configure Frequency Capping for On-Site Messaging:
>
> 1. In the **Inbound Channels** section, turn on the **On-Site Messaging** toggle.
> 2. A default rule is present to cap messages from **all On-Site Messaging campaigns**. You can set the maximum number of messages a user receives in a given **session**, **hour(s)**, or **day(s)**.
> 3. Add more granular rules using the plus sign (+). All rules are combined with an **AND** condition.
> 4. You can create rules based on:
> * **Trigger Type**: Limit messages for specific triggers like *On Page load*, *On Exit Intent*, or *On Custom Event*. Each trigger type can only be used once.
> * **Tags**: Limit messages from campaigns associated with specific tags.
>
> Example: To show a maximum of 3 on-site messages per day, and ensure that promotional messages are only shown once per week.
>
> 1. Set the default rule to: Send a maximum of three On-Site messages from **all On-Site Messaging campaigns** to a user in **1 Day**.
> 2. Add a new rule: Send a maximum of **1** On-Site message from campaigns with **any of the selected tags (Tag: promotion)** to a user in **7 Days**.
## Applying FC in Different Scenarios
| Scenario | Configuration |
| - | - |
| **Scenario 1: Outbound, based on campaign delivery type** Let's assume you want to send a maximum of six communications from Push for an upcoming week. Not more than three communications from one time/periodic campaigns and not more than three communications from event triggered campaigns via Push. | The configuration for scenario 1 is as follows:
Enable **push** and set a maximum of 6 communications from all push campaigns to a user in 7 days
Add a rule with a **maximum of 3 communications** from **Web and App Push** from **one time/periodic campaign** to a user in 7 days.
Add another rule **with a maximum of 3 communications** from **Web and App Push** from **event triggered** to a user in 7 days.
 |
| **Scenario 2: Outbound, based on tags** Let's assume you want to send a maximum of 10 communications for an upcoming week. Not more than four communications from One time/periodic campaigns and not more than two communications from campaigns with all the selected tags (Tags: engagement, promotion) via Email notification. | The configuration for scenario 2 is as follows:
Enable **Email** and set a maximum of 10 emails from **all email channels** to a user in 7 days.
Add a rule with a **maximum of 5 communications** from one **time/periodic campaign** to a user in **7 days**.
Add another rule **with a maximum of 5 communications** from **all the selected tags** (Tags: engagement, promotion) to a user in 7 days.
 |
| **Scenario 3: Outbound, FC for cross channel configuration** Let's assume you want to configure a frequency cap limited to 10 communications across all channels in 7 days. Not more than four communications should be sent from campaigns with all the selected tags (promotion, engagement). | The configuration for scenario 3 is as follows:
Set a **cross channel configuration** limit to a maximum of 10 communications from **all campaigns/flows** to a user in 7 days.
Add a rule under **cross channel configuration** with a frequency cap of 4 communications **campaigns with all the selected tags** (Tags: promotion, engagement). Remaining communications are sent from any other campaign delivery types which are processed on first-come first-serve basis.
 |
| **Scenario 4: Inbound, based on trigger type** Let's assume you want to limit In-App messages to a maximum of 6 per week to avoid overwhelming users. However, messages triggered by loading a specific screen are very common, so you want to limit those to only 2 per day. | The configuration for scenario 4 is as follows:
In the **Inbound Channels In-App** section, set the default rule to a maximum of **6** communications from **all In-App campaigns** to a user in **7 days**.
Add a new rule with a maximum of **2** communications from **On Screen load campaigns** to a user in **1 day**.
|
## Editing FC Rules
If you try to edit the tags in your frequency cap setting once it is saved, it resets the existing FC configuration, and the new FC setting is applied to the communication.
For example,
You have configured a frequency cap with a limit of four SMS & RCS communications and not more than two SMS & RCS *from campaigns with any of the selected tags(Tags: activation and promotion)* in the upcoming week. On the third day, If you try to add or remove any tags from the configuration, It resets the communication setting to zero, and the *campaigns with any of the selected tags(Tags: activation and promotion)* are eligible to receive more than two SMS & RCS communications.
## Refresh setting
Refresh setting helps you reset the frequency cap daily based on a defined timezone.
* You can reset the Frequency Cap daily at 00:00 based on your app's or user's timezone for all supported channels. By default, it refreshes at 12 AM in the app's timezone for every user. This is especially useful if you are capping messages on a daily basis. 
* Click **Save**
## Delivery Controls
In [Step 3](/docs/user-guide/campaigns-and-channels/email/create/create-an-email-campaign#step-3-schedule-and-goals) (Schedule and Goals) of campaign creation for any channel (including In-App and On-Site Messaging), you can configure the delivery controls for your frequency capping.

**Ignore frequency capping:**
To send important communications (for example, a service outage announcement) irrespective of your frequency cap setting, turn on the **Ignore frequency capping** toggle under the **Delivery Controls** section.
**Count for frequency capping:**
When a campaign is set to ignore frequency capping, you can still have it count towards the cap for other campaigns. Turn on the **Count for the frequency capping** toggle to ensure this message is included when calculating the frequency cap for subsequent messages.
# Limit Messages for Periodic and Triggered Campaigns
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/limit-messages-for-periodic-and-triggered-campaigns
Controls how many times a user receives a Periodic or Event-Triggered campaign in MoEngage with limit messages, which uses a rolling window to block repeat sends until the limit resets.
## Overview
Limit Messages per User lets you control how many times an individual user receives a specific Periodic or Event-Triggered campaign, within a time period that you define. Use this setting to prevent overexposure — for example, to control how many times a user sees a coupon offer, a promotional push, or a reminder message.
The setting is available on the **Delivery Control** section of the campaign creation flow, for both new and existing campaigns. It is turned off by default, so campaigns behave exactly as they do today unless you explicitly enable it.
> [!NOTE]
>
> If you want to configure Limit Message using the Campaigns API, refer to the `limit_send_config` schema in the API reference for [Push](/docs/api/create-campaigns/create-campaign-draft-v5#body-one-of-0-delivery-controls-limit-send-config) or [Email](/docs/api/create-campaigns/create-campaign-draft-v5#body-one-of-1-delivery-controls-limit-send-config).
## Use Case
Marketers often need to make sure a benefit such as a coupon code, a limited-time offer, or a reward reaches a user only a fixed number of times, even if the campaign itself runs continuously or is triggered repeatedly by user behavior.
For example:
* Send a coupon code campaign to a user no more than **2 times in 30 days**, so the user doesn't receive more discount codes than intended.
* Send a cart-abandonment reminder no more than **once a week** per user.
* Send a welcome offer only **once**, ever, per user.
Without this feature, marketers had to build workarounds using custom attributes and additional logic to track and control send frequency. Limit Messages per User provides this control natively, without extra setup.
## Supported campaigns and channels
| Channel | Periodic | Event-Triggered |
| - | - | - |
| Push | Supported | Supported |
| SMS | Supported | Supported |
| WhatsApp | Supported | Supported |
| Email | Supported | Supported |
| Cards | Supported | Not Supported |
| Connectors | Supported | Supported |
## Things to Know
* This setting is turned off by default on all new campaigns.
* The limit and frequency setting has no effect on delivery speed or on any other part of the sending pipeline.
* This feature works independently of, and alongside, Frequency Capping — enabling one does not change the behavior of the other.
* The maximum frequency window you can configure is 1 year.
* This feature is also supported on existing campaigns.
* This feature is not applicable to transactional campaigns (for example, transactional email campaigns).
* This feature is not applicable to Flows.
## How the Limit is Counted
### What counts as a "message received"
For each channel and delivery type, there are different mechanisms on how MoEngage counts the limit to be exhausted. Following are the specific events used to determine successful delivery depending on the channel:
| Channel | Event used to count a send | Fallback event (if the primary event isn't available) |
| - | - | - |
| Push | Notification Received (Android / iOS / Web) | Notification Sent – iOS (used only when iOS delivery tracking isn't configured) platform |
| SMS | SMS Delivered | If a delivery callback is configured, *SMS Delivered* is used; if not, *SMS Sent* is used instead |
| Email | Email Delivered (for Amazon SES and SendGrid) | Email Sent (used for custom connectors and other native connectors) |
| WhatsApp | WhatsApp Message Delivered | — |
| Cards | Card Campaign Sent | — |
| Connectors | Connector Sent | — |
> **Note:** This event-based counting logic applies only to the channels listed above.
> [!NOTE]
>
> For **Push** and **Cards**, the limit is applied at the **platform level**, not at the user level. This means the count is tracked separately for each platform **Android**, **iOS**, and **Web** rather than as a single combined count for the user.
> **Example:** Suppose you set a limit of **2 messages in 7 days** on a push campaign.
>
> * This means the user can receive up to 2 messages on **Android**, up to 2 on **iOS**, and up to 2 on **Web** independently of each other, within the same 7-day window.
> * If a message goes out to a user on Android and iOS, one count is used up on each of those platforms.
> * If another message goes out to the same user on Android and iOS, one more count is used up on each. Both platforms have now reached their limit of 2.
> * If a third message goes out that targets only Web, it still gets delivered on Web (since Web hasn't hit its limit yet), even though Android and iOS are already exhausted for this window.
> In other words, hitting the limit on one platform does not block sends on the other platforms for the same user.
### Sliding Window Behavior
The limit works on a **sliding window**, not a fixed calendar period. Each time a send is triggered for a user, the system checks how many times that user has successfully received the campaign within the defined window, counting back from the current moment.
**Example:** Suppose the limit is set to 2 messages in 7 days.
* Every time a send is about to go out, the system checks: "In the last 7 days, has this user already received 2 messages from this campaign?"
* If the user has received fewer than 2, the message is sent, and the window is re-evaluated at the next send attempt.
* If the user has already received 2 within the trailing 7-day period, the message is blocked for that user until enough time has passed for one of the earlier sends to fall outside the 7-day window.
This means the window continuously "slides" forward with time rather than resetting on a fixed schedule (such as every Monday or on the 1st of the month).
> [!WARNING]
>
> * A delay in a periodic campaign's send time can affect delivery on the following day: The window is measured from the exact time of the user's previous successful send, not from the campaign's scheduled time. As a result, a delay on one day can cause a user to be skipped on the next.
>
> **Example:** A periodic campaign is scheduled to send daily at 8:00 AM, with a limit of **1 message in 1 day**.
>
> * On Day 1, the send is delayed and goes out at **8:15 AM**. The user receives it at 8:15 AM.
> * On Day 2, the campaign runs on schedule at 8:00 AM, and this user is due to receive it at **8:01 AM**.
> * Only 23 hours and 46 minutes have elapsed since the user's last successful delivery (8:15 AM the previous day), so the 24-hour window has not yet completed. The send is blocked, and the user does not receive the campaign that day.
> This behavior is more likely to occur with tight limits, such as 1 message per day, on campaigns prone to delayed sends.
> * Calendar months have differing lengths, which can affect delivery for monthly campaigns: A frequency defined in days (for example, 30 days) is measured as an exact day count, not as a calendar month. If a calendar month has fewer days than the configured frequency, a user may not be eligible to receive the next occurrence.
>
> **Example:** A campaign is set to send monthly on the 15th, with a limit of **1 message in 30 days**.
>
> * The user receives the campaign on **February 15**.
> * There are fewer than 30 days between February 15 and March 15 (28 or 29, depending on the year).
> * As a result, the 30-day window has not completed by March 15, and the user is not eligible to receive the campaign on that occurrence.
> To avoid this, use a frequency unit of **Month(s)** rather than an equivalent number of days for monthly campaigns.
## Configure Limit Messages per User

1. Create or edit a Periodic or Event-Triggered campaign.
2. Go to **Step 3** of the campaign creation flow, where the channel-specific delivery settings appear.
3. Under **Delivery controls**, turn on the **Limit messages per user** toggle.
4. Once enabled, you'll see **Prevent a user from receiving the campaign more than a set number of times**, followed by the configuration row:
* **No more than \[ ] messages in \[ ] \[unit] per user**
* The first field is the maximum number of messages a user can receive from this campaign (up to **100**).
* The second field and dropdown define the time window, a number paired with a unit of **Day(s)**, **Week(s)**, **Month(s)**, or **Year**. Whichever unit you choose, the window cannot exceed **1 year** (for example, up to 365 days, or up to 52 weeks, or up to 12 months).
For example, setting this to **no more than 9 messages in 1 Year per user** means a user can receive at most 9 instances of this campaign in any rolling 1-year period.
5. Save or publish the campaign.
Once published, you'll be able to see the configured limit under **Limit message** in **Delivery control**, on the **Scheduling** tab of the campaign's **Info** page — for example, shown as **"1 time in 1 day"**.

## Edit an Existing Limit
You can update the number of messages or the frequency at any time, on both scheduled and active campaigns.
* **Scheduled campaigns**: Edits apply directly, since the campaign hasn't started sending yet.
* **Active campaigns**: Any change to the limit, frequency, or the on/off toggle creates a **new version** of the campaign. The updated settings take effect from this new version onward.
* If you change the number of days or months in the frequency while the campaign is active, each user's existing countdown toward their next eligible send is also updated to reflect the new frequency value.
## Turn Off the Limit
You can turn off Limit messages per user at any time from the same Delivery Control section, on scheduled, active, and paused campaigns. As with other edits, turning this off on an active campaign creates a new campaign version, and the limit no longer applies from that point forward.
## View Applied Limits
The limit and frequency you've configured are also visible on the campaign's info page, alongside the other Delivery Control settings, so you can quickly verify what's active without opening the edit flow.
## View Users Excluded Due to the Limit
Whenever a user is dropped from a send because they've already hit the configured **Limit messages per user** limit, this is recorded as an entry in the campaign's **Error breakdown**, under a category such as **Failed to Send**.
This error breakdown is available in the campaign analytics page for every supported channel.

If you notice a drop or dip in the number of users reached by your campaign, check this error breakdown; it may simply mean those users had already received the campaign the maximum number of times allowed within your defined window, not that there was a delivery issue. These dropped users are also counted toward the campaign's **failed-to-send** numbers, so you can expect your failure count to reflect them as well.
## Frequently asked questions
> [accordion] Can I use Limit messages per user together with Frequency Capping?
>
> Yes. The two settings work independently, and using one does not affect the other's behavior.
> [accordion] Does the limit reset on a fixed schedule, like every week or every month?
>
> No. It uses a sliding window that is recalculated relative to the current time at every send attempt, not a fixed calendar period.
> [accordion] What happens if a message fails to deliver — does it still count against the limit?
>
> It depends on the channel and connector type, since that determines whether **Sent** or **Delivered** is used to count the limit. Where **Delivered** is used, failed or dropped sends don't count. For Push and Cards, the limit applies separately per platform, not shared across platforms.
>
> For more information, refer to [How the limit is counted](/docs/user-guide/settings/channels/delivery-controls/limit-messages-for-periodic-and-triggered-campaigns#how-the-limit-is-counted) above.
> [accordion] If I change the frequency on a live campaign, does it apply to users who are already partway through their current window?
>
> Yes. When you update the number of days/months, each user's existing countdown is adjusted to reflect the new frequency.
# Message Queuing
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/message-queuing
Automatically retry blocked messages in MoEngage with message queuing, which holds delivery until frequency capping or delay limits reset.
# Overview
> [!NOTE]
>
> *Message Queuing* is an Early Access feature. To enable it for your account, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
*Message Queuing* helps ensure your campaigns reach your audience by automatically retrying to deliver the messages that are not delivered due to delivery settings in the campaign creation flow. When a message is blocked by [Frequency Capping](/docs/user-guide/settings/channels/delivery-controls/frequency-capping) and [Minimum Delay](/docs/user-guide/settings/channels/delivery-controls/minimum-delay-between-campaigns), MoEngage places the message in a temporary queue instead of dropping it. As soon as the user becomes eligible, MoEngage automatically sends the message.
*Message Queuing* allows marketers to maximize campaign reach and maintain timely communication without needing to manually adjust campaign schedules.
> [!NOTE]
>
> *Message Queuing* is supported only for Push campaigns with delivery types: one-time, periodic, business event-triggered, event-triggered, and flow campaigns.
# Use Cases
*Message Queuing* enables a variety of flexible campaign delivery scenarios.
* **Campaign reach optimization:** You can automatically retry messages to users who miss a campaign due to [Frequency Capping](/docs/user-guide/settings/channels/delivery-controls/frequency-capping), ensure delivery to those affected by [Minimum Delay](/docs/user-guide/settings/channels/delivery-controls/minimum-delay-between-campaigns) settings, or maximize engagement without manual rescheduling.
* **Manage time-sensitive campaigns:** For promotions where immediate delivery is essential, such as flash sales, you can disable queuing at the campaign level. Disabling queuing ensures that messages that cannot be sent instantly are dropped entirely.
* **Prioritize journey continuity**: For multi-step flows like onboarding, you can ensure users receive every critical message in the correct sequence. Instead of skipping a step due to a temporary cap, the message is held and delivered later to keep the narrative intact.
# How Queuing Works
When a campaign message is triggered but cannot be delivered due to pre-set delivery rules, the *Message* *Queuing* feature holds the message for a later attempt.
The following steps outline how message queuing works:
1. **Trigger and Check:** A message is triggered for a user, and MoEngage checks for delivery restrictions in the following order: DND > Frequency Capping > Minimum Delay. In event-triggered campaigns, the order of execution is DND > Campaign Minimum Delay > Frequency Capping > Global Minimum Delay.
2. **Queue:** If a restriction is met, the message is placed in a queue for the duration configured in step 3 of campaign creation, instead of being dropped.
3. **Retry:** MoEngage automatically attempts to resend the queued message as soon as the user becomes eligible (for example, the frequency cap resets, the minimum delay passes, or the DND window ends).
4. **Send or Drop:**
* If the user becomes eligible within the defined queuing duration, MoEngage sends the message.
* If the queuing duration expires before the user becomes eligible, MoEngage drops the message. The reason for the drop is recorded in your campaign analytics (for example, "After FC Removal").
> [!NOTE]
>
> * For *One-Time,* *Periodic (child), and Business event-triggered (child)* push campaigns, the campaign status remains *Sending* until all queued messages are sent or dropped.
> * When a user has multiple messages in the queue, MoEngage sends them in the order they were queued, *First-In, First-Out,* as soon as a delivery window is available.
> * If *Ignore FC* and *Ignore Min delay* are both enabled for a campaign, the queuing settings are automatically disabled for that campaign.
> * The *Campaign Minimum Delay* applies exclusively to *Event-triggered* Campaigns.
> * When you edit an event-triggered campaign and create a new version, MoEngage removes all users and resets the queue to zero (0).
## Queuing Behavior with DND Settings
Your campaign's DND settings and Queuing settings work together to control message delivery. Here is an explanation of how they interact.
### When You Respect DND Hours (Ignore DND is OFF)
* **With Queuing ON:** All messages that would have been dropped (for DND, FC, or Minimum Delay) are queued. MoEngage waits for the DND window to pass and for the user to be eligible based on other rules before sending. This is the best way to ensure maximum delivery while respecting user preferences.
* **With Queuing OFF:** Only messages dropped by DND are queued to be sent the next day (if you use the "Save and Send" DND option). Messages blocked by FC or Minimum Delay are dropped immediately.
### When You Ignore DND Hours (Ignore DND is ON)
* **With Queuing ON:** MoEngage sends messages at any time, as DND is not a factor. *Message Queuing* can only be used for messages dropped by Frequency Capping or Minimum Delay, and they are sent as soon as those specific limits are cleared, regardless of the time of day.
* **With Queuing OFF:** MoEngage sends all messages immediately. No messages are held for DND.
# Dashboard Configuration
You can configure *Message Queuing* settings directly within the campaign creation workflow, as mentioned below:
## Enable Queuing for a Campaign
1. In step 3: [**Schedule and goals**](/docs/user-guide/campaigns-and-channels/mobile-push/create/create-push-campaigns#step-3-scheduling-and-goals) of the push campaign creation flow, in the **Delivery controls** section, locate the **Enable Message Queuing**toggle.
2. You can:
* **Enable queuing:** Turn on the **Enable Message Queuing** toggle to automatically queue messages that are blocked by Frequency Capping or Minimum Delay.
* **Set queuing duration:** Specify the duration for which a message should remain in the queue (for example, 5 hours). You can set a maximum of 48 hours.
* **Disable queuing:** Turn off the **Enable Message Queuing** toggle for time-sensitive campaigns where you prefer to drop messages that cannot be sent immediately.

## Monitor Queued Messages
After your campaign is live, you can monitor the performance of your queued messages from the campaign analytics dashboard.
* A temporary *Queued* banner shows the number of messages pending delivery.
* Delivery funnel statistics, such as *Attempted* and *Sent,* update in real-time as queued messages are delivered.
* The *Dropped* count initially includes messages that are still queued for delivery. This metric updates in real time as messages are sent, providing a funnel based on actual success rather than probable success.

## Message Queuing in Flows
*Message Queuing* is also supported within Flows, specifically for Push nodes. This ensures that even if a user reaches a Push node while ineligible for delivery (due to Frequency Capping or Minimum Delay), the message is held and retried rather than dropped.
To enable *Message Queuing* for a Push node in a Flow:
1. Open your Flow and click the **Edit** icon on the desired Push node.
2. On the Push campaign page that opens, navigate to the **Delivery controls** section.
3. Toggle **Enable Message Queuing** to **ON**.
4. Specify the **Queuing Duration**. For more information, refer to [Enable Queuing for a Campaign](/docs/user-guide/settings/channels/delivery-controls/message-queuing#enable-queuing-for-a-campaign).
> [!NOTE]
>
> You can enable *Message Queuing* across multiple Push nodes within a single Flow. This feature is supported for all Flow types.
### Queuing Rules for Flows
When *Message Queuing* is active within a Flow, the following rules apply:
* **Non-blocking Progression:** If a user is queued at a Push node (for example, due to Frequency Capping), they are not held at that node. The user continues their journey to the next stage of the Flow immediately, while the message remains in the queue for the specified duration.
* **Global Exit Criteria:** If a user meets the [Global Exit Criteria](/docs/user-guide/flows-cross-channel-messaging/create/create-flows/create-a-flow) and exits the Flow while a Push message is still in the queue, the message will still be delivered once the user becomes eligible. The exit from the Flow does not retrospectively remove messages already residing in the delivery queue.
# Example
The following scenarios illustrate how *Message Queuing* works with different campaign settings.
## Scenario 1: Frequency Capping and DND
This scenario illustrates how *Message Queuing* handles push notifications that are blocked by Frequency Capping (FC) and Do Not Disturb (DND) hours.
### Settings
* **Frequency Cap:** 3 push notifications in 1 day
* **DND Hours:** 10 PM to 7 AM
* **Queuing Duration:** 48 hours
| Time | Campaign | Restriction | Queuing Action | Delivery Status |
| - | - | - | - | - |
| 10 AM - 7 PM | C1, C2, C3 (Push) | None | N/A | Delivered (FC count: 3) |
| 8:00 PM | C4 (Push) | Frequency Cap | Queued | Pending delivery |
| 12:01 AM | C4 (Push) | DND Hours | Remains Queued | Pending delivery (FC reset, DND active) |
| 7:01 AM | C4 (Push) | None | Sent from the queue | Delivered |
## Scenario 2: Combining FC, DND, and Minimum Delay
This scenario illustrates how queuing manages multiple rules simultaneously for different channels, noting that queuing only applies to Push notifications.
### Settings
* **Frequency Cap:** 5 communications in 1 day
* **Minimum Delay:** 30 minutes between communications
* **DND Hours:** 10 PM to 7 AM
* **Queuing Duration:** 48 hours
| Time | Campaign | Restriction | Queuing Action | Delivery Status |
| - | - | - | - | - |
| 10:00 AM | C1 (Push) | None | N/A | Delivered (Comms count: 1) |
| 10:15 AM | C2 (Push) | Minimum Delay | Queued | Pending delivery |
| 10:31 AM | C2 (Push) | None | Sent from the queue | Delivered (Comms count: 2) |
| 10:45 AM - 11:30 AM | C3 (Email), C4 (Push) | None | N/A | Delivered (Comms count: 4) |
| 11:45 AM | C5 (Push) | Minimum Delay | Queued | Pending delivery |
| 12:01 PM | C5 (Push) | None | Sent from the queue | Delivered (Comms count: 5, FC limit reached) |
| 7:00 PM | C6 (Email) | Frequency Cap | N/A (Not a Push campaign) | Dropped |
| 10:00 PM | C7 (SMS) | Frequency Cap, DND Hours | N/A (Not a Push campaign) | Dropped |
# FAQs
> [accordion] What are the message queuing limits for campaigns?
>
> MoEngage enforces the following message queuing limits per client and workspace: Messages sent after a queue reaches its maximum limit are dropped. For one-time, periodic, and Business event-triggered, the Maximum Queued messages are 10,000,000. For Event-triggered campaigns, the Maximum Queued messages are 1,000,000.
> [accordion] What happens if I enable the Ignore FC, Ignore Min delay, or Ignore DND setting for a campaign?
>
> If you enable *Ignore FC*, *Ignore Min delay*, or *Ignore DND* for a campaign, the queuing settings for that campaign are automatically disabled.
> [accordion] Which channels support the Message Queuing feature?
>
> Message Queuing is supported for Push campaigns with delivery types one-time, periodic, business event-triggered, and event-triggered, and flow campaigns.
> [accordion] Where can I view the number of users currently in the queue for a campaign?
>
> You can view the number of currently queued users on the campaign analytics dashboard. A *Queued* banner is visible as long as messages are pending delivery.
> [accordion] Does my campaign's status show as "Completed" if there are still messages in the queue?
>
> No. For one-time and periodic campaigns, the campaign status remains *Sending* until all queued messages are sent or dropped after the queue duration expires.
> [accordion] Can I edit the queuing duration for an active campaign?
>
> For periodic and triggered campaigns, you can edit the queuing duration. The change applies only to new messages being queued and does not affect messages already in the queue.
> [accordion] How does message queuing work for one-time, periodic, and event-triggered campaigns in versioning?
>
> * When you edit an event-triggered campaign and create a new version, MoEngage removes all users and resets the queue to zero (0).
> * For one-time and periodic campaigns, the system processes and sends messages already in the queue using the original campaign version.
# Minimum delay between campaigns
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/minimum-delay-between-campaigns
Set a minimum time gap between campaign deliveries in MoEngage to prevent users from receiving multiple notifications in quick succession.
Marketers create multiple campaigns in a day, spaced by 5-10 mins. As much as marketers try to create a campaign that has non-overlapping segments, they cannot ensure that there are zero overlaps. Because of this, end-users receive more than one notification or message within 5-10 mins which deteriorates their experience.
To improve this notification/message delivery experience, marketers can ensure that two or more notifications/messages are not delivered in quick succession to any device/app/website using this setting. Marketers can configure a delay between two push/in-app/osm notifications delivered to a user.
If you do not want end users to receive two push notifications within 30 minutes, set the Minimum Delay between two notifications as 30 minutes.
**Example 1**\
If a user's device is eligible to receive notification N1 (sent using One Time or Periodic Push campaign C1) at time 1:00 pm UTC and N2 (sent using One Time or Periodic Push campaign C2) at 1:15 pm UTC. If the Min Delay setting is OFF, the user device will receive a campaign as per their Frequency Capping status. If the Minimum Delay setting is ON (and set as 30 mins), the user device will not receive N2.
**Example 2**\
If a user's device is eligible to receive notification N1 (sent using One Time or Periodic Push campaign C1) at time 1:00 pm UTC and N2 (sent using Event-Triggered campaign C2) at 1:15 pm UTC. If the Min Delay setting is OFF, the user device will receive a campaign as per their Frequency Capping status. If the Minimum Delay setting is ON (and set as 30 mins), the user device will not receive N2.
# Configure and Setup Minimum delay
To enable minimum delay, go to the following navigation in the MoEngage Dashboard and set the delay to the desired duration to control the communication being sent out.
**Settings -> Channels -> Delivery Controls -> Minimum delay**
To enable minimum for a channel:
1. Turn the channel toggle on.
2. Set the minimum delay to the desired time limit.
3. Click Save.

# Send campaign in recipient's time zone
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/send-campaign-in-recipients-time-zone
Schedule MoEngage campaigns to deliver at the right local time for each recipient by sending notifications in the user's own time zone.
Isn't it uncomfortable to deliver a campaign at 6 pm IST to your customer currently in PST who might be sleeping tight in his blanket? You will be committing two sins here: 1. disturbing your user, 2. getting ignored. You don't need to worry; we have your back!
MoEngage allows you to send the notifications to the users as per their local time zone i.e. If you schedule your campaign for 9:30 am IST, we will deliver to users in IST at 9:30 am IST and to users in PST at 9:30 am PST.
# Sending a campaign in the recipient's time zone
**To send the campaign in the recipient's time zone:**
While scheduling a general campaign, you can choose to send in the recipient's time zone by selecting the radio button for "Send in user time zone".
If the difference between your current time and your scheduled time is less than 24 hours, a few time zones would have passed. For those time zones you can decide to :
* Not send any message to target users if the time zone has passed
* Send the message in the campaign's default time zone i.e. EST for the example below.

> [!NOTE]
>
> * Available in outbound channels - Push, Email, SMS
> * Available for scheduled (One Time and Periodic) campaigns
Make sure to also save the app timezone under Settings >> App - General >> General Settings

App timezone is needed to calculate the correct time zone for the users whose time zone information is not available. In absence of an app timezone, the users whose time zone details are not available will not be targeted.
# To check the sending status:
Once you have created the campaign, you can check the delivery status across time zones in the **Time zone based delivery** section of Campaign Analytics.

You should be able to see these statuses. Their meaning is as under:
1. **Not sent due to time lapse -** Communication to users in this time zone has not been sent due to time lapse. The time lapse for a target time zone happens when the campaign is scheduled for a time that has already been passed in that target time while creating the campaign.
2. **Sent -** Communication to users in this time zone has been sent completely.
3. **Sending -** Communication to users in this time zone is being sent.
4. **__Pending - Communication to users in this time zone will be sent as and when the scheduled time is clocked in the respective time zone.__**
# To know how many users lie in the certain time zone:
You can check how many of your users are in a certain time zone via our **Segmentation query** e.g. you want to check how many of the users are in Indian Standard Time (IST) which is UTC + 5:30 i.e. 330 minutes ahead of UTC, you can try the below-mentioned filter.

Similarly, use value -330 for UTC - 5:30.
# How does this work?
The feature uses Offset time (saved under User Info as e.g. +330 for TZ 5 hours 30 minutes ahead UTC) with respect to the Universal Coordinated Time (UTC) reported by/calculated from your user's device. We update**Recipient's Time Zone** as the last reported/calculated time zone of the user. There might be two cases here:
1. **Recipient Time Zone Info is not available** - Users for whom Time Zone Info is not available will receive the campaign in the time zone selected while the campaign is created. Check your application time zone at MoEngage Dashboard > Settings > General Settings.
2. \*\*Recipient Time Zone Info is available -\*\*If time zone info is available for users, we will send them as and when the campaign scheduled time is clocked in their time zone.
So when you schedule a campaign, we will try to understand what all time zones your app users fall in. We will start by sending to the first time zone for your app users. For any timezone, there can be three scenarios with respect to your scheduled campaign:
1. **time has already passed in the recipient's Time Zone** - Depending on your choice either we won't be sending the campaign to the users or send it in the campaign's default time zone
2. **time is now** - We will fetch the users fulfilling the segment criteria and start sending the campaign to the users at this timezone
3. **time will occur later in the recipient's Time Zone** - When the right time comes, we will identify the users fulfilling the segment criteria and we will send the campaign to these users in this time zone.
Since some time zones are ahead of that of marketer's, to ensure that no zones miss their scheduled time, one needs to set up these campaigns at least 24 hours before one wants it to go out in his/her time zone. To ensure that Scenario 1 (i.e. time has already passed) does not happen, it is **strongly recommended** to create your campaigns at-least **24 hours in advance** if you are in World's last time zone.
**Important note:** The feature is not supported for campaigns targeting the segments created by CSV.
# Throttling
Source: https://moengage.com/docs/user-guide/settings/channels/delivery-controls/throttling
Control the send rate of push, email, SMS, WhatsApp, and webhook messages in MoEngage by setting requests per minute throttling limits.
Throttling allows you to control the rate at which communications (such as push notifications, emails, SMS & RCS messages, WhatsApp messages, or Webhook messages) are sent to users. This is helpful when you want to spread the load on your servers over a period of time instead of spiking the traffic. You can define the number of notifications or messages that can be sent per minute (requests per minute) for the MoEngage channels.
# Supported Channels and Delivery Types
| Supported Channels | Supported Delivery Type |
| - | - |
| SMS |
One-time
Periodic
|
| MMS |
One-time
Periodic
|
| RCS |
One-time
Periodic
|
| Email |
One-time
Periodic
|
| Push |
One-time
Periodic
|
| WhatsApp |
One-time
Periodic
|
| Connector |
One-time
Periodic
|
# Configure Throttling at the Workspace Level
Perform the following steps to configure throttling at the workspace (global) level:
1. In the left navigation of the MoEngage dashboard, click **Settings** > **Channels** > **Delivery controls** > **Throttling**.
2. Under **Campaign Throttling Limits**, turn on the toggle for the required channel.
3. Set the throttling limit to the desired RPM. The throttling value cannot be lower than the minimum limit specified for the channel or greater than the maximum limit specified for the channel. The minimum, maximum, and default rates are displayed below each channel's setting.
4. Click **Save**.

# Configure Throttling at the Campaign Level
In addition to the global throttling settings, you can configure different throttling settings for individual campaigns in step 3, **Schedule and goals**, of campaign creation if the option for throttling is available. For more information, refer to [Supported Channels and Delivery Types](/docs/user-guide/settings/channels/delivery-controls/throttling#supported-channels-and-delivery-types).
You can configure the throttling at the campaign level under delivery controls, as shown in the image below:
> [tab] Push
>
> 
>
> > [!NOTE]
> >
> > With the default FCM API rate limits reduced to 600,000 RPM, MoEngage is changing the maximum allowed throttle speed for push notifications to 500,000 RPM to ensure a single campaign does not breach the project limit. This change will apply to new and existing campaigns. You may still see drops because multiple campaigns are triggered together. For more information, refer to [Changes in Sending Speed with Private Key Configuration](/docs/developer-guide/android-sdk/push/basic/fcm-authentication).
> [tab] SMS, MMS & RCS
>
> 
> [tab] Email
>
> 
> [tab] Whatsapp
>
> 
> [tab] Connector
>
> 
MoEngage populates the default setting for throttling at the campaign level from the global settings.
**Example:**
If throttling for Push/SMS & RCS/Email/WhatsApp/Connector is enabled at the workspace (global level), the same throttling value will be shown by default in the **Request limit** field at the campaign level.
If throttling Push/SMS & RCS/Email/WhatsApp/Connector is disabled at the workspace (global level), the **Request limit** field at the campaign level will have the channel's default throttle value. Refer to the table below for the minimum, default, and maximum throttling values for all channels:
| Channel | Default Throttling Value (notifications, messages, or emails) per minute | Minimum Throttling Value (notifications, messages, or emails) per minute | Maximum Throttling Value (notifications, messages, or emails) per minute |
| - | - | - | - |
| Push | 100K | 60k | 500K for all campaign types. This is a suggested maximum based on the default FCM behaviour. If FCM has allocated a higher limit, you can set a value above 500K. |
| SMS & RCS | 60K | 1K |
Non-personalized campaigns - 200K
Personalized campaigns - 200K
Recommendations campaigns - 200K
|
| Email | 60K | 1K |
Non-personalized campaigns - 225K
Personalized campaigns - 225K
Recommendations campaigns - 225K
|
| WhatsApp | 60K | 1K |
Non-personalized campaigns - 200K
Personalized campaigns - 200K
Recommendations campaigns - 200K
|
| Webhook (Connector) | 60K | 1K |
Non-personalized campaigns - 200K
Personalized campaigns - 200K
Recommendations campaigns - 200K
|
Whether workspace-level (global) throttling is enabled or disabled, you can change the throttle speed while configuring a campaign and set different options for different campaigns. If the values in the workspace-level throttling and campaign-level throttling differ, the campaign-level throttling takes precedence and is applied.
# Throttling in Merlin AI Campaigns
Merlin AI is the in-house AI of MoEngage that predicts the engagement proportion by creating different variations of audiences and analyzing their behavior. For more information, refer [here](/docs/user-guide/ai-and-intelligence/ab-testing/create-multivariate-testing/perform-user-distribution-dynamically-using-merlin-ai).
Throttling does not apply in Merlin AI campaigns due to the campaigns' extended running time. To perform user distribution dynamically with Merlin AI in Push campaigns, you must run them for at least 1 hour, whereas for Email campaigns, you must run them for at least 2 to 4 hours. The run time may vary according to the channel, which can be selected from the options provided in A/B testing.
> [!NOTE]
>
> Merlin AI is available only for Push, Email, In-app Messaging, and On-site Messaging campaigns.
# Throttling in Best Time to Send (BTS)
[BTS](/docs/user-guide/ai-and-intelligence/timing/best-time-to-send) uses a prescriptive time slot to send communications to increase user interaction. BTS determines this by analyzing Push, SMS & RCS, and Email campaigns individually, predicting the optimal time slot from the (0-24 hour) bucket. In BTS, throttling takes precedence over the number of communications that should be sent in a particular time slot.
For example, the BTS is between 4 PM and 5 PM, with a volume of 15 million users. However, the throttling is limited to 200K RPM so that you can communicate only to 12 million customers in 1 hour (200k X 60 mins = 12 million). Because throttling takes precedence, you can communicate to the remaining 3 million users in the subsequent time slot (6 PM to 7 PM).
# FAQs
> [accordion] I set a higher throttling limit for my campaign, but it still took longer than expected to send. Why?
>
> The throttling RPM you configure controls the rate at which requests are **submitted** for processing — this is what you set and directly control. The rate at which MoEngage actually processes and sends out those requests is a separate rate that is **not** directly controllable.
>
> MoEngage tries to catch up with the submission rate, but the actual send rate can lag behind it:
>
> * For **non-personalized campaigns**, the processing rate is usually close to the submission rate.
> * For **personalized campaigns**, the processing rate can be around 50% or lower than the submission rate.
>
> As a result, even with a high throttling limit (for example, 250K RPM), the actual time taken to fully send a campaign can be longer than expected, and there is no way to precisely predict the additional time required.
# Data Management Alerts
Source: https://moengage.com/docs/user-guide/settings/data-management/data-management-alerts
Set up data management alerts in MoEngage to monitor event and attribute usage, detect anomalies, and stay compliant with tracking limits.
> [!NOTE]
>
> * Data Management Alerts feature is only available if you have Alert Management enabled for your workspace.
> * Note that only roles with permission to create custom alerts can view and edit alerts. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
# Overview
Data management alerts are notifications or warnings triggered by certain conditions related to the usage or volume of events and user properties in the data management dashboard of your MoEngage workspace. As a marketer, you can use these alerts to monitor and manage your data effectively, ensuring its quality, integrity, security, and compliance.
The following are the use cases that can be fulfilled using data management alerts:
* Monitor the event and user property usage proactively, thereby complying with your workspace's [Data Tracking Policies](/docs/user-guide/data/key-concepts/data-tracking-policies). When you set up usage alerts, you are notified based on your event and user property usage.
* Validate the configuration of your data integration with MoEngage. Incorrect configuration of the data integration results in unnecessary event data flow to MoEngage. Setting up event volume alerts lets you know if such a flow occurs.
You can access this feature from **Settings** > **Analytics and Data** > **Data Management**.
# Create a Usage Alert
This option allows you to create alerts based on the usage of data. You can create alerts for event usage and user property usage. Perform the following steps to create an event usage alert:
1. In the **Data Management** dashboard, click on the **Unique events used** or **Unique user attributes used** card. 
2. In the **Create alert - Event usage** dialog box, enter the following details: 
1. In the **General details** section, enter the following details:
1. **Alert name**: Type a name for your usage alert for easy identification.
2. **Send alert via**: By default, you can send alerts through **Email.** This field is auto-populated.
2. In the **Alert condition** section, create a condition for receiving alerts. When the data usage meets this condition, an alert is received.
1. In the **Send alerts when** list, select the type of usage for which you want to create an alert. The type of usage can be **Event usage**, **User property usage**. By default, **Event usage** is auto-populated.
2. By default, **Is greater than** is the supported operator. This field is auto-populated.
3. Select the usage limit above which you want to receive the alert.
1. When you select **Event usage**, by default, **511** is auto-populated because your default limit is 512. Any value greater than 511 means you have reached event usage limit. However, a system alert is configured by default when you reach 100 percent of your event usage limit.
2. When you select **User property usage**, by default, **255** is auto-populated because your default limit is 256. Any value greater than 255 means you have reached user property usage limit. However, a system alert is configured by default when you reach 100 percent of your user property usage limit.
> [!NOTE]
>
> The alert condition you build is evaluated daily, and alerts will be sent every time the condition is met.
3. In the **Members** list, select the members to whom the alert is to be sent. This list displays all the members in your current workspace.
3. Click **Save Alert**.
4. After saving, to manage the created alerts, click **Manage alerts** at the upper-right corner of the screen. For more information, refer to [Manage alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts).
> [!NOTE]
>
> You can also create the usage alert using the **Create Alert** option on the **Alert Management** page. While creating, make sure to select the **Create Alerts On** as **Events and User Property Usage**. For more information, refer to [Create Alert](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/create-an-alert).
# Create an Event Volume Alert
This option allows you to create alerts based on the volume of events. You can create alerts for All events, All custom events, All system events, and Individual events. Perform the following steps to create an event volume alert:
1. In the **Data Management** dashboard, click on the **Event volume (All events)** or **Event volume (Custom events)** card. 
2. In the **Create alert - Event volume** dialog box, enter the following details: 
1. In the **General details** section, enter the following details:
1. **Alert name**: Type a name for your usage alert for easy identification.
2. **Send alert via**: By default, you can send alerts through **Email.** This field is auto-populated.
2. In the **Alert condition** section, in the **Events** list, select the type of event for which you want to create an alert. Following are the types of events in the list: 
* **All events**: Allows you to create alerts for all events, including custom and system events.
* **All custom events**: Allows you to create alerts for all custom events,which are events that you track.
* **All system events**: Allows you to create alerts for all system events, which are events that MoEngage tracks by default.
* **Individual event**: Allows you to create alerts for a particular event, which can be a custom or system event.
3. In the **Send alerts when event volume for the selected event(s)** section, create a condition for receiving alerts. When the event volume meets this condition, an alert is received.
1. **Select operator** from the list. The following operators are supported:
* **Is greater than**: Allows you to set an alert when the event volume is greater than the entered value. After selecting this operator, select the following values: 
1. In the **Select value** list, select the event volume for which you want to receive the alert.
2. In the **Select duration** list, select the frequency of the alert. The following frequencies are supported:
* **in a calendar month**: Allows you to set up the frequency of alerts for each day in a month.\
For example, if you select the event volume as **90,** the operator **Is greater than,** and you create an alert on December 9, the system checks from December 1 to December to see if the cumulative event volume is greater than 90. Starting the next day December 10), the system checks again from December 1 to December 10 to see if the cumulative event volume is greater than 90. This continues till December 31, and an alert is sent whenever the cumulative event volume is greater than 90. If the condition is met before the end of the calendar month, alerts will be sent daily for the remaining days of the month.\
Note that the alert condition evaluation is reset at the start of the month.
* **in a calendar week (Sun-Sat)**: Allows you to set up the frequency of alerts within a week\
For example, if you select the event volume as **90,** the operator **Is greater than,** and you create an alert on Monday, the system checks from Sunday to Monday to see if the cumulative event volume is greater than 90. Starting the next day (Tuesday), the system checks again from Sunday to Tuesday to see if the cumulative event volume is greater than 90. This continues till Saturday, and an alert is sent whenever the cumulative event volume is greater than 90. If the condition is met before the end of the calendar week, alerts will be sent daily for the remaining days of the week.\
Note that the alert condition evaluation is reset at the start of the week (Sunday).
* **in a day**: Allows you to set up the frequency of alerts within a day.\
For example, if you select the event volume as **90,** the operator **Is greater than** then members are alerted as soon as the event volume is greater than 90 within a day.
* **Is less than:** Allows you to set an alert when the event volume is less than the entered value. After selecting this operator, select the following values: 
1. In the **Select value** list, select the event volume by which you want to receive the alert.
2. In the **Select duration** list, select the frequency of the alert. The following frequencies are supported:
* **in a calendar month**: Allows you to set up the frequency of alerts within the time frame of a calendar month.\
For example, if you select the event volume as **90,** the operator **Is less than,** and you create an alert on December 9, the system checks from December 1 to December 9 to see if the cumulative event volume is less than 90. Starting the next day (Dec 10), the system checks again from December 1 to December 10 to see if the cumulative event volume is less than 90. This continues till December 31, and an alert is sent whenever the cumulative event volume is less than 90. If the condition is met before the end of the calendar month, alerts will be sent daily for the remaining days of the month. Note that the alert condition evaluation is reset at the start of the month.
* **in a calendar week (Sun-Sat)**: Allows you to set up the frequency of alerts within the time frame of a calendar week.\
For example, if you select the event volume as **90,** the operator **Is less than,** and you create an alert on Monday, the system checks from Sunday to Monday to see if the cumulative event volume is less than 90. Starting the next day (Tuesday), the system checks again from Sunday to Tuesday to see if the cumulative event volume is less than 90. This continues till Saturday, and an alert is sent whenever the cumulative event volume is less than 90. If the condition is met before the end of the calendar week, alerts will be sent daily for the remaining days of the week.\
Note that the alert condition evaluation is reset at the start of the week (Sunday).
* **in a day**: Allows you to set up the frequency of alerts within a day.\
For example, if you select the event volume as **90,** the operator **Is less than** then members are alerted as soon as the event volume is less than 90 within a day.
* **Increases by:** Allows you to set an alert when the event volume increases by a specified percentage compared to the average event volume of specified previous days. After selecting this operator, select the following values: 
1. In the **Enter value** list, select the increase in event volume percentage for which you want to receive the alert.
2. Select the number of previous days for which you want to compare the specified increase in event volume.\
For example, if you select the event volume percentage as 50 and the number of previous day as 10, the condition is *Members will be alerted as soon as the event volume increases by 50% compared to the event volume of the previous 10 day(s)*.
* **Decreases by:** Allows you to set an alert when the event volume decreases by a specified percentage compared to the average event volume of specified previous days. After selecting this operator, select the following values: 
1. In the **Enter value** list, select the decrease in event volume percentage for which you want to receive the alert.
2. Select the number of previous days for which you want to compare the specified decrease in event volume.\
For example, if you select the event volume percentage as 50 and the number of previous data as 10, the condition is *Members will be alerted as soon as the event volume decreases by 50% compared to the event volume of the previous 10 day(s)*.
4. In the **Members** list, select the members to whom the alert is to be sent. This list displays all the members in your current workspace.
3. Click **Save Alert**.
4. After saving, to manage the created alerts, click **Manage alerts** at the upper-right corner of the screen. For more information, refer to [Manage alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts).
> [!NOTE]
>
> You can also create the event volume alert using the **Create Alert** option in **Alert Management** page. While creating, make sure to select the **Create Alerts On** as **Events Volume**. For more information, refer to [Create Alert](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/create-an-alert).
# Create User Volume Alert
This option allows you to create alerts based on the user volume. You can create alerts for the volume of users who use both web and mobile. Perform the following steps to create user volume alerts:
1. In the **Data Management** dashboard, click on the **Web user volume (30-day)** or **Mobile user volume (30-day)** card. 
2. In the **Create alert - User volume** dialog box, enter the following details: 
1. In the **General details** section, type the following details:
1. **Alert name**: Type a name for your usage alert for easy identification.
2. **Send alert via**: By default, you can send alerts through **Email.** This field is auto-populated.
2. In the **Alert condition** section, the **User metric** is auto-populated as **Tracked users (Web+Mobile)**.
3. In the **Send alerts when selected metric** section, create a condition for receiving alerts. When the user volume meets this condition, an alert is received.
1. By default, **Is greater than** is the supported operator. This field is auto-populated.
2. Select the user volume by which you want to receive the alert.
3. By default, the frequency **in a calender month** is supported. This field is auto-populated. This option allows you to configure the frequency of alerts within a month.\
For example, if you select the user volume as **90**, and you create an alert on December 9, the system checks from December 1 to December 9 to see if the cumulative user volume is greater than 90. Starting the next day (December 10), the system checks again from December 1 to December 10 to see if the cumulative user volume is greater than 90. This continues till December 31, and an alert is sent whenever the cumulative user volume is greater than 90. If the condition is met before the end of the calendar month, alerts will be sent daily for the remaining days of the month.\
Note that the alert condition evaluation is reset at the start of the month.
4. In the **Members** list, select the members to whom the alert is to be sent. This list displays all the members in your current workspace.
3. Click **Save Alert**.
4. After saving, to manage the created alerts, click **Manage alerts** at the upper-right corner of the screen. For more information, refer to [Manage alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts).
> [!NOTE]
>
> You can also create the user volume alert using the **Create Alert** option on the **Alert Management** page. While creating, make sure to select the **Create Alerts On** as **Active Users Volume**. For more information, refer to [Create Alert](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts).
# Overview - Data Management
Source: https://moengage.com/docs/user-guide/settings/data-management/overview-data-management
Get a comprehensive view of tracked events and user properties in MoEngage Data Management, including quotas and auto-blocked data insights.
The Data Management feature provides a comprehensive insight into the data you track in MoEngage. The data encompasses various crucial elements, including events and user properties. You can access this feature from **Settings** >**Data** > **Data Management**.
> [!NOTE]
>
> If you have [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, the Data Management will have associated changes. For more information, refer to [Portfolio: Data Ingestion and Management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management).
Following are the key information available from the Data Management dashboard:
* Clear visibility of unique events and unique user properties tracked for your MoEngage account out of the total allowed quota of events and user properties.
* Displays the count of auto-blocked events and user properties automatically blocked due to limit breach.
* Displays the volume of users and events processed through MoEngage.
* Displays the top 10 events based on volume.

## Overview Tab
The Overview tab of data management gives you high-level information about the number of unique events and user properties currently tracked for your MoEngage account.
### Usage
Provides information about the usage of events and user properties in MoEngage.
#### Events
* **Unique events used:** This denotes the number of unique events tracked for your MoEngage account out of the total available events that can be tracked. Clicking the **Unique events used** card takes you to the [**Event** tab](/docs/user-guide/settings/data-management/overview-data-management#usage).
* **Auto-blocked events.** This denotes the number of unique events that were blocked in your MoEngage account automatically when the unique events reached 100% of your workspace quota.  Perform the following steps to view the list of auto-blocked events:
1. On the **Overview** tab, click the **Auto-blocked events** card
2. You can view the list of all auto-blocked events on the **Event** tab 
#### User properties
* **Unique user attributes used**\
This denotes the number of unique user properties tracked for your MoEngage account out of the total available events that can be tracked. Clicking the **Unique user attributes used** card takes you to the [**User properties** tab](/docs/user-guide/settings/data-management/overview-data-management#usage).
* **Auto-blocked user attributes**\
This denotes the number of unique user properties that were blocked in your MoEngage account automatically when the unique user properties reached 100% of your workspace quota.  Perform the following steps to view the list of auto-blocked user properties:
1. On the **Overview** tab, click the **Auto-blocked user attributes** card
2. You can view the list of all auto-blocked user properties on the **User attributes** tab 
#### Limits on Events and Attributes Tracked in MoEngage
The below limits apply when you track data in MoEngage:
| **Type** | **Default Limit** | **Handling for overage** |
| - | - | - |
| Unique Events | 512 | Events not tracked in the last 60 days are auto-blocked first, and then new events are blacklisted if the limit is still breached. |
| Unique User Properties | 256 | User properties not tracked in the last 60 days are auto-blocked first, and then new user properties are blacklisted if the limit is still breached. |
| Unique Event Properties | 100 per event | Only the first 100 event properties will be ingested. |
For more information, refer to [Data Tracking Policies.](/docs/user-guide/data/key-concepts/data-tracking-policies)
### Volume
Provides information about the volume of users and events processed through MoEngage. Changing the date range filter affects the **Event Volume (All Events)** and **Event Volume (Custom Events)** charts. The system generates charts based on the date range defined by the user.
> [!NOTE]
>
> Backdated events are not included in the Event Volume charts. For instance, any event ingested today that is dated for a previous day (For example, events ingested on November 17th, dated for November 16th) will not be reflected in the chart metrics.

* **Event volume (All events)**\
This denotes the total count of all events ingested into MoEngage from various sources. The total event includes both system and custom events. Clicking the **Event volume** card directs you to the analytics chart, allowing you to filter events based on day-level granularity. 
* **Event volume (Custom events)** This denotes the total count of custom events ingested into MoEngage from various sources. Clicking the **Event volume** card directs you to the analytics chart, allowing you to filter events based on day-level granularity. 
* **Web user volume (30-Day)** This denotes the count of users who have executed the event *App/Site opened* using the *Web* platform. Note that a user who opens an app/site at least once a month is considered an active user. Clicking the **Web user volume** card directs you to the analytics chart, allowing you to filter users based on month-level granularity. 
* **Mobile user volume (30-Day)** This denotes the count of users who have executed the event *App/Site opened* using the *Mobile* platform. Note that a user who opens an app/site at least once a month is considered an active user. Clicking the **Mobile** **user volume** card directs you to the analytics chart, allowing you to filter users based on month-level granularity. 
* **Top events by volume** This displays the top 10 events with the maximum volume. Based on your requirements, you can filter for the top events from **All events** or **Custom events**.
## Event Tab
The **Event** tab lists all the events tracked for your MoEngage account and enables you to take action on your events. You can click the following event cards to view the associated list of events.

* **Unique events used** This denotes the number of unique events tracked for your MoEngage account out of the total available events that can be tracked.
* **Auto-blocked events** This denotes the number of unique events that were blocked in your MoEngage account automatically when the unique events reached 100% of your workspace quota.
* **Events not tracked** This denotes the number of events that have received no data since the chosen time duration. After reaching 100% of your workspace quota, these events can be blocked to create new events. 
You can perform the following action on your events:
* Click to download the event list in CSV format.
* Click to filter events based on **Visibility**, **Category**, **Platform**, **Last seen**, **First seen** and click **Apply**.

* Click the edit icon and select the columns you want to view in the events table. 
## User Attributes Tab
The **User attributes** tab lists all the user properties tracked for your MoEngage account and enables you to take action on your user properties. You can click **Unique user attributes used**, **Auto-blocked user attributes** cards to view the list of user properties associated with it.

You can perform the following actions on your user properties:
* Click to download the event list in CSV format.
* Click to filter events based on **Visibility**, **Category**, **Platform**, **Last seen**, **First seen,Tracked Data type, Allowed Data type, PII Masking** and click **Apply**. 
* Click the edit icon and select the columns you want to view in the user properties table. 
## Categories
The events and user properties listed on this dashboard are placed under their respective categories which are pre-created by MoEngage. You can expand any category to see the events or user properties under that category as shown below.

## Actions
The data management dashboard supports the following actions:
| Action | Result | Supported for |
| - | - | - |
| Edit Attribute or Event details | You can edit event, event property, or user property details. The event details include:
Display name
Status
Visibility
Description
The attribute details include:
Display name
Status
Visibility
Description
Data privacy configuration
Encrypt attribute
Mask attribute
Description
Allowed data type
|
Events
Event Properties
User Properties
|
| [Set / Edit Display Name](/docs/user-guide/settings/data-management/overview-data-management#edit-display-name) | On setting/editing the display name of an event or event property, the same will be visible in drop-downs to make it easier for marketers when creating the segments/campaigns. |
Events
Event Properties
User Properties
|
| [Change Status: Allowed](/docs/user-guide/settings/data-management/overview-data-management#status) | On changing the status of a blocked event to allowed, the event will start getting tracked for your MoEngage account. By default, all unique events will be allowed unless you breach data tracking limits. |
Events
Event Properties
User Properties
|
| [Change Status: Blocked](/docs/user-guide/settings/data-management/overview-data-management#status) | On changing the status of an event to blocked, the event will no longer be tracked for your MoEngage account even if received. All your existing campaigns for this event will not work. |
Events
Event Properties
User Properties
|
| [Change Visibility: On](/docs/user-guide/settings/data-management/overview-data-management#visibility) | On changing the visibility of an event to on, the event will start being visible in your drop-downs. By default, all unique events will be visible in drop-downs. |
Events
Event Properties
User Properties
|
| [Change Visibility: Off](/docs/user-guide/settings/data-management/overview-data-management#visibility) | On changing the visibility of an event to off, the event will stop being visible in your drop-downs. The campaigns/segments which are using events with visibility off will continue to work just fine as the events will still be tracked in your MoEngage account but only hidden from drop-downs. |
Events
Event Properties
User Properties
|
| [Set / Edit Description](/docs/user-guide/settings/data-management/overview-data-management#edit-display-name) | On setting/editing the description of an event/event property, you will be able to get additional context about tracking. This is already set by MoEngage for the MoEngage events as of now and those cannot be edited. |
Events
Event Properties
User Properties
|
| Data privacy configuration |
Turn on the **Encrypt attribute** toggle to encrypt the PII (Personal identifiable information) attributes and store them in the MoEngage data warehouse. Attributes values received before enabling this option will not be encrypted.
Turn on the **Mask attribute** toggle to hide PII from other users in your organisation.
|
Event Properties
User Properties
|
| [Set Allowed Data type](/docs/user-guide/settings/data-management/overview-data-management#set-allowed-data-types) | Set a single allowed data type of attributes so that incorrect data types are not ingested into the database. |
Event Properties
User Properties
|
> [!NOTE]
>
> Enabling attribute encryption is at no extra cost and cannot be reversed once turned on, encrypted values cannot be decrypted or unmasked afterward. Only data received *after* encryption is enabled gets encrypted, data already ingested stays as-is. Exports of an encrypted attribute are also encrypted.
### Status
The **Status** option allows you to view the allowed or blocked status of events, event properties, or user properties.
Whenever an attribute is ingested into the MoEngage system, its status is set to **Allowed**. Over time, you may start noticing incorrect events, event properties, or user properties in your account, likely due to incorrect integration or testing. If you wish to prevent such inaccurately tracked data points, you can block these attributes, which will then change their status to **Blocked.**
Perform the following steps to block allowed events, event properties, or user properties:
1. Select the event or user property you want to block.
2. Click **Block**. 
3. In the following dialog box that appears, click **Update**. 
4. After blocking, the status changes from **Allowed** to **Blocked**.
Perform the following steps to allow the blocked events, event properties, or user properties:
1. Select the event or user property you want to allow.
2. Click **Allow**. 
3. In the following dialog box that appears, click **Update**. 
4. After allowing, the status changes from **Blocked** to **Allowed**. Note that you can also allow auto-blocked events using the same procedure explained above.
5. Click the ellipsis icon to **Edit an attribute or event**, **Turn visibility off,** or **Block**. 
#### Blocking Due to Limits of Data Tracking
At times, if your events, event properties, or user properties breach the limits mentioned [here](/docs/user-guide/data/key-concepts/data-tracking-policies) or as shown in your [overview tab](/docs/user-guide/settings/data-management/data-management-alerts), then your new events, event properties, or user properties may be automatically blocked.
### Visibility
The **Visibility** option helps you hide or unhide events, event properties, and user properties from your drop-downs. By default, visibility is on for all events, event properties, or user properties ingested into the MoEngage system.
Your drop-downs may become cluttered over time due to too many events and event properties, even the ones your marketers don't need. In such cases, hiding ensures that such events and event properties no longer appear in the drop-down.\
Perform the following steps to turn off the visibility of your events, events attributes, or user properties:
1. Select the event, event property, or user property you want to turn off the visibility.
2. Click **Visibility Off**. 
3. In the following dialog box that appears, click **Update**. 
4. After turning it off, the **Visibility** changes from **On** to **Off**.
Perform the following steps to turn on the visibility of your events, events attributes, or user properties:
1. Select the event, event property, or user property you want to turn on the visibility.
2. Click **Visibility On**. 
3. In the following dialog box that appears, click **Update**. 
4. After turning it on, the **Visibility** changes from **Off** to **On**.
### Edit Display Name
Display name will enable your marketers to read your event, event property, and user property names clearly while creating segments.
At times, when your analytics systems are generating events, they may be encoded and are not easily readable by marketers. In such cases, you can always define a display name for your events and make it easy for your marketers.
Perform the following steps to set the display name for event property or user property.
1. Click the ellipsis icon against event property, or user property.
2. Click **Edit attribute**.
3. In the **Edit attribute details** side drawer, type the **Display name**.

4. Click **Save**. 
Perform the following steps to set the display name for event.
1. Click the ellipsis icon against event.
2. Click **Edit event**. 
3. In the **Edit event** side drawer, type the **Display name**.

4. Click **Save.**
#### Edit Description
The description will give additional context to your marketers on what an event does. You can set this from the edit event/edit event property/edit user property pop-up, similar to what is shown in the [edit display name](/docs/user-guide/settings/data-management/overview-data-management#volume) action.
### Set Allowed Data types
Setting up allowed data type action is supported for user properties and event properties and this ensures that any other data type is not recorded for the same attribute.
Perform the following steps to set allowed data types for event properties or user properties:
1. Click the ellipsis icon against event property, or user property.
2. Click **Edit attribute**.
3. In the **Edit attribute details** side drawer, select the data type from the **Allowed data type** list. 
4. Click **Save.**
#### How does this work?
For example, if you set the allowed data types of an attribute called "amount" as Numeric, then after this point, whenever the "amount" attribute is tracked, MoEngage will try to typecast the value to Numeric. For example, after setting allowed data types of amount as Numeric, if you send `{"amount": "145"}`, which is a string value, we will save it as 145 numeric and enable you to run numeric operators on this value in Segmentation and Analytics. However, if you send `{"amount": "sample value"}`, we will not be able to typecast this value, and hence it will be dropped. We will not save the amount: sample_value in your database to ensure accurate data is only saved.
The below table lists the data type of incoming attributes on columns and the allowed data type on rows and the value of each cell represents the data ingestion logic.
| | String | Numeric | Boolean | Date | Location |
| - | - | - | - | - | - |
| Any | Accepted as String | Accepted as Numeric | Accepted as Boolean | Accepted as Date | Accepted as Location |
| String | Accepted as String | Typecast to String | Typecast to String | Typecast to String | Typecast to String |
| Numeric | Typecast to Numeric if possible else drop | Accepted as Numeric | Dropped | Dropped | Dropped |
| Boolean | Typecast to boolean if possible else drop | Dropped | Dropped | Dropped | Dropped |
| Date | Typecast to Date for accepted formats else drop | Dropped | Dropped | Dropped | Dropped |
| Location | Typecast to Location for accepted format else drop | Dropped | Dropped | Dropped | Dropped |
By default, attributes will be set to **Any** which means that any data type will be accepted for this attribute. If more than one data type is set for an attribute then your segmentation drop-down will show multiple data types during query creation as shown below.

Once you set the allowed data type, only the allowed data type will be ingested going forward. However, we may still see older data types in your database due to past data present in the system. By default, the allowed data type will be pre-selected for your segmentation.
#### Effect on Data Already Ingested
Setting an allowed data type applies to data ingested after the change. MoEngage does not convert values that were already stored under the previous data type, and it does not re-ingest or rewrite past events, so an attribute keeps a mix of both data types until the older values age out of your retention window.
This has consequences worth planning for before you change the allowed data type of an attribute that is already in use:
* **Queries on the new data type match only the newer values.** A segmentation or analytics query that filters the attribute as the newly allowed data type returns 0 users, or far fewer than expected, because values stored under the previous data type are not evaluated as the new type. The count recovers as new data is ingested. This is the most common reason a segment count appears to drop right after a data type change.
* **Both data types stay available in the query builder.** The attribute keeps every data type it has ever been tracked as, so the segmentation dropdown continues to list the previous data type alongside the allowed one. The allowed data type is pre-selected, but the older type remains selectable.
* **Value suggestions still show values from the previous data type.** Suggestions are generated from data that has already been ingested, so values stored under the old data type keep appearing. They're removed only when newer values replace them after the attribute reaches its suggestion limit, or when the attribute receives no values for 60 days. For details, see [Value Suggestions](/docs/user-guide/segment/advanced-concepts/value-suggestions).
To query the full history of an attribute while both data types are present, add one condition per data type and combine them with OR — for example, the attribute as Date for newer values, OR the attribute as String for older values.
> [!NOTE]
>
> Relative date operators — such as "in the last 7 days" — are available only on the Date data type. Values still stored as String cannot be filtered by a relative date, so a segment that has to cover both data types needs an absolute value or range for the String condition. Where the full history matters and relative dates are required, re-ingest the historical values in the allowed data type instead of querying across both.
### Rules
> [!NOTE]
>
> This is an Early Access feature. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Rules let you enforce data standards on incoming user identifiers. When you enable a validation rule on an email or mobile number attribute, MoEngage checks every incoming value against the rule before ingestion. This reduces delivery failures and improves campaign performance.
When a validation rule is enabled on an attribute:
* Incoming values are checked against the rule before ingestion.
* Values that don't match the rule are dropped. The attribute value isn't stored, but the rest of the user record is accepted.
* Valid values are ingested normally.
> [!NOTE]
>
> Validation rules apply only to new incoming data. Existing user records are not retroactively validated. To clean existing data, re-import it using [File Imports](/docs/user-guide/data/imports/setting-up-a-file-import) or update it using [Data APIs](/docs/api/data/data-overview).
#### Built-in Rules
##### Email
The Email rule makes sure every email is campaign-ready. It enforces RFC 5322 standards and converts each email to lowercase.
* What it validates:
* Email syntax follows RFC 5322 (the global email standard).
* The local part (before `@`) and the domain contain only valid characters.
* The `@` is placed correctly and the domain is structured correctly.
* What it transforms:
* Converts all emails to lowercase (`User@Example.com` → `user@example.com`).
* Why it matters:
* Prevents duplicate profiles when the same user signs up with different casing.
* Stops invalid emails from causing hard bounces at send time.
* Reduces rejections from email service providers.
* Example:
| Incoming data | Result | Reason |
| :- | :- | :- |
| `user@example.com` | Stored as `user@example.com` | Valid |
| `User@Example.com` | Stored as `user@example.com` | Valid, converted to lowercase |
| `user.name@example.com` | Stored as `user.name@example.com` | Valid |
| `user..name@example.com` | Dropped | Invalid (consecutive periods) |
| `userexample.com` | Dropped | Invalid (missing `@`) |
| `user@` | Dropped | Invalid (missing domain) |
##### Mobile number
The Mobile number rule makes sure numbers comply with the E.164 global standard for phone numbers.
* What it validates:
* The number has a `+` prefix.
* The country code is valid (1–3 digits).
* The subscriber number is valid (up to 12 digits).
* The total length is 15 digits or fewer.
* The number contains no special characters (spaces, hyphens, or parentheses).
* Why it matters:
* E.164 is required by the WhatsApp Business API and SMS aggregators (such as Twilio and Vonage).
* It prevents ambiguity across different countries.
* It stops messages from failing due to routing errors.
* Example:
| Incoming data | Result | Reason |
| :- | :- | :- |
| `+14155552671` | Stored | Valid E.164 |
| `+919876543210` | Stored | Valid E.164 (India) |
| `+447123456789` | Stored | Valid E.164 (UK) |
| `14155552671` | Dropped | Invalid (missing `+` prefix) |
| `+1 (415) 555-2671` | Dropped | Invalid (contains spaces and parentheses) |
| `(0) 98765 43210` | Dropped | Invalid (not in E.164 format) |
> [!TIP]
>
> Before you enable the Mobile number rule, make sure your data source sends numbers in E.164 format. If your existing data uses local formats (such as `(0) 98765 43210`), update your ingestion pipeline to transform it first.
#### Enable Validation Rules
Perform the following steps to enable a validation rule on a user property:
1. On the **User attributes** tab, click the ellipsis icon against the attribute you want to apply a rule to (for example, your standard email attribute or a custom mobile number attribute).
2. Click **Edit attribute**.
3. In the **Edit attribute details** side drawer, under **Rules**, turn on the **Enable attribute validation rules** toggle.
4. Select **Email** or **Mobile number**. 
5. Click **Save**.
> [!WARNING]
>
> After a rule is active, all incoming data that doesn't match the rule is dropped. Test in a non-production environment first.
#### FAQs on Rules
> [accordion] Why am I unable to apply rules?
>
> You can apply validation rules only to an attribute whose allowed data type is **String** and that doesn't have PII encryption enabled.
> [accordion] How do the rules work with PII encryption?
>
> Validation rules can't validate encrypted data because the values appear as encrypted strings. If you use PII encryption, you must disable validation rules.
> [accordion] What happens if I disable a rule?
>
> Validation stops immediately. Existing records are not affected, and new incoming data is no longer validated.
> [accordion] Can I validate data after it's already in MoEngage?
>
> No. Validation rules apply only to incoming data. To validate existing user records, export the attribute, clean it externally, and re-import it.
### Array Typecasting
All the elements in the array have to be homogenous, which means they must be either integers or strings. If they are not homogenous, MoEngage tries to typecast (transform) the element and then store the data. Following is the example of an array in a CSV field: \[1|2|3] 
If an array has elements \[1 | 2 | “abc”] which has multiple datatypes and the defined datatype is Array Integer based on the first element, then the array or the entire datapoint will not be ingested as "abc" cannot be successfully typecasted into Integer.
Empty arrays \[] ingestion is supported and will unset the existing array attribute.
# Settings - Inform
Source: https://moengage.com/docs/user-guide/settings/miscellaneous/settings-inform
Configure MoEngage Inform settings including API credentials like Workspace ID and API Secret, plus user property fallback preferences.
There are two configurations for Inform on the MoEngage Dashboard:
1. [API Settings](/docs/user-guide/settings/miscellaneous/settings-inform#api-settings) - displays the Workspace ID and API SECRET.
2. [User Property Settings](/docs/user-guide/settings/miscellaneous/settings-inform#user-property-settings) - allows you to enable or disable user properties to be used as fallbacks for personalizing the Alert.
# API Settings
To access the Inform API settings, navigate to MoEngage Dashboard -> Settings -> APIs -> General Settings -> Inform.
The following parameters are available:
* **Workspace ID** - When you create an account in MoEngage, you will be assigned a unique identifier called the Workspace ID. This value will be used for identifying your account and authenticating it.
* **API SECRET**- API SECRET is the authentication key provided along with your Workspace ID. You can regenerate the API SECRET by clicking on the Regenerate API Secret icon. **Note**: MoEngage does not recommend regenerating the key unless there is a security breach. Once you generate and save a different API SECRET, API calls using the older SECRET won't work.
# User Property Settings
The **User Properties** available in MoEngage's user profile can be added as fallbacks for personalization in Inform. For example, if you want to send 'name' as a parameter in your alert and its value is not passed in the API request (as the microservice didn’t know the value for 'name') while sending the alert, you can define a fallback. You can configure the fallback to be fetched from the user property (that contains the value for the 'name' parameter in the request) of the user for whom the alert is being sent. If this fallback is not available for the requested user, you can define a default value to be used for completing the request.
**Note**: If User Properties are enabled, the SLAs for an Inform request will increase from 3 seconds (p90) to 4 seconds (p90).
To utilize user properties as part of Text personalization fallbacks, do the following:
1. Navigate to MoEngage Dashboard -> Settings -> Inform -> User Properties.
2. Turn on the *Enable user properties* toggle.
3. Click Enable in the popup to confirm the higher SLA for further Inform requests.

After enabling user properties, you’ll be able to define the fallbacks based on them, and subsequent API calls will start considering the user properties as part of the fallback algorithm. For more information, refer to [Personalization using User Properties](/docs/user-guide/inform/create/personalize-alert).
# Webhooks
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/alert-management/alert-destination/webhooks
The Webhook alert destination allows you to receive real-time alert notifications by sending an HTTP POST request with a detailed JSON payload to a URL you specify. This guide details the structure of the JSON payload and provides sample requests for different alert types.
> [!NOTE]
>
> When a configured alert is triggered, MoEngage sends an HTTP POST request to your designated webhook URL, enabling seamless integration with your internal systems, monitoring tools, or third-party services.
## Set Up Your Webhook URL
To set up a webhook destination, you must provide a URL. Your URL must be a publicly accessible endpoint that accepts `HTTP POST` requests with a JSON body.
> [!NOTE]
>
> Your webhook URL is the address of your application or service that will listen for and process the incoming alert notifications.
After obtaining your URL using one of these methods, enter it in the Webhook URL field when configuring the alert destination.
## Webhook Payload Structure
All webhook notifications follow a consistent JSON structure. The table below describes each field in the payload. Note that some fields, particularly within the `entity_data` object, are specific to certain alert types.
| Field name | Data type | Description |
| - | - | - |
| `alert_id` | String | The unique identifier for the alert that was triggered. |
| `alert_name` | String | The user-defined name of the alert. |
| `alert_type` | String | The type of the alert. Possible values: `CAMPAIGN_STATS`, `FLOW_STATS`, `CAMPAIGN_EXPIRY`, `APNS_TOKEN_EXPIRY`, `FACEBOOK_TOKEN_EXPIRY`. |
| `db_name` | String | The name of the workspace associated with the alert. |
| `alert_evaluation_frequency` | Object | An object describing how often the alert condition is checked. |
| `alert_evaluation_frequency.value` | Number | The numeric value for the frequency (for example, `1`). |
| `alert_evaluation_frequency.unit` | String | The unit of frequency (for example, `day`, `hour`). |
| `alert_triggered_at` | String | The ISO 8601 timestamp indicating when the alert was triggered. |
| `alert_evaluation_criteria` | Object | An object containing the specific conditions that triggered the alert. |
| `alert_evaluation_criteria.name` | String | The name of the metric being evaluated (for example, `DELIVERY_RATE`, `EXPIRY_DAYS`). |
| `alert_evaluation_criteria.operator` | String | The comparison operator used. For example, `gt` (greater than), `lt` (less than). |
| `alert_evaluation_criteria.threshold` | Number | The threshold value that was breached. |
| `alert_evaluation_criteria.unit` | String | The unit for the threshold (for example, `percentage`, `count`, `day`). |
| `alert_evaluation_criteria.range_start` | String | The ISO 8601 timestamp for the start of the evaluation window. |
| `alert_evaluation_criteria.range_end` | String | The ISO 8601 timestamp for the end of the evaluation window. |
| `alert_evaluation_criteria.moving_avg_range` | Object | Available only for relative alerts. Describes the window used to calculate the moving average (for example, the last 7 days). |
| `entity_data` | Object | A flexible object containing details about the specific entities (for example, campaigns, flows) that triggered the alert. This object is not available for certain alerts, such as `APNS_TOKEN_EXPIRY`. |
| `entity_data.count` | Number | The total number of entities listed in the `content` array. |
| `entity_data.content` | Array | An array of objects, where each object represents a single entity that met the alert criteria. The fields within each object vary depending on the `alert_type`. |
### entity_data.content object
The following table describes the possible fields in each object in the `entity_data.content` array.
| Field name | Data type | Description |
| - | - | - |
| `campaign_name` | String | The name of the campaign. |
| `campaign_id` | String | The unique identifier for the campaign. |
| `flow_name` | String | The name of the flow. |
| `flow_id` | String | The unique identifier for the flow. |
| `version_name` | String | The name of the flow version. |
| `channel` | String | The communication channel (for example, `PUSH`, `EMAIL`). |
| `delivery_type` | String | The delivery type (for example, `PROMOTIONAL`, `TRANSACTIONAL`). |
| `current_value` | Number | The metric's current value for the entity that triggered the alert. |
| `moving_avg_value` | Number | The metric's calculated moving average value. Available only for relative alerts. |
| `expiry_in_days` | Integer | The number of days until the campaign expires. |
| `event_type` | String | The type of the event being tracked. |
| `event_name` | String | The name of the event being tracked. |
## Verify the webhook signature
To ensure that webhook requests are authentic and originate from MoEngage, we include a digital signature in the request headers.
> [!NOTE]
>
> It is recommended to validate this signature on your server to prevent unauthorized access and ensure data integrity.
The signature is passed in the `Signature` HTTP header. It is generated by creating a SHA-256 hash of your API key concatenated with the raw request body.
### Generate and verify the signature
1. **Get your Campaign Report API key**: Find this key in your MoEngage dashboard by navigating to **Settings > Account > APIs**.
2. **Prepare the signature string**: Concatenate your [Campaign Report API](/docs/api/campaign-reports/download-campaign-report) key, a pipe character (`|`), and the raw JSON request body. Format: `YOUR_API_KEY|RAW_REQUEST_BODY`
3. **Calculate the hash**: Create a SHA-256 hash of the signature string and encode it as a hexdigest.
4. **Compare signatures**: Compare the hash you generated with the value from the `Signature` header in the incoming request. If they match, the request is authentic.
```python Python theme={null}
from hashlib import sha256
request_body_str = '{"alert_id":"","alert_name":"",...}'
campaigns_report_api_key = "YOUR_CAMPAIGN_REPORT_API_KEY"
signature_base_string = campaigns_report_api_key + "|" + request_body_str
generated_signature = sha256(signature_base_string.encode('utf-8')).hexdigest()
print("Generated Signature: ", generated_signature)
```
## Sample Payloads and cURL Requests
Below are samples of `cURL` commands demonstrating the `POST` request and JSON payload your webhook endpoint will receive. Replace `'https://your-webhook-url.com/endpoint'` with your actual endpoint URL.
### Campaign stats (CAMPAIGN_STATS)
#### Absolute Threshold Alert
This alert triggers when a metric crosses a fixed value.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "Delivery Rate Breach",
"alert_type": "CAMPAIGN_STATS",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "DELIVERY_RATE",
"operator": "gt",
"threshold": 10,
"unit": "percentage",
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
},
"entity_data": {
"count": 2,
"content": [
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5
},
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5
}
]
}
}'
```
#### Relative Threshold Alert (with Moving Average)
This alert triggers when a metric deviates from its historical moving average. A moving average is the average of a metric over a specific number of past periods (for example, the last 7 days), which helps identify significant deviations from recent performance trends.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "Delivery Rate Breach",
"alert_type": "CAMPAIGN_STATS",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "DELIVERY_RATE",
"operator": "gt",
"threshold": 10,
"unit": "percentage",
"moving_avg_range": {
"value": 7,
"unit": "day"
},
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
},
"entity_data": {
"count": 2,
"content": [
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5,
"moving_avg_value": 10.9
},
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5,
"moving_avg_value": 10.9
}
]
}
}'
```
### Flow Stats (FLOW_STATS)
These alerts are similar to campaign stats but focus on flow-level metrics.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "new alert for the flow commons",
"alert_type": "FLOW_STATS",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "TRIP_STARTED",
"operator": "lt",
"threshold": 20,
"unit": "count",
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
},
"entity_data": {
"count": 2,
"content": [
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5
},
{
"campaign_name": "",
"campaign_id": "",
"flow_name": "",
"flow_id": "",
"version_name": "",
"channel": "",
"delivery_type": "",
"current_value": 70.5
}
]
}
}'
```
### Campaign Expiry (CAMPAIGN_EXPIRY)
This alert notifies you when campaigns are nearing their expiration date.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "Expiry Breach",
"alert_type": "CAMPAIGN_EXPIRY",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "EXPIRY_DAYS",
"operator": "lt",
"threshold": 7,
"unit": "day",
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
},
"entity_data": {
"count": 2,
"content": [
{
"campaign_name": "",
"campaign_id": "",
"channel": "",
"delivery_type": "",
"expiry_in_days": 5
},
{
"campaign_name": "",
"campaign_id": "",
"channel": "",
"delivery_type": "",
"expiry_in_days": 5
}
]
}
}'
```
### APNS Token Expiry (APNS_TOKEN_EXPIRY)
This alert warns you when your Apple Push Notification Service (APNS) token is about to expire. Note that this payload does not contain an `entity_data` object.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "Apns token Breach",
"alert_type": "APNS_TOKEN_EXPIRY",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "EXPIRY_DAYS",
"operator": "lt",
"threshold": 7,
"unit": "day",
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
}
}'
```
### Facebook Token Expiry (FACEBOOK_TOKEN_EXPIRY)
This alert warns you when your Facebook token is about to expire. This payload also does not contain an `entity_data` object.
```bash cURL theme={null}
curl -X POST 'https://your-webhook-url.com/endpoint' \
-H 'Content-Type: application/json' \
-d '{
"alert_id": "{{alert_id}}",
"alert_name": "fb token Breach",
"alert_type": "FACEBOOK_TOKEN_EXPIRY",
"db_name": "{{db_name}}",
"alert_evaluation_frequency": {
"value": 1,
"unit": "day"
},
"alert_triggered_at": "2025-03-21T23:59:00Z",
"alert_evaluation_criteria": {
"name": "EXPIRY_DAYS",
"operator": "lt",
"threshold": 7,
"unit": "day",
"range_start": "2025-03-21T23:59:00Z",
"range_end": "2025-03-22T23:59:00Z"
}
}'
```
## Integrate Alert Management via Webhook URL
**1. Open app marketplace**
On the left navigation menu of your MoEngage dashboard, click **App marketplace**.

**2. Select Webhooks**
On the App marketplace page, click **Alert management**, and then select **Webhooks**.

**3. Open the Integrate tab**
On the Webhooks page, click the **Integrate** tab.

**4. Enter connection details**
On the Integrate tab, enter the following details:
* **Connection name**: Enter a name for the connection.
* **Connection URL**: Enter the webhook URL you created in the [Set up your webhook URL](#set-up-your-webhook-url) section.
**5. Connect**
Click **Connect**.

**6. Select webhook as an alert destination**
After the connection is defined, select the new destination from the **Send Alerts On** list while creating an alert on the Alert management page. You can select *Email*, *Slack*, or both.

**7. View configured destinations**
After adding the destinations, you can view the defined alert destinations on the Alert management page.

# Create an Alert
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/create-an-alert
Create campaign performance alerts in MoEngage to get real-time notifications about delivery failures, engagement drops, or cost spikes.
Ensuring a good campaign performance is crucial for marketers. Alerts provide real-time notifications of irregularities, helping you react promptly and optimize campaigns for better results. With alerts, you can analyze your campaigns in real time, identify and resolve any issues promptly, and ultimately ensure the success of your marketing efforts. By identifying issues like cost-per-conversion spikes or engagement drops, alerts empower you to make informed decisions and achieve campaign goals effectively, aligning with industry standards for efficient campaign management.
# Use Cases
* **Failure rate exceeding a threshold** If you want to be alerted when a campaign's failure rate exceeds a specified threshold within a custom time window, you can set alerts to ensure timely corrective actions. For example, you set an alert for a campaign's failure rate exceeding 10% in the last 6 hours, ensuring quick resolution when the threshold is breached.
* **Unsubscribe rate exceeding a threshold** Suppose you want to monitor unsubscribe rates over extended periods; you can set custom alerts to notify you when the rate exceeds a defined threshold, enabling proactive adjustments. For example, you set an alert for an unsubscribe rate exceeding 0.5% over 3 days, ensuring you can adjust the campaign when needed.
* **Failure rate increase compared to historical data** If you want to track deviations in campaign performance, set alerts comparing real-time failure rates with historical averages to receive early warnings of significant changes. For example, you set an alert for failure rates increasing by more than 10% compared to the last 90 hours, ensuring quick action if performance deviates.
# Create an Alert
You can create alerts from the Alert Management dashboard in MoEngage. However, you cannot create *System Alerts*. MoEngage offers role-based access control for account admins to enable different levels of access permissions (to dashboard components) for your team members. Only those roles that have permission to create custom alerts can do so. For more information, refer to [Access Permissions](/docs/user-guide/settings/account/team-management/access-roles).
Perform the following steps to create an alert:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Reports and Alerts** > **Alert management**.
2. On the **Alert management** page, click **+ Create alert**.
3. On the **Create alert** page, enter the following details:
## General details
| Field | Description |
| - | - |
| Alert name | This field specifies the unique name with which the alert will be identified on the dashboard. For example, if you wish to set up an alert for campaign expiry, you could name the alert *Campaign Expiry Alert*. You can look up the alert in the dashboard using its name. |
| Create Alerts On | This field specifies the type of the alert. Alerts can be one of the following types: **APNS Token Expiry**: You can set up alerts to receive notifications on the expiration of your APNS tokens. **Campaign Expiry**: You can set up an alert to receive notifications on the expiration of your campaigns. **Campaign Stats**: You can set up alerts to receive notifications when there is an increase or drop in the chosen metric in a given day or hour by a specified number. For example, you might wish to:
Take action when your delivery rate drops by 20% within an hour.
Watch a campaign with a high open rate or conversions within an hour.
**Note**: The stats for point channel campaigns in Flows will be available in the campaign stats alert type. **Flow Stats**: Alert the user when a specified metric is less than, greater than, decreases by, or increases by a specified percentage in a day or hour. **Facebook Token Expiry**: You can set up an alert to receive notifications on the expiration of your Facebook Tokens. **Events and User Attribute Usage**: You can set up alerts to receive notifications when the chosen metric increases by a specified amount daily. **Events Volume**: You can set up alerts to receive notifications when the event volume increases or decreases by a specified percentage or number within a specified month, week, or day. **Active Users Volume**: You can set up alerts to receive notifications when the active user's volume increases by a specified number within a specified timeframe. **WhatsApp Template Suspension**: You can set up alerts to receive notifications when WhatsApp templates are suspended. |
| Send Alert On | This field specifies the delivery destination for the alert. You are notified through the selected channel when the trigger conditions are met. For example, if an alert is configured to trigger when a campaign is two days from its expiration, a notification will be sent to the specified destination at that time. Supported delivery channels are:
Email
MS Teams
Slack
Webhooks
To configure a new destination, select the **+ Add Alert Destination** button from the dropdown. For detailed instructions, please refer to the following articles:
|
## Alert Condition
The **Alert Condition** section allows you to define the dynamics of the alert, including the alert type, metrics, supported operators, and evaluation frequency. This section specifies when the alert should be triggered based on the specified conditions.
| Alert Type | Metrics | Supported Operators | Alert Evaluation Frequency |
| - | - | - | - |
| APNS Token Expiry | NA | NA | Days |
| Campaign Expiry | NA | NA | Days |
| Campaign Stats |
Attempted
Sent
Delivered
Clicks
Failed
Send rate
Delivery rate
Failure rate
Click through rate
Open
Open rate
Click to open rate
Read
Read rate
Bounces
Bounce rate
Spam
Unsubscribe
Complaints
Converted Users- View Through
Converted Users- Click Through
CVR- View Through
CVR- Click Through
Revenue-View Through
Revenue-Click Through
|
Is less than
Is greater than
Decreases by more than
Increases by more than
| Values in the **Evaluate Condition on** field:
*On the last day*: Evaluates the metrics on the last day of the campaign.
*On the last hour*: Evaluates the metrics during the final hour of the campaign.
*Campaign start time*: Evaluates the metrics from when the campaign begins.
|
| Flow Stats |
Trips started
Active Trips
Ended Trips
Engaged Trips
Converted Users- View Through
Converted Users- Click Through
CVR- View Through
CVR- Click Through
Revenue-View Through
Revenue-Click Through
Drop Offs
|
Is less than
Is greater than
Decreases by more than
Increases by more than
| Values in the **Evaluate Condition on** field:
*On the last day*: Evaluates the metrics on the last day of the campaign.
*On the last hour*: Evaluates the metrics during the final hour of the campaign.
*Flows start time*: Evaluates the metrics from when the campaign begins.
|
| Facebook Token Expiry | NA | NA | Days |
| Events and User Property Usage |
Event usage
User property usage
| Is greater than | This field is automatically populated based on the following conditions:
The minimum value for the *user attribute usage* is the number of user properties ingested into MoEngage - 487. The maximum value for user property usage as per your plan is 512.
You will be alerted as soon as the user property usage is greater than 487.
The minimum value for the *events usage* is the number of events ingested into MoEngage - 479. The maximum value for event usage as per your plan is 512.
You will be alerted as soon as the event usage is greater than 479.
The condition will be evaluated daily, and alerts will be sent every time the condition is met. The alert will be evaluated at 7 AM in the Asia/Calcutta timezone. |
| Events Volume |
All Events
All custom events
All system events
Individual events
|
Is less than
Is greater than
Decreases by more than
Increases by more than
|
In a calendar month
In a calendar week
In a day
|
| Active Users Volume | Tracked Users (Web + Mobile) | Is greater than | In a calendar month |
| WhatsApp Template Suspension | NA | NA | On WhatsApp template sync |
### Supported Operators
| Operator | Description |
| - | - |
| is less than | Allows you to check if the chosen metric is less than a specified number of hours or days. |
| is greater than | Allows you to check if the chosen metric exceeds a specified number of hours or days. |
| decreases by more than | Allows you to check if the chosen metric has decreased by a specified percentage within an hour or a day. You can also check if the specified metric has decreased by the specified percentage with respect to the moving average of the last 'x' hours or days. |
| increases by more than | Allows you to check if the chosen metric has increased by a specified percentage within an hour or a day. You can also check if the specified metric has increased by the specified percentage with respect to the moving average of the last 'x' hours or days. |
### Supported Frequency
| Frequency | Description |
| - | - |
| Hour | You can check if the chosen metric is less than, greater than, increased by, or decreased by a specified number of hours. |
| Day | You can check if the chosen metric is less than, greater than, increased by, or decreased by a specified number of days. When you select this option, a message is displayed indicating when the alert will be evaluated.  **Note**:
The data used to evaluate the alert is from 12:00:00 AM to 11:59:59 PM on the last day, and the evaluation happens at 7 AM on the current day. For example, if the alert evaluation is happening on July 27, the 24-hour data of July 26 is used for evaluation.
The timezone in the message depends on the value configuration at **Settings** > **Account** > **General settings** > **Basic details** > **Time zone** setting.
|
| in a calendar month | You can check if the chosen metric is less than, greater than, increased by, or decreased by a timeframe specified within a calendar month. For example, if you create an alert on December 9 with a greater than condition, the system checks from December 1 to December 9 to see if the chosen metric is greater than the specified value. Starting the next day (Dec 10), the system checks again from December 1 to December 10 to see if the chosen metric is greater than the specified value. This continues till December 31, and an alert is sent whenever the chosen metric is greater than the specified value. If the condition is met before the end of the calendar month, alerts will be sent daily for the remaining days of the month. Note that the alert condition evaluation is reset at the start of the month. |
| in a calendar week (Sun-Sat) | You can check if the chosen metric is less than, greater than, increased by, or decreased by a timeframe specified within a calendar week. For example, if you create an alert on Monday with greater than condition, the system checks from Sunday to Monday to see if the chosen metric is greater than the specified value. Starting the next day (Tuesday), the system again checks from Sunday to Tuesday to see if the chosen metric is greater than the specified value. This continues till Saturday, and an alert is sent whenever the chosen metric is greater than the specified value. If the condition is met before the end of the calendar week, alerts will be sent daily for the remaining days of the week. Note that the alert condition evaluation is reset at the start of the week (Sunday). |
## Filter By
This section is displayed when the **Create Alerts On** field is set to one of the following values:
* Campaign expiry
* Campaign stats
* Flow stats
This field specifies the filter conditions for a campaign expiry alert and is used to filter campaigns expiring in 'x' days (specified in the Alert condition) on the following criteria:
* **Campaigns**: You can select all the campaigns or specify individual campaigns for which the alert needs to be set up. This field is available only for the *Campaign Expiry* and *Campaign Stats* alerts.
* **Flows**: You can select all the flows or specify individual flows for which the alert needs to be set up. This field is available only for the *Flow Stats* alert.
* **Channels**: You can select All Channels or specify individual channels for which the expiry alert needs to be set up. This field is available only for the *Campaign Expiry* and *Campaign Stats* alerts.
* **Delivery Types**: You can select All Delivery Types or specify them individually.
* **Tags**: You can select All Tags (Campaign/Flow tags) or specify them individually.
If no filter is specified, you will receive alerts for the chosen campaign alert types in all channels (*Campaign Expiry* and *Campaign Stats* alerts) or all flows based (*Flow Stats* alert).
## Members
This field lists the email IDs of the members who will be alerted. When left unspecified, all the members will be alerted via email.
4. Click **Create**. After the alert is created, you will see a success message (as shown below) and be redirected to the Alert Management dashboard, where the newly created alert is available.

# Alert Destinations
The Alert Destinations helps you reach your users where they’re most active, enabling real-time alerts without requiring users to switch between apps. You can now deliver real-time alerts directly to your preferred destinations in addition to *Email*, for detailed instructions, please refer to the following articles:
* [MS Teams](/docs/partner-guide/messaging-channels/messaging-apps/ms-teams)
* [Slack](/docs/partner-guide/messaging-channels/messaging-apps/slack)
* [Webhook](/docs/user-guide/settings/reports-and-alerts/alert-management/alert-destination/webhooks)
This helps you notify users without having to switch between tools. You can select your preferred alert destination from the **Send Alerts on** dropdown.
# How Alerts Work
MoEngage monitors campaign performance and triggers alerts when specified thresholds are met. The evaluation frequency and alert behavior depend on the campaign type and defined alert conditions. Below are examples of how alerts work for different delivery types:
> [!NOTE]
>
> This section specifically applies to alerts in Campaigns and Flows.
## One Time Campaigns
A one-time campaign is a single-instance communication, such as a promotional email for a flash sale. After sending the campaign, the system evaluates the specified performance thresholds within the defined time frame. If the set threshold is breached, an alert is triggered.
### Scenario
* Configured Alert: Open rate \< 10% to be evaluated one hour after the campaign is sent.
* Evaluation: The system checks the open rate after one hour and sends an alert if the rate is below 10%. No further alerts are generated for this campaign.
| Date | Time | Campaign Performance Status | Alert Notification |
| - | - | - | - |
| Feb 26 | 9:00 AM | Campaign sent | None |
| Feb 26 | 10:00 AM | Open rate = 7% | 1 Notification |
## Periodic Campaigns
A periodic campaign, such as a weekly newsletter, is sent on a scheduled basis. The system evaluates alerts at regular intervals (for example, every day or week) to track trends over time. If a performance threshold is breached during an evaluation, an alert is triggered.
### Scenario
* Configured Alert: Click-through rate (CTR) \< 5% to be evaluated every 7 days.
* Evaluation: The system checks the CTR every seven days. If the CTR drops below 5%, an alert is sent.
| Date | Time | Campaign Performance Status | Alert Notification |
| - | - | - | - |
| Feb 1 | 9:00 AM | Newsletter sent | None |
| Feb 8 | 9:00 AM | CTR= 4.5% | 1 Notification |
| Feb 15 | 9:00 AM | CTR= 6% | No notification |
For Periodic alerts, data considered is from Feb 1 to Feb 8 for the first alert and then from Feb 8 to Feb 15 for the second alert.
## Event-Triggered Campaigns
User actions, such as a transaction confirmation email, activate an event-triggered campaign. The system continuously monitors performance within a set evaluation period (for example, every 12 or 24 hours). If the threshold is breached during any evaluation window, an alert is triggered.
### Scenario
* Configured Alert: Email delivery rate \< 90% to be evaluated within a 24-hour window.
* Evaluation: The system checks the delivery rate every 24 hours. If it drops below 90% during any evaluation, an alert is sent.
| Date | Time | Campaign Performance Status | Alert Notification |
| - | - | - | - |
| Feb 25 | 9:00 AM | Campaign sent | None |
| Feb 26 | 9:00 AM | Delivery rate = 92% | No Notification |
| Feb 27 | 9:00 AM | Delivery rate = 88% | 1 Notification |
| Feb 28 | 9:00 AM | Delivery rate = 85% | 1 Notification |
For Event-triggered alerts, data considered is from Feb 25, 9:00 AM to Feb 26, 9:00 AM for the first alert, and then Feb 26, 9:00 AM to Feb 27, 9:00 AM for the second alert, and so on.
# Example
The following example illustrates how to set up an alert when your campaign's failure rate decreases by more than 10% from its start time.
1. On the **Create Alert** page, in the **General details** section, type the **Alert Name** as Test_Alert_Stats.

2. In the **Create Alerts On** list, click **Campaign Stats**.
3. In the **Alert Condition** section, enter the details as mentioned below:
1. In the **Evaluate Condition on** list, click **Campaign Start time**.
2. Choose the metric for which you want to set up the alert in the **Send alert when** list and select the operator as **Decreases by more than**.
3. Select the percentage in the textbox and choose **Hour** in the **Hour/Day** list.
4. You can compare this rate with respect to the moving average of the last 'x' hours or days.

4. Configure the **Filter by** conditions and add relevant members to the respective section.

5. Click **Create**.
Now that the alert is created, you can view and manage it from the Alert Manager. For more information, refer to [Manage Alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts).
# Overview - Alert Management
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/overview-alert-management
Set up alert management in MoEngage to monitor token expirations, campaign failures, and stat drops with automated real-time notifications.
Alert Management enables you to configure and receive alerts when there are changes in the system that you would like to monitor and act upon proactively. For example, you can set up alerts to be sent to you when your Facebook account's token or your APNS token is about to expire. Similarly, when a campaign is experiencing a lot of failures within an hour or there is a sudden drop in stats, you can set up alerts to be notified about these occurrences. You then get a chance to monitor and take corrective action at the right time. This could help you improve customer engagement and ROI.
> [!NOTE]
>
> Alert Management provides two sets of alerts:
>
> * Custom alerts are currently part of the Enterprise plan.
> * System alerts are available for customers across all paid plans.
Alert Management provides a centralized way to set up, manage, and subscribe to receive alerts about events that you would like to be notified about without reaching out to developers or the support team. With this feature, you can create an alert, edit it, and subscribe to it by yourself.
With Alert Management, you can:
* Receive information regarding issues with your campaigns or flows in a timely manner
* Proactively address issues before they turn into major problems
* Improve efficiency and productivity as no manual intervention is required to identify issues
* Improve ROI with proactive and timely action
## Alert Types
There are two types of Alerts:
1. **System alerts** - These alerts are available in the Alert Manager by default. Some examples of the System or default alerts are Campaign Expiry, Facebook Token Expiry, APNS Token Expiry, and Data Exports.
2. **Custom alerts** - These alerts are created and configured based on the criteria specified by you. For example, a custom alert could be set up to send a notification when the campaign stats of a periodic campaign see an increase in engagement metrics by over 20% within an hour.
## Subscription Management for Alerts
When creating an alert, you can add subscribers (members of your team). You can also subscribe to or unsubscribe from receiving an alert in the Alert Manager. You can also add other team members as subscribers to the alerts from the Alert Manager. For more information, refer to [Alert Subscription Management](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts#actions-that-can-be-performed-on-alerts).
# Use Cases
* Receiving alerts for APNS and Facebook token expiries
* Receiving alerts about campaigns that are expiring in the next fortnight
* Receiving alerts for campaign failure
* Receiving alerts when there are failures in campaigns that exceed a specified limit
* Receiving alerts when there is a drop or increase in campaign stats below or above a specified limit within an hour or a set time
* Receiving alerts for delivery failures when there are campaign delivery failures that exceed a specified percentage within a set time
* Receive alerts when WhatsApp templates are suspended.
* Receiving alerts for data exports when they are paused due to multiple failures. Refer to [Event Exports](/docs/user-guide/data/exports/events/overview-events-exports) for more information.
* Configuring custom alerts to get notifications for any event of your choice based on events specified by you.
# Next Steps
1. [Create Alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/create-an-alert#create-an-alert)
2. [Manage Alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts#navigation)
# Managing Alerts
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts
Edit, subscribe to, duplicate, or delete alerts from the MoEngage Alert Management Dashboard. Manage system and custom alerts in one place.
You can manage your alerts from the Alert Management Dashboard. Any alert created is listed in the dashboard. To perform any action, such as edit, subscribe, duplicate, and so on, you would need the required access permission to do so. For more information, refer to [Access Permissions for Alert Management](/docs/user-guide/settings/account/team-management/access-roles).
## Navigation
To access Alert management on the MoEngage dashboard, navigate to **Settings** **-> Reports and Alerts -> Alert management**.
The following tabs are available in the Dashboard:
1. **All alerts** - This section contains all the alerts created in your MoEngage account.
2. **System alerts** - This section contains the default alerts available as part of alert management. The system or default alerts are Campaign Expiry, Facebook Token Expiry, and APNS Token Expiry, and so on.
3. **Custom alerts** - This section contains custom alerts created on your request for your MoEngage account.
## Alert Information
The following information is available for all the alerts listed in all three tabs.
1. Alert name - This column contains the name of the alert.
2. Create alerts on - This column contains the alert type. For system alerts, the types are Campaign expiry, Facebook token expiry, APNS token expiry, Campaign Stats, Flows Stats, Events and User Property Usage, Events Volume and Active Users Volume.
3. Created by - This column specifies the email ID of the member who created the alert.
4. Subscribed by - This column specifies the email IDs of the members who've subscribed to the alert.
5. Subscription - This column specifies the subscription status of the logged-in user for the alert. For example, if you have subscribed to an alert, the status is **Subscribed to Email** and if you haven't subscribed to the alert, the status is **Subscribe to Email**. You can click on the *Subscribe to* link to subscribe to the alert.
6. Actions - Click on the to view the available options. For more information, refer to [Actions that can be performed on alerts](/docs/user-guide/settings/reports-and-alerts/alert-management/manage-alerts/managing-alerts#actions-that-can-be-performed-on-alerts).
## Actions That Can Be Performed on Alerts
You can perform the following actions on an alert by clicking the ellipsis icon at the end of the row.

| Field | Description |
| - | - |
| View | This action lets you view the created alert. Any member with access to the Alert management dashboard can view the alert. |
| Edit | This action lets you edit the alert. You can edit the fields the following sections only: - Alert condition - Filter by - Members **Note**: You cannot edit the fields in the **General details** section. You can also duplicate or delete the alert.  |
| Duplicate | This action lets you duplicate the alert. You cannot duplicate system alerts. |
| Unsubscribe | This action lets you unsubscribe from receiving the alert. |
| Subscribe others | This action lets you add other members as subscribers to receive the alert. For example, if someone were to join your team and you wish to add them to the subscribers to receive alerts about certain events, you can do so with this option.  |
| Delete | This action lets you delete the alert. Once deleted, the alert will not be available for viewing on the dashboard. |
## Search by alert name
You can specify an alert by its name in the Search bar and look it up, as shown below:

## Filter alerts
You can filter alerts by their type, creator, and subscribers. To Filter alerts, click **Filter alerts** at the top right corner and specify the criteria for filtering, as shown below:

# Dashboard Subscriptions
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions
Schedule and manage dashboard subscription emails in MoEngage. Share custom dashboard snapshots with your team and whitelist email domains.
A *Dashboard Subscription* enables you to receive a snapshot of your custom dashboard via email. Additionally, dashboard subscriptions allow you to share custom dashboards with users in your organization.
On this settings page, you can:
* [Create subscriptions](/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions#create-subscriptions)
* [Manage subscriptions](/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions#manage-subscriptions)
* [Whitelist domains](/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions#whitelist-domains)
> [!NOTE]
>
> The maximum number of dashboard subscriptions per workspace depends on your analytics package:
>
> * **Customer Journey Analytics (CJA):** 10 subscriptions
> * **Product Analytics (PA):** 25 subscriptions
# Create Subscriptions
Perform the following steps to create a dashboard subscription:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Reports and Alerts** > **Dashboard subscriptions**.
2. In the upper-right corner, click **Create**/**Manage** and select **Create Subscription**.

3. On the **Subscribe to Dashboard** dialog box, enter the following details:

1. In the **Dashboard** list, select the dashboard for which you wish to receive scheduled reports.
2. In the **Send report to** box, type or paste the email address(es) to which the email report must be sent and press Enter.
> [!NOTE]
>
> * A list of recipients is added as a comma-separated list.
> * You can add up to 50 email recipients to each subscription.
> * For non-registered users, the email domain must be whitelisted. For more information, refer to [Whitelist Domains](/docs/user-guide/settings/reports-and-alerts/dashboard-subscriptions#whitelist-domains).
3. In the **Frequency of sending reports** section, configure the following to send the dashboard report at a specific time and date:
| Field | Description |
| - | - |
| Daily, Weekly, or Monthly | Select the frequency at which you wish to send the dashboard report. |
| Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday | The day on which you wish to send the dashboard report. |
| Time | Use the arrows or type when you wish to send the dashboard report. |
| am or pm | Click am or pm to set the time. |
4. Click **Subscribe** to create the subscription.
> [!NOTE]
>
> * The **Dashboard** field is pre-populated when you create a subscription from the custom dashboard.
> * If a dashboard subscription is already present for any dashboard, the subscription is shown upfront, and you can edit the existing subscription if required.
# Manage Subscriptions
To manage existing subscriptions, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Reports and Alerts** > **Dashboard Subscriptions**. A list of all dashboard names will appear with the frequency of the subscription, the last update time, and the person who updated it.

2. You can perform the following actions:
* **Search**: To find subscriptions by email or dashboard name, use the search box at the top.
* **Edit/Delete**: To edit or delete existing subscriptions, click the icon against a dashboard name and select **Edit** or **Delete**.
* **Unsubscibe**: To unsubscribe:
1. Click the icon for the required subscription name, and click **Edit**. The **Subscribe to Dashboard** dialog box appears.
2. In the **Send report to** box, remove the email and click **Update**.

* **View subscribers/unsubscribers**: To view the list of subscribers and unsubscribers, click the dashboard name. An expanded section appears listing the **Subscribers** and **Unsubscribers**.

## Subscription Access and Permissions
The following table describes the roles and permissions for managing subscriptions. For more information about roles and permissions, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
| Action for managing subscription | Role and Access |
| - | - |
| Create Subscription | All user roles that have access to the dashboard can create subscriptions. |
| Edit or Delete Subscription |
All user roles can edit or delete their own created subscriptions.
Only Managers and Administrators can edit or delete subscriptions for other user roles.
|
| Add Users to the Subscription List |
All user roles can add users who are part of the MoEngage workspace to the subscription list.
Only Managers and Administrators can add users who are not part of the MoEngage workspace to the subscription list (the domain must be in the whitelist).
|
# Whitelist Domains
Domain whitelisting helps protect data confidentiality. Administrators and Managers can whitelist email domains that are used to subscribe to the dashboards.

To whitelist a domain:
1. On the left navigation menu in the MoEngage dashboard, click **Settings** > **Reports and Alerts** > **Dashboard subscriptions**.
2. In the upper-right corner, click **Create/Manage** > **Manage Domain Whitelist**.
3. In the **Select email domain names to whitelist** field, type or paste the domains you want to whitelist and press Enter. For example, abc.com
4. Click **Update**. OR, click **Cancel** or **Close** to close the window without adding or updating the domain names.
> [!NOTE]
>
> You can whitelist up to five domains.
# Proactive Insights Settings
Source: https://moengage.com/docs/user-guide/settings/reports-and-alerts/proactive-insights-settings
Customize MoEngage Proactive Insights by configuring RFM insights, key insights preferences, confidence intervals, and analysis duration.
# Overview
You can customize your RFM Insights and Key Insights preferences on the Proactive Insights settings page. You can also adjust the Confidence Interval and Analysis Duration based on your needs. Configuring these settings helps populate accurate data on the **Proactive Insights** page on the MoEngage dashboard. To open the Proactive Insights page, go to the left navigation, select **Analyze**, and then click **Proactive Insights**.


For more information on how this AI-powered assistant works, refer to [Proactive Insights](/docs/user-guide/ai-and-intelligence/proactive-insights).
# Setting Up Proactive Insights
To access the Proactive Insights settings page, navigate to **Settings** > **Reports and alerts** > **Proactive Insights**. The **Proactive Insights settings** page appears.

You can configure the following settings:
* [Key insights](/docs/user-guide/settings/reports-and-alerts/proactive-insights-settings#key-insights)
* [RFM insights](/docs/user-guide/settings/reports-and-alerts/proactive-insights-settings#rfm-insights)
* [Retention insights](/docs/user-guide/settings/reports-and-alerts/proactive-insights-settings#retention-insights)
## Key Insights
The events and revenue attributes that you set up in the **Key Insights** section will be used for Key Metrics analysis. Proactive Insights will provide relevant insight and alerts for any sizable movement of users for DAU and MAU Metrics.

Perform the following steps to set up Key Insights:
1. Specify the **App Open Event**, **Conversion Event**, and **Revenue Attribute** you would like to use for Key Insights.
2. Define the **Deviation interval.** The Deviation Interval is the range around the forecasted value within which the actual value is likely to fall for generating insights. This range can be between 5% to 20%.
3. Set the **Analysis duration** based on your needs.
## RFM Insights
The events and revenue attributes that you set up in the **RFM Insights** section will be used for RFM analysis. Merlin AI will provide relevant insight and alerts for any significant movement of users across the RFM segments.

You can set up to five different RFM Metrics to be used as input to Merlin AI. Perform the following steps to set up RFM Insights:
1. By default, **Recency event** and **Frequency** **event** will be set up as *App/Site Opened.*
2. **Monetary event** will be picked from the **Settings** > **General** > **Goal mapping** > **Revenue attribute** field.
3. These inputs will be analyzed over the duration added in **Analysis duration**. Set the analysis duration based on your needs. It is recommended to be above 7 days for meaningful insights.
## Retention Insights
The events and revenue attributes that you set up in the Retention Insights section will be used for Retention analysis. Merlin AI will provide relevant insight and alerts for anomalies around 7-day, 15-day, and 30-day retention.

Perform the following steps to set up Retention Insights:
1. Specify the **First Event**, **Return Event**, and **Retention type** you would like to use for Retention insights.
2. Specify the **Deviation interval** and **Analysis duration** based on your needs.
Proactive Insights will provide the relevant insight and alerts for any sizable movement of users for D7 and D30 Retention Metrics.
All MoEngage AI products, which were previously referred to as *Sherpa AI*, are now known as *Merlin AI*.
# Behavior Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/behavior/behavior-analysis
Step-by-step guide to Behavior Analysis in MoEngage — define events, apply attribute filters, set date ranges, and choose your chart types.
# Step 1: Define Events
An event refers to any action a user performs on your app that is tracked. Every behavior analysis needs at least one event, and you can add up to 10 events simultaneously.

Each event can be further filtered using **+ Attributes**. Add event filters for specific actions performed by users such as Platform, App Version, and so on.

Use **+ Attributes** again and combine multiple attributes using **AND**/**OR** for each event. For example, use the **OR** filter to combine data across two platforms. If you want to get data for a specific platform and look at the visits to a specific website, use the **AND** filter.

With **Split by**, you can compare the data using a specific attribute. To compare, click **+ Split By** and select the attribute from the list with which you wish to compare. For example, to obtain a chart for the number of songs played across different platforms. Select *product_viewed* as the event and select *Platform* in the **Split By** list. **Split by** shares a combined limit of 10 attributes with the **Group by user property** option in [Step 4](#step-4-select-the-comparison-and-the-duration).

You can add a maximum of 10 events to your behavior chart using **+ Add Event**.
# Step 2: Filter Users
By default, you can perform behavior analysis on all users. However, you can also query for a group of users filtered using User Properties, User Activity, User Affinity, or Custom Segments. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
> [!NOTE]
>
> In Behavior, the **for the first time** operator checks only the events inside the selected date range, so a user who also performed the event before the range still qualifies. Segmentation excludes such users, so the two counts can differ. For more information, refer to [First-Time Event Filters](/docs/user-guide/analyze/analytics-how-to/different-count-in-analytics-and-segmentation#first-time-event-filters).
To compare results across segments instead, use Compare Mode. You can select a maximum of 5 segments. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 3: Choose an Analysis Option
After defining your events, you can choose how to calculate the data. The following options are available:

* **Total events**: This option provides the total count of selected actions or events performed by the user.
* **Unique users**: This option provides the number of distinct users who have completed the selected event.
* **Total events per user**: This option provides an aggregated count of the total events per individual user. For example, you can get the average number of songs played per user. The aggregation types available are shown below:

* **Unique sessions**: This option provides the total number of unique sessions in which the selected event was performed.
* **Aggregation**: This option aggregates the count of the selected event or action. The supported aggregation functions are sum, minimum, maximum, average, median, percentile, and distinct count. The aggregation option is available only for numerical attributes. When you select percentile, enter a value between 1 and 100.

You can aggregate attributes of an event. These attributes are available in the list after selecting your aggregate function type. The available attributes depend on the defined events at the beginning of the analysis.
For more information on advanced Behavior options, refer to [Advanced](/docs/user-guide/analyze/analytics/behavior/advanced-behavior-analysis).
# Step 4: Select the Comparison and the Duration
In addition to the ability to split an event by attributes, you can also group all selected events by a common user property using the **Group by user property** option on the **Behavior Options** tab. For example, you can compare the number of successful orders placed by users of different subscription tiers.

You can select a maximum of 10 attributes, including the **Split by** attributes.\
After choosing the *Group by user property* attributes, specify the duration of the analysis.

# Step 5: Choose Charts
After your query is generated, choose your preferred visualization type. You can change between Line, Area, Bar, Column, and Pie charts. Every chart has its own significance.
* Line charts are widely used for analyzing data trends, changes, or patterns. They are frequently used to display and compare data over time.

Line charts can be viewed in the following ways:

* **Linear**: The chart displays data with a continuous line.
* **Logarithmic**: The chart scales the values on the Y-axis to logarithmic values.
* **Cumulative**: The chart will accumulate all values up to the most recent period shown in the chart.
* Area charts combine a line chart and a bar chart to show how data changes over time. These charts show how one or more groups' numeric values change over time. They are often used to show trends in data, such as the growth of revenue.

* A bar or column chart is a graph used to compare different measures across various data categories or series.
> [tab] Column Chart
>
> 
> [tab] Bar Chart
>
> 
* Pie charts are commonly used to visualize categorical data that can be divided into distinct parts. They display the relative proportions or contributions of various categories within a whole.

Line, area, column, and bar charts are scaled relative to percentages using an absolute number or a percentage. You can switch between numerical and percentage views for line, area, bar, and column charts.

### Granularity
You can also break down the report into Hourly, Daily, Weekly, or Monthly granularities for easy visualization. Based on the granularity you select, unique users will be displayed. Hourly granularity is available for date ranges of up to 31 days.


### Compare to Past
This will allow you to compare the current chart with past trends during behavior analysis. You can compare any data point over a period of time with the corresponding data point from the previous period.

You can compare the chart for the following periods:
* Previous Day
* Previous Week
* Previous Month
* Previous Quarter
* Previous Year
* Custom Range
Time comparison is available only on line, bar, and column charts. You cannot use time comparison and segment comparison together. Segment comparison starts when you add a second segment, so keep a single segment if you want to compare to the past. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).
# Step 6: Tables
In addition to charts, the data is also available for analysis in a tabular format. You can sort the table or change its view using the transpose feature. Additionally, you can download the data in CSV format. For more information, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
When your analysis has a **Split by** attribute or **Group by user property**, you can turn on **Pivot mode** in the table header to see events, attributes, and user properties side by side by date. For more information, see [Pivot Tables](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview#pivot-tables).
# Save to My Studio or Custom Dashboard
Your analysis is now ready. To access this later, you can save the analysis.
To save:
1. Click the icon in the upper-right corner and click **Save to My Studio.**
2. Additionally, you can save the analysis to a custom dashboard. Choose the required option from the list.

3. Select the dashboard where you want to save the analysis. You can choose an existing dashboard or create a new one.

4. Enter a name for your analysis to help you identify.
5. Enter a brief description of the analysis.
6. Click **Save**.
You can access the analysis by navigating to **Analyze** > **My Studio**. To access the custom dashboard, navigate to **Dashboards**.
# Next Steps
* [Advanced](/docs/user-guide/analyze/analytics/behavior/advanced-behavior-analysis)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# Behavior - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/behavior/behavior-overview
Track user interactions across web and mobile with MoEngage Behavior Analysis — monitor events, spot trends, and evaluate campaign impact.

**Behavioural Analytics**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3355142-behavioural-analytics)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Behavior Analysis provides valuable insights into user interactions with your web and mobile applications. By employing this analysis, you can track specific events and assess emerging trends, enabling you to evaluate the effectiveness and performance of your product and marketing campaigns. You can generate graphical charts designed for straightforward visualization and tabular reports intended for in-depth analysis.
# Use Cases
As a marketer or product owner, you can answer the following questions with Behavior Analysis:
* How many Monthly Active Users (MAU) or Daily Active Users (DAU) does my app have?
* Which cities saw the highest number of hotel bookings on my travel app last month?
* How much revenue did I get last month from the latest product I added to my e-commerce app?
* What is the distribution of my users based on the revenue made from their orders?
* How many distinct songs are played across different segments of users?
* What is the average number of orders a user places using my app?
* What is the median number of orders placed by each user by my customers last month?
* How many minutes did the least active listener play over a day, week, or month on my music or video streaming app?
# Getting Started
[YouTube video player](https://www.youtube.com/embed/-NHmUS784iQ)
Getting a Behavior chart follows a workflow similar to other analyses. For a basic overview of performing an analysis, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
We will begin with performing Behavior Analysis in the next section.
# Next Steps
* [Analysis](/docs/user-guide/analyze/analytics/behavior/behavior-analysis)
# Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview
Explore MoEngage analysis types — Behavior, Funnel, Retention, Session and Source, User Paths, and more for data-driven engagement strategies.
MoEngage provides various analysis types suited for different scenarios to evaluate product performance and user interactions with your platform. By utilizing these analysis options, you can implement data-driven customer engagement strategies. The available analysis options include:
* [Users](/docs/user-guide/analyze/analytics/users)
* [Behavior](/docs/user-guide/analyze/analytics/behavior)
* [Funnel](/docs/user-guide/analyze/analytics/funnels)
* [Retention](/docs/user-guide/analyze/analytics/retention)
* [Session and source](/docs/user-guide/analyze/analytics/session-and-source)
* [User paths](/docs/user-guide/analyze/analytics/user-paths)
* [Acquisition](/docs/user-guide/analyze/analytics/acquisition)
* [Uninstalls](/docs/user-guide/analyze/analytics/uninstall)
These tools will help you gather and analyze demographics, preferences, user interactions across various channels, conversion rates, and retention patterns. They will allow you to identify key trends and gain deeper insights into your customer and product needs.
# Getting Started
At a high level, you will follow these standard steps to perform these analyses. While the specifics may vary based on the case and needs, this provides a general overview of the process to be followed.
## Choose Events
Select the events or properties for the analysis, either single or multiple. Choose those that will provide the most value for your analysis. These should generally be relevant to your users and app/website.

## Define Attributes
Select relevant attributes for your event. Attributes provide context for the events you choose, allowing you to filter specific actions or events further.

## Choose Users
Identify the users on whom you want to perform this analysis. These are the individuals who have completed the set of events that you have selected. For more information, refer to [Segmentation](/docs/user-guide/segment/create-segments/rule-based-filter-segments).

## Analysis Options and Duration
MoEngage offers options for count-level and aggregated analysis. These options vary depending on the type of analysis. You will learn more about these options in the analysis types.
After selecting the analysis option, you will specify the duration for which you wish to run the analysis.
## Charts
Charts are the results obtained at the end of an analysis. They visually represent data, making it easier to understand large quantities and their relationships with different data. Each analysis type offers different ways to visualize your query. To give you a general overview, the types of visualization options available are:
* Line
* Bar
* Column
* Area
* Pie
* Choropleth
You can visualize the results in Numerical and Percentage views.

## Tables
With charts, the data is also presented in tabular form, arranged in rows and columns. Tables are useful for locating specific information and identifying patterns.
You can adjust how each table looks and what it shows—resize and reorder columns, sort and filter values, pin the columns you care about, and download the current view—without rerunning your query. These table controls are available across Behavior, Funnels, Retention, Session & Source, User Analysis, and Custom Dashboards.
> [!NOTE]
>
> Sorting, filtering, and other column actions only change how the table is displayed. They do not change the underlying query or the chart above the table.
### Transpose Table
You can transpose the table. This allows you to view and download the table in your preferred format by shifting its vertical and horizontal orientation.

### Sorting and Calculation
You can organize the data in the table without external tools. Click the header of any column to sort the table data. Sorting is available on every column.
* The first click sorts in ascending order, the second click sorts in descending order, and the third click resets the column to its default order.
* To sort by more than one column, hold **Shift** and click additional column headers. The table applies the sorts in the order you click them.
* You can also open the column menu (the three-dot icon in the column header) and select **Sort Ascending** or **Sort Descending**.
Along with sorting, you can choose the calculation type from the list in the column.
* Sum
* Median
* Average
* Min
* Max
For tables with multiple events, you can sort the calculation by clicking the header of the calculation type. This will sort the data in ascending or descending order. In the transpose view, the calculation type row remains fixed while the columns are sortable.

### Resize Columns
Drag the divider between two column headers to make a column wider or narrower. Each column has a minimum and maximum width, so content stays readable. To fit a column to its content automatically, open the column menu (the three-dot icon in the column header) and select **Autosize This Column** or **Autosize All Columns**. When you resize the browser window, the table adjusts to fit the available space.

### Filter
You can narrow the rows shown in a table without changing your query.
* **Column filters:** Click the filter (funnel) icon in a column header to keep only the rows that match a condition. For text columns, the available operators are **Contains**, **Does not contain**, **Equals**, **Does not equal**, **Begins with**, **Ends with**, **Blank**, and **Not blank**. You can combine two conditions with **AND** or **OR**, and apply filters on more than one column at the same time.
* **Quick search:** Use the **Search across all columns** box above the table to find a value across all rows and columns at once. The table updates as you type to show only matching rows.
* **Advanced filters:** For more complex conditions, open the **Filters** tab on the right sidebar to assemble multiple conditions into a single filter expression.

### Pin, Reorder, and Choose Columns
* **Pin:** To keep a column visible while you scroll horizontally, open the column menu (the three-dot icon in the column header), select **Pin Column**, and choose **Pin Left** or **Pin Right**. Select **No Pin** to unpin. You can also drag a column into or out of a pinned section.
* **Reorder:** Drag a column header left or right to change the order of columns.
* **Choose columns:** Open the column menu and select **Choose Columns** to show or hide columns, or use the **Columns** tab on the right sidebar. Select **Reset Columns** to restore the default layout.

### Download the Table
To share or analyze the table elsewhere, click **Download Table** at the top of the table and choose **Download as CSV** or **Download as Excel**. The download reflects the table's current state, including any filters you applied and the sort order you set, and includes all columns.

### Tooltips and Copy
When a cell value or column header is too long to fit, the full text appears in a tooltip when you hover over it. Values that already fit do not show a tooltip. You can also select one or more cells and copy them to your clipboard—the copied text keeps the order in which you selected the cells.
### Pagination and Infinite Scroll
How a table loads rows depends on where you view it. On the analysis pages (Behavior, Funnels, Retention, Session & Source, and User Analysis), tables are paginated: a **Page Size** selector controls how many rows appear per page, a row count shows the current range (for example, 1 to 38 of 38), and page controls let you move between pages. On Custom Dashboards, tables use infinite scroll, loading more rows as you scroll down.
### Pivot Tables
> [!NOTE]
>
> This feature is only available in the Product Analytics package of MoEngage Analytics. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
See your events and attributes side by side in MoEngage, without exporting the table to Excel. In pivot mode, you drag the table's columns into rows, columns, and values, and choose how the numbers add up. Your pivot always reflects the data you were already looking at: the same events, filters, and date range.
Pivot mode helps most when your analysis has several events or split-by attributes. The standard table shows one row for every combination of event and attribute value, which gets hard to compare as the combinations grow. In pivot mode, you decide what goes in the rows and what sits side by side in the columns.
> [!TIP]
>
> **Before You Start**
>
> * Open a [Behavior](/docs/user-guide/analyze/analytics/behavior/behavior-analysis) or [Session and Source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-analysis) analysis.
> * Split or group your data by at least one attribute, such as **Platform** or **City**. In Behavior, use **Split by** or **Group by user property**. In Session and Source, select a source property.
>
> If the **Pivot mode** toggle is disabled, check that the table isn't transposed and that your analysis type supports pivot. For more information, see [Where Pivot Is Available](#where-pivot-is-available).
#### Turn On Pivot Mode
**1. Run the Analysis**
Set up your Behavior or Session and Source analysis with at least one attribute to split or group by, and click **Apply**.
**2. Turn On Pivot Mode**
In the table header, next to **Transpose** and **Download Table**, turn on the **Pivot mode** toggle. The table opens empty, with the message *Drag fields into Row Groups and Column Labels to build your Pivot*, and the **Columns** sidebar opens on the right.
**3. Build the Layout**
Drag columns into **Row Groups**, **Values**, and **Column Labels**. For more information, see [Build a Pivot Table](#build-a-pivot-table).
> [!TIP]
>
> Pivot rearranges the data you're already seeing. It doesn't fetch any new data, so you can try different layouts without rerunning the analysis.
To return to the standard table, turn off the **Pivot mode** toggle. If you change the analysis and click **Apply** again, pivot mode turns off and your layout is cleared, so you need to build it again.
#### Build a Pivot Table
A pivot has three parts:
* **Rows** are what you're comparing, such as platforms.
* **Columns** are what you want side by side, such as events.
* **Values** are the numbers you're comparing, such as daily counts.
The **Columns** sidebar lists the columns of the standard table that you can use:
* **Events**, which holds the event names. This column appears in Behavior only.
* One column for each split-by attribute, group-by user property, or source property in the analysis.
* One column for each date in the analysis duration, at the analysis granularity. For example, a daily analysis from 17 Sep 2026 to 24 Sep 2026 lists one column for each of those eight days. A weekly analysis lists one column per week.
Drag each column into the zone where you want it. To place a column faster, select its checkbox instead: attributes go to **Row Groups** and dates go to **Values**. To remove a column, click its **X**.

| Zone | What it does | Example |
| :- | :- | :- |
| **Row Groups** | Groups rows by the values of the column. Add more than one column to nest groups, in the order shown in the bar above the table. | Add **Platform** to get one row each for Android, iOS, and Web. |
| **Values** | Sets the numbers shown in the table. Each date column you add becomes a column in the pivot. Add only the dates you want to compare. | Add the three most recent dates to compare the last three days. |
| **Column Labels** | Adds a column group for each value of the column. Each group holds the date columns from **Values** and a **Total** column. Use an attribute with a short list of values, such as a text or true or false attribute. | Add **Events** to get one column group per event. |
> [!NOTE]
>
> Integer, float, array, and object attributes can't be used as column labels, because each unique value would become its own column. You can still add them to **Row Groups**.
**Tips**
* Pivot tables start collapsed, so you see only totals at first. To see the numbers by day, click the arrow next to a group name in the table header. Click it again to collapse the group.
* When you nest row groups, click the arrow next to a row group to show or hide the rows under it.
* The **Total** row at the bottom of the table aggregates each column across all rows.

##### Change the Pivot Aggregation
Each column in **Values** shows its aggregation function and name, for example **sum(17 Sep 2026)**. Values use **sum** by default. To change it, click the column in **Values** and select one of these functions:
| Function | What each group shows |
| :- | :- |
| **sum** | The total of the values in the group. |
| **avg** | The average of the values in the group. |
| **min** | The smallest value in the group. |
| **max** | The largest value in the group. |
| **count** | The number of rows in the group. |
| **first** | The value of the first row in the group. |
| **last** | The value of the last row in the group. |

The column headers in the table show only the column name, such as the date, and don't include the function name.
#### Example: Compare Carts and Orders by Platform
An ecommerce team wants to know whether shoppers on each platform turn their carts into orders at the same rate.
In Behavior, the team adds two events, **Add to Cart** and **Order Placed**, splits each by **Platform**, chooses **Total events**, and runs the analysis daily from 22 Sep 2026 to 24 Sep 2026. The standard table has one row for every event and platform combination, so comparing carts to orders on the same platform means jumping between rows:
| Events | Platform | Average | 22 Sep 2026 | 23 Sep 2026 | 24 Sep 2026 |
| :- | :- | -: | -: | -: | -: |
| Add to Cart | Android | 1,350 | 1,200 | 1,350 | 1,500 |
| Add to Cart | iOS | 840 | 800 | 820 | 900 |
| Add to Cart | Web | 600 | 600 | 550 | 650 |
| Order Placed | Android | 340 | 310 | 320 | 390 |
| Order Placed | iOS | 255 | 240 | 255 | 270 |
| Order Placed | Web | 90 | 90 | 80 | 100 |
To put carts and orders side by side, the team turns on **Pivot mode** and builds this layout:
1. Drag **Platform** into **Row Groups**.
2. Drag **Events** into **Column Labels**.
3. Drag **22 Sep 2026**, **23 Sep 2026**, and **24 Sep 2026** into **Values**, and keep the function as **sum**.
The pivot now has one row per platform and one column group per event. With both groups expanded, the table looks like this:
| Group | Add to Cart: 22 Sep | Add to Cart: 23 Sep | Add to Cart: 24 Sep | Add to Cart: Total | Order Placed: 22 Sep | Order Placed: 23 Sep | Order Placed: 24 Sep | Order Placed: Total |
| :- | -: | -: | -: | -: | -: | -: | -: | -: |
| Android | 1,200 | 1,350 | 1,500 | 4,050 | 310 | 320 | 390 | 1,020 |
| iOS | 800 | 820 | 900 | 2,520 | 240 | 255 | 270 | 765 |
| Web | 600 | 550 | 650 | 1,800 | 90 | 80 | 100 | 270 |
| **Total** | 2,600 | 2,720 | 3,050 | 8,370 | 640 | 655 | 760 | 2,055 |
The gap is now easy to read. On 22 Sep 2026, web shoppers placed about one order for every seven carts, compared with about one in four on Android and nearly one in three on iOS. The same pattern holds on every date, which points to a web checkout problem rather than a one-day dip. With both groups collapsed, the two **Total** columns give the same comparison for the whole period: 270 orders from 1,800 carts on web, against 1,020 from 4,050 on Android. The **Total** row gives the carts and orders across all platforms.
The team can reshape the pivot to answer follow-up questions:
* **Compare platforms for each event:** Move **Events** to **Row Groups** and **Platform** to **Column Labels**. Each event becomes a row, and the platforms sit side by side under each date.
* **Find where the gap comes from:** Add **City** as a **Group by user property** and click **Apply**. Turn on **Pivot mode** again, rebuild the layout, and drag **City** into **Row Groups** below **Platform**. Expand **Web** to see which cities have the lowest orders for their carts, and collapse it to return to the platform view.
For more examples across industries, see [How to Use Pivot Tables to Answer Common Business Questions](/docs/use-cases/analytics/how-to-use-pivot-tables-to-answer-common-business-questions).
#### Download and Pin a Pivot Table
To share your pivot, download it or pin it to a dashboard:
* **Download:** Click **Download Table** and choose **Download as CSV** or **Download as Excel** to export the table in its pivoted shape. In the Excel file, grouped column headers are kept as merged header rows. For more information, see [Download the Table](#download-the-table).
* **Pin to a dashboard:** Pin the table to a [custom dashboard](/docs/user-guide/analyze/dashboards/custom-dashboards). The dashboard widget shows the pivot layout as it was when you pinned it. You can't edit the layout from the dashboard, and the widget doesn't show the **Pivot mode** toggle. To change the layout, edit the pivot in the source analysis and pin it again.
#### Where Pivot Is Available
You can use pivot mode in Behavior and Session and Source analyses. It isn't available in Funnels, Retention, User Paths, or User Analysis.
Pivot works best for counts and totals. It isn't available for medians, percentiles, or ratio metrics such as bounce rate, because combining those numbers again gives misleading results. For these analysis types, the toggle is disabled, and its tooltip explains why. For example, a median shows *Pivot is not available for median or percentile aggregation*, and a ratio report shows *Pivot is not available for a derived ratio metric like this report type*.
> [tab] Behavior
>
> | Analysis type | Pivot available |
> | :- | :- |
> | Total events | Yes, when a split-by attribute or group-by user property is set. |
> | Unique users | Yes, when a split-by attribute or group-by user property is set. |
> | Unique sessions | Yes, when a split-by attribute or group-by user property is set. |
> | Aggregation with sum, minimum, maximum, average, or distinct count | Yes, when a split-by attribute or group-by user property is set. |
> | Aggregation with median or percentile | No. |
> | Total events per user with sum, average, minimum, maximum, or count | Yes, when a split-by attribute or group-by user property is set. |
> | Total events per user with median or percentile | No. |
> | Aggregation distribution | No. |
> | Attribute aggregation per user | No. |
> [tab] Session and Source
>
> | Report type | Pivot available |
> | :- | :- |
> | Session count | Yes, when a source property is selected. |
> | Conversion Count | Yes, when a source property is selected. |
> | Revenue | Yes, when a source property is selected. |
> | Avg. Session Duration | No. |
> | Avg. Sessions / User | No. |
> | Avg. Conversions/Session | No. |
> | Bounce Rate | No. |
#### Pivot Limitations
* You can't add custom calculated fields to a pivot.
* You can't edit a pivot from a dashboard widget. To change it, edit the pivot in the source analysis and pin it again.
# Next Steps
* [How to Use Pivot Tables to Answer Common Business Questions](/docs/use-cases/analytics/how-to-use-pivot-tables-to-answer-common-business-questions)
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [Behavior Analysis](/docs/user-guide/analyze/analytics/behavior/behavior-analysis)
# Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/users/analysis
Analyze user properties in MoEngage — filter by location, device type, language, and other attributes to understand audience demographics.
# Step 1: Define User Property
User properties store information about individuals, including personal details such as name, birthdate, address, and location. They also include unique identifiers like mobile numbers, ID numbers, email addresses, device IDs, and user preferences. You can select multiple user properties to start your analysis. To learn more about the properties, refer to [Derived User Properties](/docs/user-guide/data/user-data/derived-user-attributes).

You can filter each selected user property by assigning attributes. After choosing the user property, click **+ Filters** to add attributes. Adding filters will exclude unwanted data for your analysis. You can apply multiple filters using **AND**/**OR**, as demonstrated below:

You can add up to 5 user properties for your analysis using **+ Add user property**. Every analysis needs at least 1 user property.

Duplicate the added property by clicking the **Duplicate step** icon in the right corner.

# Step 2: Filter Users
By default, you can perform user analysis on all users. However, you can also query for a group of users filtered using User Properties, User Activity, User Affinity or Custom Segments. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).

# Step 3: Choose an Analysis Option
After defining your users, you can choose how to calculate the data. The following options are available:

* **Total count**: This option provides the total count of available values for the selected user property.\
For example, with total count analysis, you can determine how many users have purchased or added a product to their carts within a specific city or group of cities.
* **Unique count**: This option provides the unique count of available values for the selected user property.\
For example, you can identify the number of unique products purchased by users over a specific period in a given geography or demographic.
* **Distribution**: This option provides distribution for the selected user property. In a simple way, this is a self-split of data.

You can also configure **Custom** **Distribution bucketing**. With custom distribution, you will enter the boundaries in the **From** and **to** fields (the lower and upper limits) and an interval size to divide each distribution. This option is available only for numerical properties. Choose boundaries and an interval that produce a maximum of 10 buckets.

For example, you can use distribution to identify users who would qualify for a specific credit card product or an add-on service based on different spending habits.
* **Aggregation**: This option aggregates the count of the selected user property. The supported aggregation functions are sum, minimum, maximum, average, median, percentile, and distinct count. The aggregation option is available only for numerical attributes. When you select percentile, enter a value between 1 and 100.

For example, aggregation can be used to calculate the average screen-on duration of users on your platform.
* **Email domain analysis**: This option provides domain-specific visualization based on the standard email attribute. The email domain is the part after @, for example, gmail.com, yahoo.com, etc.

For example, consider a bank that wants to analyze its user base using the domains of its users. By performing Email Domain analysis, they can see the number of spam complaints and bounces bucketed on a domain basis.
# Step 4: Choose a Split
The **Split by** option allows you to group and compare the data in a report based on a specific attribute. You can add a maximum of 10 attributes.

For example, you can see the data of users on Android OS in different cities. Here, Android OS is the User property, and the **Split by** condition is their *Last known city*.
# Step 5: Choose Charts
After your query is generated, choose your preferred visualization type. You can change between Line, Bar, Column, and Pie charts. Every chart holds its own significance.
* Line charts are widely used for analyzing data trends, changes, or patterns. They are frequently used to display and compare data over time.

* Bar and column charts present aggregated data, such as sales figures for various products, population comparisons of different cities, or analysis of survey responses across different categories.
> [tab] Column Chart
>
> 
> [tab] Bar Chart
>
> 
* Pie charts are commonly used to visualize categorical data that can be divided into distinct parts. They are helpful for displaying the relative proportions or contributions of various categories within a whole.

* Choropleth charts offer a quick and easy way to visually represent the distribution of attributes or variables geographically and help identify patterns or disparities among different regions.

This chart is available only if the **Split by** condition is *Last known country*.
You can switch between Numerical and Percentage views for Line, Bar, and Column charts.

# Step 6: Tables
In addition to charts, the data is also available for analysis in a tabular format. You can sort the table or change its view using the transpose feature. Additionally, you can download the data in CSV format. For more information, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
# Save to My Studio or Custom Dashboard
Your analysis is now ready. To access this later, you can save the analysis.
To save:
1. Click the icon in the upper-right corner and click **Save to My Studio.**
2. Additionally, you can save the analysis to a custom dashboard. Choose the required option from the list.

3. Select the dashboard where you want to save the analysis. You can choose an existing dashboard or create a new one.

4. Enter a name for your analysis to help you identify.
5. Enter a brief description of the analysis.
6. Click **Save**.
You can access the analysis by navigating to **Analyze** > **My Studio**. To access the custom dashboard, navigate to **Dashboards**.
# Next Steps
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
* [Dashboards](/docs/user-guide/analyze/dashboards)
# Users - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/users/users-overview
Study user properties and demographics with MoEngage User Analysis — identify trends, personalize experiences, and target specific segments.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
User Analysis enables you to analyze users and attributes that define the user groups within your overall user base. This analysis helps you identify trends about your users, such as the number of your users from a specific location and their language preferences. User analysis is helpful in personalizing user experiences, targeting specific audiences, and tailoring content, services, or products to individual needs or preferences.
## Use Cases
Some of the questions User Analysis will help you answer:
* How to analyze user preferences on different devices using device types and conversion rates
* How to identify regional spending patterns using the user location and average order value
* How to analyze the number of unique users who have abandoned checkout grouped by platform or device
* How to analyze the total number of users who have purchased in a store based on device-triggered push notifications
* How to identify the number of users who have engaged with emails in a specified domain
# Getting Started
[Loom video player](https://www.loom.com/embed/987c01f8c3dd49a9ba7611781cf72059)
User analysis follows a similar workflow to other analyses. For a basic overview of performing an analysis, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
We will begin with performing User Analysis in the next section.
# Next Step
* [Analysis](/docs/user-guide/analyze/analytics/users/analysis)
# Overview
Source: https://moengage.com/docs/user-guide/analyze/moengage-analytics/overview
Get started with MoEngage Analytics — an insights-led tool for analyzing user behavior, journeys, and product usage with visual reports.
MoEngage Analytics is an insights-led analytics tool that helps you gather data about your customers and products. It allows you to analyze user behavior, journey, and product usage deeply. You can visualize the analysis with charts and tables, which helps you make informed and data-driven decisions.
# Basics
The following are some important terms (building blocks) to know before you start your first analysis:
## Events
An event refers to any action taken by a user on your platform and specific occurrences that may happen within it. These events can vary depending on the type of platform.
For example, a purchase on an e-commerce platform is an event. A sign-up on an OTT platform could be an event.
## Attributes
### Event Properties
An event property is the extra information that describes an event.
For example, cart value is an attribute that could define a product purchase, and location can be associated with a sign-up event.
### User Properties
These are the pieces of information associated with a user.
For example, the first seen event on an app is considered a user property. User demographics, such as the city, are another example.
## Users
These are the individuals who have interacted with your platform to perform the event.
For more information, refer to [Data](/docs/user-guide/data).
With these basic building blocks, you can now start building your first chart. Let us begin with performing an analysis.
# Next Steps
* [Getting Started](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview)
* [User Analysis](/docs/user-guide/analyze/analytics/users/analysis)
# Computed Traits - Overview
Source: https://moengage.com/docs/user-guide/data/computed-traits/computed-traits-overview
Computed traits are dynamic user properties auto-calculated from event data. Build richer profiles for segmentation without any coding work.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Computed traits are dynamic user properties that you can create by applying calculations and transformations to the existing event data you collect in MoEngage. Think of them as smart, custom-built user properties that get automatically updated based on user behavior.
Instead of relying on developers to track a specific attribute like *Lifetime Value* (LTV) or manually uploading CSV files, you can create a computed trait that automatically calculates this attribute based on user behavior. This allows you to build richer, more accurate user profiles and unlock deeper segmentation and personalization opportunities.

> [!NOTE]
>
> A workspace can have up to 10 active computed traits at any given time. This includes traits with **Scheduled**, **Processing**, or **Active** status. Paused traits do not count toward this limit. To increase this limit, contact your MoEngage CSM or the Support team.
>
> A workspace can hold up to 50 computed traits in total, including paused ones. Because you cannot delete a trait, create only the traits you intend to use.
# Use Cases
Computed traits help you move beyond static user data and engage users based on their real-time activities and preferences. Here are some use cases:
* **Hyper-personalization:** Tailor campaigns with dynamic values like a user's total savings or loyalty points to create highly relevant messages that boost engagement and drive conversions.
* **Advanced segmentation:** Create highly specific segments, such as "power users" or "at-risk customers," to run targeted campaigns that improve user retention and increase LTV.
* **Automate data enrichment:** Automatically calculate and store key metrics like a user's favorite product category, eliminating manual work and ensuring your campaigns are always based on the latest user data, which improves campaign efficiency and relevance.
## Use Cases by Industry
For ready-to-build traits tailored to your industry, explore these references. Each lists the computation method, data source, and business use case for every trait:
* [Banking, Financial Services, and Insurance](/docs/use-cases/computed-traits/computed-traits-for-bfsi)
* [E-commerce](/docs/use-cases/computed-traits/computed-traits-for-e-commerce)
* [Telecom](/docs/use-cases/computed-traits/computed-traits-for-telecom)
* [Media and Entertainment](/docs/use-cases/computed-traits/computed-traits-for-media-and-entertainment)
* [Retail](/docs/use-cases/computed-traits/computed-traits-for-retail)
* [Content Streaming](/docs/use-cases/computed-traits/computed-traits-for-content-streaming)
# Methods of Computations
You can create computed traits using several methods:

## Count, Aggregation, and First/Last Value
These methods allow you to create a computed trait by performing calculations on event data over a specific time period.
* **Count:** Counts the number of times a user has performed an event.
* **Aggregation:** Calculates the sum, average, minimum, or maximum value of an event property.
* **First/Last value:** Identifies the first or last recorded value of an event property for a user.
## Use Cases
* **Count:** Create a *Total Orders in Last 90 Days* trait by using **Count** on your *Order Placed* event. Use this to identify and reward frequent shoppers.
* **Aggregation (Sum):** Calculate a *Total Amount Invested* trait by using **Sum** on the "amount" attribute of your *Investment Successful* event. This helps you segment users into different investment tiers.
* **Aggregation (Count Distinct):** Create a *Distinct Genres Watched* trait by using **Count Distinct** on the *genre* attribute of your *Video Played* event. This helps you understand a user's content preferences for better recommendations.
* **First/Last Value:** Identify a user's *First Played Song Genre* with the **First Value** computation on the *genre* attribute of the *Song Played* event to understand their initial interests.
## SQL Compute
For more complex calculations, you can use **SQL** (Structured Query Language) to define your computed trait. This gives you the flexibility to combine multiple events and user properties, create conditional logic, and define sophisticated metrics.
## Use Cases
* Create a *Lead Score* trait. Write a SQL query to count user engagement events, like Page View. Based on the count, use conditional logic to set a user property to "Strong" (for example, if page view count > 20) or "Weak" (for example, if page view count > 10), helping sales teams prioritize leads.
* Create a *High-Value Churn Risk* trait. Write a SQL query to find users who have spent over \$500 in their lifetime but haven't made a purchase in the last 60 days.
* Define a *Loan Pre-Qualified* trait. Use SQL to check if a user has completed key application events (for example, *Viewed Loan Offer*, *Submitted Documents*) and meets certain user property criteria (for example, *Credit Score 700*).
* Identify *Artist Super Fans* with a SQL query that counts the number of times a user has played songs from a specific artist and also registered for that artist's virtual concert event.
* Create a *Binge Watcher* trait by writing a SQL query to identify users who have watched three or more episodes of the same series within a 24-hour window.
# Computed Traits in a Multi-Project Portfolio
If your workspace uses [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio), computed traits work across every project in that workspace.
* **You can define a trait using data from any project.** When you configure the computation, the event and attribute lists show the combined set of events and attributes from all projects in the workspace. You can build a trait on an event that only one project tracks.
* **Each trait is created as a global user property.** After the computation runs, the trait is available in every project and at the portfolio level. In the segment builder, select any project under **User property**, and the trait appears without a project name suffix. So there is no targeting restriction: you can build a trait from the events of one project and use it to target users in another project.
* **You cannot scope a trait to a single project.** Every trait you create is visible to everyone working in any project in the workspace. Name your traits so that the source of the value is clear, for example *Grocery App Lifetime Value*, and teams working in other projects know what the trait measures.
For more information on how project and portfolio selection works in the segment builder, refer to [Segmentation in a Multi-Project Portfolio](/docs/user-guide/segment/advanced-concepts/segmentation-in-a-multi-project-portfolio).
# Things to Know
Keep the following in mind when you plan your computed traits:
* **Traits are calculated on a schedule, not in real time.** A trait's value is written to user profiles when its computation runs, so a new value is not available until the next scheduled run. For the available frequencies, refer to [Scheduling](/docs/user-guide/data/computed-traits/create-a-computed-trait#step-3-scheduling).
* **Each trait creates a user property.** The attribute counts toward the unique user property quota for your workspace. For more information, refer to [Data Tracking Policies](/docs/user-guide/data/key-concepts/data-tracking-policies).
* **Send standard profile attributes through your SDK or the API.** For fields such as First Name and Last Name, use your SDK integration or the [Track User API](/docs/api/user/track-user) so that the value is available on the user's profile as soon as you send it. Use computed traits for derived and behavioral attributes, such as lifetime value or favorite category.
* **To personalize a message with the event that triggered it, use event properties.** Event property personalization reads from the triggering event, so you do not need to wait for a computation to run. For more information, refer to [Event Properties](/docs/user-guide/campaigns-and-channels/getting-started/message-personalization/overview#event-properties).
# Next Steps
* [Create a Computed Trait](/docs/user-guide/data/computed-traits/create-a-computed-trait)
# Create a Computed Trait
Source: https://moengage.com/docs/user-guide/data/computed-traits/create-a-computed-trait
Step-by-step guide to creating computed traits in MoEngage using count, aggregation, first/last value, or SQL computation methods.
This article guides you through creating a new computed trait, managing existing computations, and using them to enhance your campaigns.
# Create
To get started, perform the following steps:
1. On the sidebar menu in MoEngage, hover over the **Data** menu item  . The **Data** menu appears.
2. Click **Computed traits**.

3. Click **+ Create Computed trait**. The **Create computation** dialog box appears. 
4. Click the desired computation method. You have the following options:
* **Count**
* **Aggregation**
* **First/Last Value**
* **SQL Computation**
For more information on methods of computation and their use cases, refer to [Computed Traits - Overview](/docs/user-guide/data/computed-traits/computed-traits-overview).
The process includes three steps:
* [Step 1: Basic Details](/docs/user-guide/data/computed-traits/create-a-computed-trait#step-1-basic-details)
* [Step 2: Define Computed Trait](/docs/user-guide/data/computed-traits/create-a-computed-trait#step-2-define-computed-trait)
* [Step 3: Scheduling](/docs/user-guide/data/computed-traits/create-a-computed-trait#step-3-scheduling)
## Step 1: Basic Details
First, define the basic details and specify which users the computation applies to.
1. **Computed trait name:** Enter a unique name for your computation. This name will appear as a new user property across the MoEngage UI (for example, "Lifetime Value").
2. **Description:** Briefly explain what the computation calculates for your team's reference.

3. **Filter users:** Choose the users to be part of the computation. You can select:
* **All users:** The computation will run for every user in your account.
* **Filter users by:** Define a specific segment of users based on user properties, events, or affinities. For more information, refer to [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).

## Step 2: Define Computed Trait
Next, define the logic for how your trait will be calculated.
1. **Select the Type:** In the **Type** section, choose the desired type of computation. You can create traits based on:

* **Count:** Count the number of times users performed an action.
* **Aggregation:** Aggregate values of an event property (for example, Total order value).
* **First/Last Value:** Identify the first or last value of an event property.
* **SQL Computation:** Write a custom SQL query for complex calculations.
2. **Set up the Configuration:** In the **Configuration** section, based on the type of computation that you selected, do the following:
* For a **Count** computation, select the event to count, define the time period, and optionally add attribute filters.

* For an **Aggregation** computation, select the event and the time period. Then, choose the aggregation function. The following functions are available: **Sum**, Min, Max, Average, Median, Distinct count, and **True if event exists**. After selecting the function, select the event property you want to compute.

* For a **First/Last Value** computation, select the event and time period. Then, choose whether to compute the **First value** or **Last value** of a specific event property.

* For a **SQL Computation**, in the SQL editor, write your query. You can use the left section to browse and select user and event tables. Your query must return two columns: the MoEngage ID and the computed value for your new trait.

3. **Define the Data type:** Choose the data type of the computed trait's output (for example, **Numerical**, **String**, **Boolean**). Defining a data type is only permitted when you select **SQL** as the computation type. For other computation types, the data type is auto-populated.
4. **Review the Summary:** A plain-language summary of your configuration will be displayed for confirmation.

5. **Preview the trait:** Before navigating to the next step, you must test the logic. Perform these steps to preview:
1. In the **Preview Computed Trait** section, select a preview type.
* **A specific user**: Test the configuration on a specific user ID.
* **A set of 10 random users**: Test the configuration on a set of ten random users.
2. Click **Preview**. A table is generated with ID and computed value.

You can export this preview. To do so, click **Download**.
## Step 3: Scheduling
Finally, decide how and when your computation should run. Perform the following steps to schedule and publish your computed trait.
1. In the **Schedule section**, select when the computation will execute.
* In the **One-time** section, select **Run at next schedule** to run the computation once at the next scheduled time.\
or
* In the **Periodic section**, select the computation to run repeatedly on a **Weekly** or **Monthly** basis to keep the user property updated. You can adjust the schedule from the **Settings** page.

> [!NOTE]
>
> Computations can also be scheduled to run at a **daily** frequency. To enable daily scheduling for your account, contact your account manager.
2. For **Periodic** computations, choose how to handle existing values for users. Select one of the following in the **Computation action**:

* **Replace:** Overwrites the old value with the new one for users who meet the computation definition. If a user no longer meets the definition, their existing value is retained.
* **Compute only for new users:** Calculates the value only for users who do not already have a value for this trait.
* **Add to existing value:** Adds the newly computed value to the user's current value.
* **Subtract from existing value:** Subtracts the newly computed value from the user's current value.
Once you are done, click **Publish** to create your computed trait.
# Manage Your Computations
The Computed Traits page lists all the computations you have created.
### Navigation
1. After creating the computed trait, navigate to **Data** > **Computed traits**. The Computed traits page appears.

On this page, you can:
* Use the search box to search for a computed trait.
* See information like **Type**, **Schedule**, and **Status**.
* Use the filters in the header to filter the created computed traits by type, schedule, or status.
2. For a computed trait, you can edit, pause, or view the computation. To do so, click the ellipsis icon against a name and select the desired option.

* * **View:** See the detailed configuration of a computation on a new page. Alternatively, you can access the detail page by clicking the trait name.

The detail page contains the following information:
* **Basic details**: This section contains information on when the computed trait was created, the scheduled details, last run and next run timestamps, and the filtered users' details.
* **Computation type**: This section contains information about the type of computation and its configuration.
* **Run history**: This section provides a detailed view of the computation history.
* **Pause/Resume**: Pause the computation, or resume a paused computation. Pausing a computation releases its slot in the active-computation limit.
* **Edit:** Modify a computation. You can only make changes before its first scheduled run. After the first run, only the schedule can be changed.
> [!NOTE]
>
> You cannot delete a computed trait. To stop a trait from running, pause it.
>
> To change the logic of a trait that has already run, create a new trait with the updated configuration and pause the original. Recomputing a trait with different logic would change the values that live segments and campaigns already depend on.
> [!NOTE]
>
> * You can have a maximum of ten active computations at any given time. This includes computations with Scheduled, Processing, or Active statuses. Paused computations do not count toward this limit.
> * A workspace can hold up to 50 computations in total, including paused ones.
> * Computed trait values are applied to user properties at a processing speed of up to 1 million users per hour.
# Use Your Computed Traits
Once your computation has run successfully, the new trait will be available as a standard user property throughout MoEngage.
* **In Segmentation:** In the segment creator, go to **User Property**, find your new computed trait by name, and use it to build your segment.
* **In campaign personalization:** Use Jinja to insert the trait's value directly into your messages. For example: `Hi {{UserAttribute['First Name']}}, you have {{UserAttribute['Loyalty Points']}} points!`. Alternatively, use @ to add the attribute to your content.
* **In Flows:** Use the computed trait as a condition to guide users down different paths in a flow.
> [!NOTE]
>
> In a workspace with multiple projects, a computed trait is created as a global user property. It appears under **User property** for every project, regardless of which project's events you built it from. For more information, refer to [Computed Traits in a Multi-Project Portfolio](/docs/user-guide/data/computed-traits/computed-traits-overview#computed-traits-in-a-multi-project-portfolio).
# A Complete Guide to Event Tracking
Source: https://moengage.com/docs/user-guide/data/event-data/a-complete-guide-to-event-tracking
Master event tracking in MoEngage. Monitor user actions, behaviors, and transactions across websites and mobile apps to optimize marketing strategies.
# Introduction to Event Tracking
Event tracking is a fundamental aspect of modern marketing and analytics that allows businesses to monitor and analyze specific actions or occurrences (events) within their digital properties, such as websites, mobile apps, and online platforms. These events represent significant interactions, behaviors, or transactions that users perform while engaging with a brand's digital assets.
By tracking these events, businesses can gain valuable insights into user behavior, preferences, and engagement patterns, enabling them to optimize their marketing strategies, improve user experiences, and drive business growth.
# What is Event Tracking?
Event tracking involves the systematic capture, recording, and analysis of user interactions or actions within a digital environment. These interactions can range from clicking on a button, submitting a form, viewing a page, making a purchase, to more complex behaviors such as scrolling, hovering, or watching a video. Each event is defined and tracked using specific parameters or properties that provide additional context and detail about the event, such as the event name, timestamp, user ID, and any relevant metadata.
For example, in an eCommerce context, event tracking may involve monitoring events such as product views, add-to-cart actions, checkout initiations, and purchases. In a mobile app, event tracking could include events like app launches, in-app purchases, feature interactions, and app uninstallations.
By capturing and analyzing these events, businesses can gain insights into user engagement, conversion funnels, user journeys, and product performance, which can inform marketing strategies, product enhancements, and user experience optimizations.
## Importance of Event Tracking in Marketing
Event tracking plays a crucial role in modern marketing for several reasons:
1. **Granular Insights:** Event tracking provides granular insights into user behavior and interactions, allowing businesses to understand how users engage with their digital properties at a detailed level. This enables marketers to identify trends, patterns, and opportunities for optimization.
2. **Personalization:** By tracking user events, businesses can create personalized experiences tailored to individual user preferences and behaviors. This includes delivering targeted messages, recommendations, and offers based on specific user actions, leading to improved engagement and conversion rates.
3. **Optimized Campaigns:** Event tracking allows marketers to measure the effectiveness of marketing campaigns and initiatives by tracking key conversion events and attributing them to specific marketing channels or campaigns. This enables marketers to optimize their campaigns in real-time and allocate resources more effectively.
4. **Enhanced User Experience:** Understanding user behavior through event tracking helps businesses identify pain points, bottlenecks, and areas for improvement within their digital properties. By optimizing the user experience based on these insights, businesses can increase user satisfaction and loyalty.
5. **Data-Driven Decision Making:** Event tracking provides businesses with valuable data and analytics that can inform data-driven decision-making processes. By analyzing event data, businesses can identify opportunities for growth, innovation, and strategic planning, leading to better business outcomes.
In summary, event tracking is an essential tool for marketers and businesses looking to gain deeper insights into user behavior, personalize user experiences, optimize marketing efforts, and make data-driven decisions to drive business success in the digital age.
# Understanding the Events
Events form the backbone of data collection and analysis in marketing and analytics. Understanding events involves grasping the concept of what events are, the different types of events, and how they manifest across various industries. Let's delve into each aspect in detail:
## Definition of Events:
Events represent specific actions, occurrences, or interactions that users perform within a digital environment. These actions can be anything from clicking a button, submitting a form, viewing a page, making a purchase, or even non-click interactions like scrolling or hovering over an element. Each event is captured and recorded with relevant details or parameters, providing valuable insights into user behavior and engagement patterns.
### Types of Events:
Events can be classified into different types based on their characteristics and purposes. Some common types of events include:
1. **User Interaction Events:** These events capture user actions or interactions within a digital interface, such as clicks, taps, swipes, form submissions, and mouse movements.
2. **System Events:** System events monitor activities or behaviors related to the underlying system or infrastructure, such as error messages, system alerts, software updates, or server logs.
3. **Business Events:** Business events track key activities or transactions that occur within a business context, such as purchases, order placements, payments, sign-ups, subscriptions, and customer support interactions.
4. **Behavioral Events:** Behavioral events focus on capturing user behavior and engagement patterns over time, such as session starts, session ends, time spent on page, frequency of visits, and user journeys.
5. **Custom Events:** Custom events are events that businesses define and track based on their specific needs, objectives, and use cases. These events can vary widely depending on the industry, business model, and goals of the organization.
### Examples of Events in Different Industries:
Events are ubiquitous across various industries and are tailored to suit the specific needs and objectives of each sector. Here are some examples of events in different industries:
1. **eCommerce Industry:**
1. Product View: When a user views a product page.
2. Add to Cart: When a user adds a product to their shopping cart.
3. Checkout Initiation: When a user initiates the checkout process.
4. Purchase: When a user completes a purchase transaction.
5. Shipping Confirmation: When an order is shipped to the customer.
2. **Telecommunications Industry:**
1. Plan Selection: When a user selects a telecom plan.
2. Data Usage: When a user consumes data or makes calls.
3. Plan Renewal Reminder: When a user receives a reminder to renew their plan.
4. Plan Upgrade: When a user upgrades their existing plan.
3. **Healthcare Industry:**
1. Appointment Booking: When a patient books an appointment with a healthcare provider.
2. Prescription Refill: When a patient requests a prescription refill.
3. Health Monitoring: When a patient's vital signs are monitored remotely.
4. Appointment Reminder: When a patient receives a reminder about their upcoming appointment.
4. **Gaming Industry:**
1. Game Launch: When a player launches a game.
2. Level Completion: When a player completes a level or stage.
3. In-Game Purchase: When a player makes an in-game purchase.
4. Multiplayer Interaction: When players interact with each other in a multiplayer game.
5. **Financial Services Industry:**
1. Account Login: When a user logs into their financial account.
2. Fund Transfer: When a user transfers funds between accounts.
3. Bill Payment: When a user pays a bill online.
4. Loan Application Submission: When a user submits a loan application form.
Understanding events and their diverse applications across industries is essential for businesses to effectively track and analyze user behavior, optimize processes, and drive business success through data-driven insights and actions.
# Sample Tracking Plans
[**1. eCommerce Tracking Plan**](/docs/images/moengage_bc5489.png)
[**2. Fintech Tracking Plan**](/docs/images/moengage_15f980.png)
[**3. BFSI Tracking Plan**](/docs/images/moengage_c7259b.png)
[**4. Media / OTT Tracking Plan**](/docs/images/moengage_39c157.png)
**5. Create your own tracking plan using our [tracking plan template](/docs/images/moengage_e1f9f1.png)**
# Benefits of Event Tracking with MoEngage
Event tracking with MoEngage offers numerous benefits for businesses looking to enhance their marketing efforts, improve user engagement, and drive conversions. Let's explore some of the key advantages of leveraging event tracking with MoEngage:
**1. Enhancing User Engagement:**
Event tracking allows businesses to gain valuable insights into user behavior and preferences, enabling them to deliver more personalized and relevant experiences to their audience. With MoEngage, businesses can track a wide range of user interactions, such as app launches, page views, product interactions, and more. By understanding how users engage with their digital assets, businesses can optimize their messaging, content, and offers to better resonate with their target audience, ultimately driving higher levels of user engagement and retention.
**2. Leveraging Event Tracking for Personalization:**
Personalization is key to delivering exceptional customer experiences and building long-term relationships with users. MoEngage's event tracking capabilities empower businesses to collect rich behavioral data and use it to create highly personalized and contextualized experiences for their audience.
By tracking user actions and preferences, businesses can segment their audience based on behavior, interests, and engagement levels, allowing them to deliver targeted messages, recommendations, and offers that resonate with each individual user. This level of personalization not only enhances user satisfaction but also increases the likelihood of conversion and customer loyalty.
**3. Optimizing Marketing Campaigns with Event Data:**
Event tracking provides businesses with valuable data and insights that can be used to optimize marketing campaigns and drive better results. With MoEngage, businesses can analyze event data to understand the effectiveness of their marketing initiatives, identify high-performing channels and campaigns, and optimize their strategies in real-time.
By tracking key conversion events, engagement metrics, and user journeys, businesses can measure the impact of their marketing efforts, identify areas for improvement, and make data-driven decisions to maximize ROI.
Additionally, MoEngage's advanced analytics and reporting capabilities enable businesses to track campaign performance, attribute conversions, and measure the impact of personalized messaging on user behavior, allowing them to continuously refine their marketing strategies for optimal results.
# Getting Started with Event Tracking in MoEngage
Getting started with event tracking in MoEngage is an essential step for businesses looking to gain deeper insights into user behavior, personalize user experiences, and optimize marketing campaigns. Let's explore an overview of MoEngage event tracking features and how to access event tracking tools in the MoEngage dashboard:
## Overview of MoEngage Event Tracking Features:
MoEngage offers robust event tracking capabilities designed to help businesses collect, analyze, and act on valuable user behavior data. Some key features of MoEngage event tracking include:
**1. Flexible Event Tracking:** MoEngage allows businesses to track a wide range of user interactions, actions, and events across multiple channels, including mobile apps, websites, and other digital platforms. Businesses can define custom events based on their specific use cases and objectives, providing flexibility and scalability in tracking user behavior.
**2. Real-time Data Collection:** MoEngage enables real-time data collection and processing, allowing businesses to capture user interactions as they happen and gain immediate insights into user behavior. Real-time event tracking ensures that businesses can respond quickly to user actions and deliver timely, personalized experiences to their audience.
**3. Rich Event Properties:** With MoEngage, businesses can capture rich event properties and properties associated with each event, providing valuable context and detail about user interactions. These attributes can include user identifiers, timestamps, device information, geographic location, and any other relevant metadata, enabling businesses to segment their audience and personalize messaging based on specific user properties.
**4. Cross-Channel Tracking:** MoEngage offers cross-channel event tracking capabilities, allowing businesses to capture user interactions across various channels and touchpoints, including mobile apps, websites, email, SMS, and more. This holistic approach to event tracking enables businesses to gain a comprehensive view of user behavior and engagement patterns across the entire customer journey.
**5. Advanced Analytics and Reporting:** MoEngage provides advanced analytics and reporting tools that enable businesses to analyze event data, track key metrics, and derive actionable insights to inform marketing strategies and decision-making. Businesses can visualize event data through intuitive dashboards, generate custom reports, and measure the impact of their marketing campaigns on user behavior and conversion outcomes.
# Creating a Tracking Plan
A tracking plan serves as a roadmap for businesses to systematically define, organize, and implement their event tracking strategies. It outlines the key events to be tracked, along with their associated properties and parameters, to ensure consistent data collection and analysis. Let's explore the importance of a tracking plan and the steps to define your tracking plan in detail:
## Importance of a Tracking Plan:
**1. Clarity and Consistency:** A tracking plan provides clarity and consistency by clearly defining the events and properties to be tracked across digital channels. It ensures that all stakeholders have a shared understanding of the data being collected and its intended use, reducing confusion and discrepancies in data interpretation.
**2. Alignment with Business Goals:** A tracking plan helps align event tracking efforts with business goals and objectives. By identifying key user actions and conversion events that contribute to business success, businesses can prioritize their tracking efforts and focus on collecting data that is most relevant to their strategic objectives.
**3. Data Quality and Integrity:** A well-defined tracking plan promotes data quality and integrity by standardizing event naming conventions, property definitions, and data collection methodologies. It minimizes data errors, inconsistencies, and redundancies, ensuring that businesses can rely on their data for accurate analysis and decision-making.
**4. Scalability and Flexibility:** A tracking plan provides a scalable and flexible framework for managing event tracking initiatives as businesses grow and evolve. It allows businesses to easily adapt their tracking strategies to changing business requirements, market dynamics, and technological advancements, ensuring that their data collection efforts remain relevant and effective over time.
**5. Optimized Resource Allocation:** By outlining the events and properties to be tracked upfront, a tracking plan helps businesses optimize resource allocation and investment in event tracking tools, technologies, and implementation efforts. It ensures that businesses focus on tracking the most impactful events that drive business outcomes, maximizing the return on investment in data analytics.
## Steps to Define Your Tracking Plan:
**1. Identify Business Goals and Objectives:** Start by identifying the overarching goals and objectives of your business or marketing initiatives. What specific outcomes are you trying to achieve? What key performance indicators (KPIs) will indicate success?
**2. Understand User Behavior and Journeys:** Gain a deep understanding of your target audience, their behaviors, preferences, and interaction patterns across digital channels. Identify key user actions and conversion events that are critical to achieving your business goals.
**3. Define Key Events and Properties:** Based on your business goals and user behavior analysis, define the key events and properties to be tracked. Consider both high-level events (e.g., page views, sign-ups, purchases) and more granular actions (e.g., button clicks, form submissions, product interactions).
**4. Prioritize Events:** Prioritize events based on their relevance to your business goals, user engagement metrics, and potential impact on conversion outcomes. Focus on tracking events that are most closely aligned with your strategic objectives and have the highest potential for driving business growth.
**5. Document Your Tracking Plan:** Document your tracking plan in a centralized document or spreadsheet, detailing each tracked event along with its associated properties, parameters, and implementation instructions. Ensure that all stakeholders have access to and understand the tracking plan to facilitate collaboration and alignment.
**6. Implement Tracking Code:** Implement the necessary tracking code or integrations to capture and record the defined events and properties within your digital properties, such as websites, mobile apps, or other platforms. Follow best practices and guidelines provided by your analytics platform or tracking tools for seamless implementation.
**7. Test and Validate:** Test the implemented tracking code to ensure that events are being captured accurately and consistently across different devices, browsers, and user scenarios. Validate the data against expected outcomes and use cases to identify any discrepancies or issues that require resolution.
**8. Iterate and Optimize:** Continuously iterate and optimize your tracking plan based on feedback, insights, and evolving business needs. Monitor data quality, analyze event data reports, and incorporate learnings to refine your tracking strategy, improve data accuracy, and drive better business outcomes over time.
# Selecting Events to Track
Selecting the right events to track is crucial for businesses to gain meaningful insights into user behavior, optimize marketing efforts, and achieve their strategic objectives. It involves identifying key user actions and prioritizing events based on their alignment with business goals and potential impact on desired outcomes. Let's explore in detail how businesses can select events to track by identifying key user actions and prioritizing events based on business goals:
## Identifying Key User Actions:
**1. User Journey Analysis:** Conduct a thorough analysis of user journeys across digital channels to identify key touchpoints, interactions, and actions that users perform while engaging with your brand. Map out the typical paths users take from initial interaction to conversion, paying attention to common entry points, navigation patterns, and conversion funnels.
**2. Customer Persona Research:** Gain insights into the characteristics, preferences, and behaviors of your target audience by developing detailed customer personas. Understand the specific needs, motivations, pain points, and goals of different segments within your audience to identify the most relevant and impactful user actions to track.
**3. Data Exploration:** Explore existing data sources, analytics reports, and user feedback to uncover patterns, trends, and opportunities for optimization. Look for recurring user actions, conversion events, and engagement metrics that correlate with business success and indicate user intent or interest.
**4. Stakeholder Input:** Collaborate with cross-functional teams, including marketing, product, sales, and customer support, to gather input and insights into user behavior and business objectives. Leverage the expertise and perspectives of different stakeholders to identify key user actions that align with overarching business goals and strategies.
**5. Competitive Analysis:** Analyze the digital experiences and event tracking strategies of competitors and industry leaders to gain inspiration and benchmark against best practices. Identify common events tracked by competitors and evaluate their relevance and effectiveness in driving user engagement and conversions.
## Prioritizing Events Based on Business Goals:
**1. Alignment with Business Objectives:** Prioritize events that directly align with your business goals, objectives, and key performance indicators (KPIs). Focus on tracking events that have a clear impact on driving desired outcomes, such as conversions, revenue generation, customer retention, or brand loyalty.
**2. Impact on User Experience:** Consider the impact of tracked events on the overall user experience and satisfaction. Prioritize events that enhance user engagement, improve usability, and deliver value to users, leading to positive interactions and long-term relationships with your brand.
**3. Conversion Potential:** Identify events that signal user intent or progression towards conversion and prioritize tracking these events to optimize conversion funnels and drive revenue growth. Focus on high-value conversion events, such as sign-ups, purchases, subscriptions, or other desired actions that contribute to business success.
**4. Frequency and Importance:** Evaluate the frequency and importance of tracked events in relation to overall user engagement and business objectives. Prioritize events that occur frequently, have a significant impact on user behavior, or represent critical milestones in the user journey.
**5. Resource Allocation:** Consider resource constraints, implementation efforts, and technical feasibility when prioritizing events to track. Focus on tracking events that are feasible to implement, require minimal resources, and provide maximum value in terms of insights and impact on business outcomes.
# Defining Event Properties
Event properties provide additional context and detail about user interactions or actions captured through event tracking. Understanding event properties, defining them effectively, and leveraging them in event tracking initiatives is essential for businesses to gain deeper insights into user behavior, personalize user experiences, and optimize marketing strategies.
Let's delve into the details of defining event properties, including understanding event properties, examples of event properties, and best practices for defining event properties:
## Understanding Event Properties:
Event properties are attributes or parameters associated with each tracked event that provide context, detail, and additional information about the event and the user interaction it represents. These properties help businesses segment and analyze event data, personalize messaging and experiences, and derive actionable insights to inform decision-making.
Event properties can include a wide range of attributes, such as user identifiers, timestamps, geographic location, device information, and any other relevant metadata that enriches the event data.
**Examples of Event Properties:**
**1. User ID:** Unique identifier of the user performing the event.
**2. Timestamp:** Date and time when the event occurred.
**3. Device Type:** Type of device used by the user (e.g., desktop, mobile).
**4. Geographic Location:** Location from which the event originated (e.g., country, city).
**5. Page URL:** URL of the page where the event occurred.
**6. Referrer:** Source or channel that led the user to the event (e.g., organic search, social media).
**7. Event Value:** Numeric value associated with the event (e.g., purchase amount, product price).
**8. Event Category:** Category or classification of the event (e.g., navigation, conversion, engagement).
**9. User Segment:** Segment or cohort to which the user belongs (e.g., new users, returning users).
**10. Session ID:** Unique identifier of the user session during which the event occurred.
## Best Practices for Defining Event Properties:
**1. Relevance and Granularity:** Define event properties that are relevant to your business goals, user behavior analysis, and personalization efforts. Focus on capturing granular data that provides meaningful insights into user interactions and preferences, avoiding unnecessary or redundant properties that add complexity without adding value.
**2. Consistency and Standardization:** Standardize event property names, formats, and values to ensure consistency and interoperability across tracking initiatives and analytics tools. Use descriptive and intuitive property names that are easily understandable by stakeholders and facilitate data interpretation and analysis.
**3. Completeness and Accuracy:** Ensure that event properties capture all relevant information needed to analyze user behavior and derive actionable insights. Include essential attributes such as user identifiers, timestamps, and contextual information to provide a comprehensive view of each event and its context.
**4. Privacy and Compliance:** Respect user privacy and adhere to data protection regulations by carefully considering the types of event properties collected and their impact on user privacy. Minimize the collection of sensitive or personally identifiable information (PII) unless absolutely necessary and ensure compliance with applicable privacy laws and guidelines.
**5. Documentation and Documentation:** Document your event properties in a centralized tracking plan or schema to facilitate communication, collaboration, and alignment across teams. Document the purpose, definition, and usage guidelines for each event property to ensure consistent understanding and implementation.
# What are data types?
When it comes to event designing within MoEngage, understanding data types is paramount for effective implementation and analysis. Data types categorize information based on the kind of values they represent and dictate how these values can be manipulated and interpreted. In simpler terms, data types define the structure and format of the data, ensuring consistency and coherence throughout the system.
At its core, data types provide a framework for organizing and processing information within the MoEngage platform. Common data types include integers, floats, strings, and booleans, each serving distinct purposes in capturing and representing user interactions and behaviors. By understanding these fundamental data types, users can efficiently structure their event data to accurately reflect user interactions and attributes.
Moreover, comprehending data types empowers users to make informed decisions regarding event design and analysis strategies. Choosing the appropriate data type for each event property ensures data integrity and facilitates seamless integration with downstream processes such as segmentation, targeting, and reporting.
In essence, mastering data types equips users with the foundational knowledge necessary to harness the full potential of event designing capabilities offered by MoEngage.
## Common Data Types
| | | |
| - | - | - |
| **Data Type** | **Definition** | **Example** |
| | | |
| Integer (int) | Numeric data type for numbers without fractions | -307, 0, 307 |
| | | |
| Floating point (float) | Numeric data type for numbers with fractions | 307.07, 3.7 |
| | | |
| Boolean (bool) | True or false values | 0 (false), 1 (true) |
| | | |
| Array | List with a number of elements in a specific order—typically of the same type | Rock (0), Jazz (1), blues (2) |
| | | |
| String (str or text) | Sequence of characters, digits, or symbols—always treated as text | Hello, +91-1234-2421-42 |
| | | |
| Datetime | Date and time together in the YYYY-MM-DD hh:mm:ss format | 2021-09-28 12:00:59 |
# What is customer data?
Customer data refers to any information a company collects about its customers. This data can include a wide range of details such as names, contact information, demographics (like age, gender, location), purchase history, preferences, interactions with the company's products or services, feedback, and more.
Essentially, customer data encompasses any information that helps a company understand its customers better and tailor its products, services, and marketing efforts to meet their needs and preferences. Proper management and analysis of customer data are crucial for businesses to improve customer satisfaction, drive sales, and make informed decisions about their operations and strategies.
Customer data can be sourced from various channels and interactions with the company. Here are some common sources of customer data:
1. **Transactional Data:** This includes purchase history, order details, payment information, and any other data related to transactions made by customers.
2. **Interaction Data:** Information gathered from customer interactions with the company, such as website visits, clicks, page views, social media interactions, emails opened, and responses to marketing campaigns.
3. **Customer Service Interactions:** Data collected from customer service interactions, including inquiries, support tickets, chat transcripts, and feedback provided by customers.
4. **Demographic and Firmographic Data:** Details about customers' demographics (age, gender, location, income) and firmographics (company size, industry, revenue) help in understanding the characteristics of the customer base.
5. **Surveys and Feedback:** Data obtained through surveys, feedback forms, reviews, and ratings provided by customers, which offer insights into their preferences, satisfaction levels, and opinions.
6. **Social Media:** Information gathered from customers' social media profiles, posts, comments, likes, and shares can provide valuable insights into their interests, behavior, and sentiments.
7. **Third-Party Data:** Data purchased or obtained from third-party sources, such as data brokers, can supplement internal data and enrich customer profiles with additional information.
8. **Mobile Apps and IoT Devices:** Data collected from mobile applications, wearable devices, and Internet of Things (IoT) devices can provide real-time insights into customer behavior and preferences.
9. **Subscription and Membership Data:** Details about customers' subscription plans, membership levels, renewal dates, and usage patterns can inform targeted marketing and retention strategies.
# What is user data?
User data refers to any information collected, stored, or processed about individuals. This data can encompass a wide range of details that characterize and identify users, including but not limited to:
1. **Personal Information:** This includes basic details such as name, age, gender, date of birth, contact information (email, phone number, address), and other identifiers.
2. **Behavioral Data:** Information about users' actions, interactions, and behaviors within a digital environment, such as website visits, clicks, searches, purchases, preferences, and social media activities.
3. **Device and Location Data:** Details about the devices users use to access digital services (e.g., device type, operating system, browser), as well as their geographic location or IP address.
4. **Usage Patterns:** Data about how users engage with products or services over time, including frequency of use, session duration, feature usage, and user journeys.
5. **Preferences and Settings:** Information about users' preferences, settings, and configurations within digital platforms, such as language preferences, notification settings, and customization choices.
6. **Authentication and Security Data:** Data related to user authentication and security measures, such as login credentials, access permissions, authentication tokens, and security events (e.g., failed login attempts).
7. **Communication Data:** Content and metadata associated with user communications, including emails, messages, chats, calls, and other forms of communication exchanged within digital platforms.
User data is often collected through various channels, including websites, mobile apps, social media platforms, customer relationship management (CRM) systems, and other digital touchpoints.
Organizations use this data to personalize experiences, improve products and services, target marketing efforts, make data-driven decisions, and enhance user engagement and satisfaction.
# What is event data?
Event data refers to information generated by specific occurrences or actions within a system or application. These events represent significant interactions, transactions, or changes in state that are recorded and logged for analysis, monitoring, and decision-making purposes. In digital contexts, event data often pertains to user interactions, system events, or business activities occurring within software applications, websites, or digital platforms.
Examples of event data include:
1. **User Interactions:** Events triggered by user actions such as clicks, taps, scrolls, form submissions, page views, searches, purchases, sign-ups, logins, and other engagements with digital interfaces.
2. **System Events:** Events related to system operations and behaviors, including error messages, system alerts, performance metrics, software updates, API requests, database transactions, and server logs.
3. **Business Events:** Events that capture key business activities and processes, such as order placements, payments, shipments, inventory updates, customer support tickets, marketing campaigns, and sales conversions.
Event data is typically structured and timestamped, allowing for chronological ordering and analysis over time. It is often collected, processed, and stored in event logs, databases, or event streaming platforms, where it can be queried, analyzed, and visualized to derive insights, detect patterns, track performance, and trigger automated actions or responses.
# Implementing Event Tracking in MoEngage
Implementing event tracking in MoEngage is a critical step for businesses looking to capture and analyze user interactions across digital channels. It involves integrating event tracking code, leveraging MoEngage SDKs, and thoroughly testing the implementation to ensure accurate data collection and analysis. Let's explore in detail how businesses can implement event tracking in MoEngage:
**1. Implementing Event Tracking Code:**
**a. Generate Tracking Code:** Generate tracking code with the help of the MoEngage event tracking [help doc](https://www.moengage.com/docs/developer-guide/android-sdk/data-tracking/basic/track-events).
**b. Insert Code Snippet:** Insert the generated tracking code snippet into the relevant pages or components of your digital properties, such as websites, mobile apps, or other platforms. Place the code snippet within the HTML code or source files of your digital assets to ensure it is executed and loaded correctly.
**c. Define Tracked Events:** Define the events you want to track within the MoEngage dashboard by specifying event names, properties, and parameters. Customize event tracking settings to align with your tracking objectives and business requirements.
**d. Track Events Programmatically:** Utilize MoEngage's API or JavaScript functions to track events programmatically based on user interactions or system events within your digital properties. Call the appropriate tracking functions with event names and properties to capture relevant user actions in real-time.
**2. Integrating Event Tracking with MoEngage SDKs:**
**a. Select SDK:** Choose the appropriate MoEngage SDK based on the platform(s) of your digital properties, such as iOS, Android, web, or other supported platforms.
**b. Install SDK:** Integrate the MoEngage SDK into your digital properties by following the installation instructions provided in the SDK documentation. Install the SDK package using package managers, dependency managers, or manual installation methods, depending on the platform and development environment.
**c. Initialize SDK:** Initialize the MoEngage SDK within your application code by providing your MoEngage account credentials, API keys, and other configuration settings. Ensure that the SDK is properly initialized and configured to communicate with the MoEngage servers for event tracking and data synchronization.
**d. Track Events:** Utilize the SDK's event tracking methods or functions to track user interactions and system events within your application. Call the appropriate tracking functions with event names and properties to capture relevant user actions and behaviors.
**3. Testing Event Tracking Implementation:**
**a. Manual Testing:** Manually test the event tracking implementation by performing various user interactions and actions within your digital properties. Verify that tracked events are captured accurately and consistently across different devices, browsers, and user scenarios.
**b. Debugging Tools:** Use debugging tools, browser developer tools, or SDK logging features to inspect network requests, console logs, and event payloads generated by the event tracking code. Identify any errors, warnings, or anomalies in the tracking data and address them promptly.
**c. Validation Checks:** Validate tracked events against expected outcomes, user journeys, and business logic to ensure data accuracy and integrity. Verify that event properties are populated correctly and that tracked events align with predefined tracking objectives and use cases.
**d. Regression Testing:** Perform regression testing to ensure that event tracking implementation does not introduce any regressions or conflicts with existing functionality within your digital properties. Test the compatibility and interoperability of event tracking code with other components and modules of your application.
# Analyzing Event Data
Analyzing event data is crucial for businesses to gain actionable insights into user behavior, engagement patterns, and campaign performance. In MoEngage, accessing event data reports, interpreting event data metrics, and extracting insights play a vital role in optimizing marketing strategies and driving business growth. Let's explore in detail how businesses can analyze event data in MoEngage:
**1. Accessing Event Data Reports in MoEngage:**
**a. Dashboard Navigation:** Log in to your MoEngage account and navigate to the analytics section. Locate the event data reports dashboard, which provides insights into user interactions, engagement metrics, and campaign performance based on tracked events.
**b. Event Overview:** Access the event overview report to view a summary of all tracked events, including event names, frequencies, and trends over time. Gain a high-level understanding of user interactions and behaviors across different events and digital channels.
**c. Custom Reports:** Create custom reports and dashboards to analyze specific events, event properties, or user segments based on your tracking objectives and business requirements. Customize report parameters, filters, and visualizations to tailor insights to your unique needs.
**d. Real-time Data:** Leverage MoEngage's real-time data capabilities to access event data reports in real-time and monitor user interactions as they happen. Stay informed about the latest trends, patterns, and anomalies in user behavior to make timely decisions and optimizations.
**2. Interpreting Event Data Metrics:**
**a. Event Volume:** Analyze the volume of events tracked over time to understand user engagement levels, trends, and seasonality patterns. Identify spikes or drops in event volume that may indicate changes in user behavior or campaign effectiveness.
**b. Conversion Rates:** Calculate conversion rates for key conversion events to measure the effectiveness of marketing campaigns and user journeys. Monitor conversion rates over time and across different user segments to identify opportunities for optimization and improvement.
**c. User Engagement Metrics:** Evaluate user engagement metrics such as session duration, session frequency, and time spent on page to assess user engagement levels and content effectiveness. Identify areas of high engagement and optimize messaging and content to enhance user experience.
**d. Event Funnel Analysis:** Conduct event funnel analysis to visualize user journeys and conversion funnels, from initial interactions to desired outcomes. Identify drop-off points, bottlenecks, and opportunities for optimization within the conversion funnel to improve conversion rates and campaign ROI.
**3. Extracting Insights from Event Data Analysis:**
**a. User Behavior Patterns:** Identify recurring patterns, trends, and behaviors in event data analysis to gain insights into user preferences, interests, and intent. Understand how users interact with your digital properties and content to tailor messaging and experiences accordingly.
**b. Campaign Performance:** Evaluate the performance of marketing campaigns and initiatives based on event data analysis. Measure campaign attribution, ROI, and effectiveness in driving key conversion events and business outcomes.
**c. Segmentation Analysis:** Segment users based on event data attributes, properties, and behaviors to identify high-value segments, target audiences, and personalized messaging opportunities. Tailor marketing campaigns and offers to specific user segments to maximize relevance and engagement.
**d. Optimization Opportunities:** Use event data analysis to identify optimization opportunities, A/B test hypotheses, and iterate on marketing strategies. Experiment with different messaging, content formats, and targeting criteria to continuously improve campaign performance and drive better results.
# Optimizing Event Tracking Strategy
Optimizing event tracking strategy is essential for businesses to continuously improve data collection, analysis, and utilization processes. By iterating on tracking plans, conducting A/B testing, and incorporating feedback and learnings, businesses can enhance the effectiveness and impact of their event tracking initiatives. Let's explore in detail how businesses can optimize their event tracking strategy:
**1. Iterating on Your Tracking Plan:**
**a. Review Tracking Objectives:** Regularly review your tracking objectives and business goals to ensure alignment with evolving priorities, market dynamics, and user needs. Identify areas for improvement or optimization in your tracking plan based on changing requirements and feedback from stakeholders.
**b. Update Event Definitions:** Update event definitions, properties, and parameters in your tracking plan to capture new user interactions, actions, or behaviors that are relevant to your business objectives. Incorporate additional events or properties based on insights gained from data analysis and user feedback.
**c. Refine Tracking Methods:** Refine tracking methods and implementation approaches to enhance data accuracy, completeness, and reliability. Experiment with different tracking technologies, methodologies, and tools to identify the most effective and efficient ways to capture and analyze user behavior.
**d. Collaborate with Stakeholders:** Collaborate with cross-functional teams, including marketing, product, sales, and customer support, to gather input and insights into tracking plan optimization. Incorporate feedback and perspectives from different stakeholders to ensure that your tracking plan reflects diverse perspectives and requirements.
**2. A/B Testing Event Tracking Strategies:**
**a. Define Hypotheses:** Define clear hypotheses and objectives for A/B testing event tracking strategies. Identify specific tracking variations, parameters, or configurations to test, such as event names, properties, tracking methods, or implementation approaches.
**b. Split Testing:** Implement split testing methodologies to compare the performance of different tracking variants or strategies in real-world scenarios. Randomly assign users or segments to different tracking groups and measure key metrics and outcomes to assess the impact of each variation.
**c. Measure Impact:** Measure the impact of A/B testing on key performance indicators (KPIs), such as conversion rates, user engagement, or campaign effectiveness. Analyze the data to identify statistically significant differences between test groups and draw insights into the effectiveness of each tracking strategy.
**d. Iterate and Iterate:** Iterate on A/B testing results and refine tracking strategies based on learnings and insights gained from experimentation. Implement successful variations and discard ineffective ones to continuously optimize event tracking performance and drive better outcomes.
**3. Incorporating Feedback and Learnings:**
**a. Collect User Feedback:** Collect feedback from users, stakeholders, and internal teams regarding their experience with event tracking data and insights. Gather input on usability, relevance, and effectiveness of tracked events and properties to identify areas for improvement.
**b. Monitor Data Quality:** Continuously monitor data quality, integrity, and consistency to identify any issues or discrepancies in event tracking implementation. Address feedback and concerns related to data accuracy, completeness, and reliability to ensure that tracked data remains actionable and reliable.
**c. Analyze Insights:** Analyze insights and findings from event tracking data analysis to identify trends, patterns, and opportunities for optimization. Extract actionable insights from data analysis to inform decision-making, strategy development, and resource allocation.
**d. Iterative Improvement:** Implement iterative improvement processes based on feedback and learnings to continuously enhance event tracking strategy. Incorporate user feedback, data analysis findings, and best practices into tracking plan iterations and A/B testing initiatives to drive continuous improvement and innovation.
# Data Governance and Privacy
Data governance and privacy are critical considerations for businesses when collecting, storing, and processing user data. Ensuring data security and compliance, handling user consent and privacy regulations, and implementing data retention policies are essential components of a robust data governance framework. Let's explore each aspect in detail:
**1. Ensuring Data Security and Compliance:**
**a. Secure Data Storage:** Implement secure data storage mechanisms to protect user data from unauthorized access, breaches, or leaks. Utilize encryption, access controls, and other security measures to safeguard sensitive information stored in databases, servers, or cloud platforms.
**b. Compliance with Regulations:** Ensure compliance with relevant data protection regulations, such as the General Data Protection Regulation (GDPR), California Consumer Privacy Act (CCPA), or other applicable laws and standards. Stay informed about regulatory requirements, updates, and changes to ensure that data processing practices align with legal obligations.
**c. Data Encryption:** Encrypt sensitive data both at rest and in transit to prevent unauthorized interception or disclosure. Utilize encryption algorithms and protocols to secure data transmission over networks and encrypt stored data to protect it from unauthorized access or theft.
**d. Access Controls:** Implement access controls and authentication mechanisms to restrict access to user data based on roles, permissions, and least privilege principles. Grant access only to authorized personnel and enforce strong authentication measures, such as multi-factor authentication (MFA), to prevent unauthorized access.
**2. Handling User Consent and Privacy Regulations:**
**a. Transparent Data Practices:** Maintain transparency and accountability in data processing practices by providing clear and concise information to users about how their data is collected, used, and shared. Obtain explicit consent from users before collecting or processing their personal information, and provide options for users to opt out or withdraw consent if desired.
**b. Privacy Policy:** Publish a comprehensive privacy policy that outlines the types of data collected, purposes of data processing, data retention practices, and rights and choices available to users regarding their personal information. Ensure that the privacy policy is easily accessible, understandable, and up-to-date with current data practices and regulations.
**c. Cookie Consent:** Implement cookie consent mechanisms to obtain user consent for the use of cookies and similar tracking technologies on websites and digital properties. Display cookie banners or pop-ups that inform users about the use of cookies and provide options to accept or reject cookies based on their preferences.
**d. Regulatory Compliance:** Adhere to privacy regulations and guidelines, such as GDPR, CCPA, and other regional or industry-specific regulations, when collecting, processing, or sharing user data. Implement measures to comply with data subject rights, such as the right to access, rectify, or delete personal information, and respond to user inquiries and requests in a timely manner.
**3. Data Retention Policies:**
**a. Define Retention Periods:** Define data retention periods based on legal requirements, business needs, and data usage purposes. Determine how long different types of data will be retained before being securely deleted or anonymized to minimize data storage costs and risks.
> [!NOTE]
>
> MoEngage allows ingestion of data older than 2 months (default DRP) or beyond your account specific Data Retention Policy (DRP); But our Segmentation service will allow you to query the data only based on your DRP. Our Data Storage services deletes data beyond DRP on a periodic basis.
**b. Anonymization and Pseudonymization:** Anonymize or pseudonymize user data after the expiration of retention periods to remove personally identifiable information (PII) and reduce the risk of re-identification. Implement data anonymization techniques to preserve data utility while protecting user privacy and confidentiality.
**c. Regular Data Purging:** Regularly purge outdated or unnecessary data from storage systems to reduce data clutter and minimize security risks. Implement automated data purging processes or retention schedules to ensure timely deletion of expired data and compliance with data retention policies.
**d. Audit and Monitoring:** Conduct regular audits and monitoring of data retention practices to ensure compliance with retention policies and regulatory requirements. Monitor data storage systems, access logs, and retention schedules to identify any deviations or non-compliance issues and take corrective actions as needed.
# Troubleshooting and Support
Troubleshooting event tracking issues and accessing support resources are essential aspects of managing event tracking initiatives effectively. Businesses may encounter common challenges in event tracking, such as data discrepancies, implementation errors, or technical issues. By following troubleshooting tips and leveraging support resources provided by MoEngage, businesses can address these challenges and ensure the smooth operation of their event tracking systems. Let's explore in detail:
**1. Common Challenges in Event Tracking:**
**a. Data Discrepancies:** Discrepancies between expected and actual event data can occur due to various factors, such as implementation errors, browser compatibility issues, or data processing delays. Identifying the root cause of data discrepancies is essential for ensuring data accuracy and reliability.
**b. Implementation Errors:** Errors in event tracking code implementation, such as missing or incorrect tracking code snippets, can result in incomplete or inaccurate data capture. Debugging and troubleshooting tracking code issues are critical for resolving implementation errors and ensuring proper data collection.
**c. Technical Limitations:** Technical limitations of tracking technologies or platforms may restrict the types of events that can be tracked or the level of detail captured in event data. Understanding and mitigating technical constraints is important for optimizing event tracking capabilities and maximizing data utility.
**d. Data Sampling:** Data sampling techniques used in analytics reporting may impact the accuracy and representativeness of event data analysis, particularly for high-volume or complex data sets. Minimizing data sampling biases and ensuring data integrity are essential for deriving accurate insights from event data.
**2. Troubleshooting Tips and Solutions:**
**a. Review Implementation:** Review event tracking code implementation to ensure that tracking code snippets are correctly inserted and configured on relevant pages or components of your digital properties. Verify that tracking code is executed and loaded properly to capture user interactions.
**b. Check Configuration:** Check configuration settings and parameters within your event tracking tools or platforms to ensure that tracking settings align with your tracking objectives and business requirements. Adjust tracking configurations as needed to capture desired events and properties accurately.
**c. Test and Debug:** Test event tracking implementation across different devices, browsers, and user scenarios to identify and debug issues. Utilize browser developer tools, debugging extensions, or SDK logging features to inspect network requests, console logs, and event payloads for errors or anomalies.
**d. Monitor Data Quality:** Monitor data quality and integrity regularly by comparing tracked events against expected outcomes and user interactions. Set up alerts or notifications to detect data discrepancies or anomalies in real-time and take corrective actions to address issues promptly.
**3. Accessing MoEngage Support Resources:**
**a. Knowledge Base:** Access MoEngage's knowledge base, documentation, and help center for comprehensive guides, tutorials, and troubleshooting articles on event tracking and related topics. Search for solutions to common issues or browse through support resources to find answers to your questions.
**b. Community Forums:** Participate in MoEngage's community forums, discussion boards, or user groups to connect with other users, share experiences, and exchange best practices for event tracking and marketing automation. Engage with the community to seek advice, offer insights, and collaborate on problem-solving.
**c. Technical Support:** Contact MoEngage's technical support team for personalized assistance with troubleshooting event tracking issues, resolving technical challenges, or addressing specific questions or concerns. Reach out to support representatives via email, live chat, or support tickets for timely support and guidance.
**d. Training and Webinars:** Attend training sessions, webinars, or workshops offered by MoEngage to learn about event tracking best practices, advanced features, and tips for optimizing marketing automation strategies. Stay informed about platform updates, new features, and industry trends through educational resources provided by MoEngage.
# Conclusion
In conclusion, event tracking with MoEngage offers businesses valuable insights into user behavior, engagement patterns, and campaign performance, empowering them to optimize marketing strategies and drive business growth. Throughout this guide, we've covered essential aspects of event tracking, including understanding events, defining event properties, accessing event data reports, and optimizing event tracking strategy. Let's recap the key takeaways and outline next steps for implementing event tracking with MoEngage:
## Recap of Key Takeaways:
**1. Understanding Events:** Events represent user interactions or actions captured through event tracking, providing valuable data for analyzing user behavior and optimizing marketing campaigns.
**2. Defining Event Properties:** Event properties provide additional context and detail about tracked events, facilitating segmentation, personalization, and data analysis efforts.
**3. Accessing Event Data Reports:** MoEngage offers comprehensive event data reports and analytics dashboards for analyzing user interactions, engagement metrics, and campaign performance based on tracked events.
**4. Optimizing Event Tracking Strategy:** Iterating on tracking plans, conducting A/B testing, and incorporating feedback and learnings are essential for optimizing event tracking initiatives and driving better outcomes.
## Next Steps for Implementing Event Tracking with MoEngage:
**1. Define Tracking Plan:** Define your event tracking plan by identifying key user actions, defining event properties, and prioritizing events based on business goals and objectives.
**2. Implement Tracking Code:** Implement event tracking code snippets or integrate MoEngage SDKs into your digital properties to capture user interactions and track relevant events.
**3. Test Implementation:** Test event tracking implementation across different devices, browsers, and user scenarios to ensure accurate data collection and reliability.
**4. Analyze Event Data:** Access event data reports and analytics dashboards in MoEngage to analyze user behavior, engagement metrics, and campaign performance based on tracked events.
**5. Optimize Strategy:** Iterate on your tracking plan, conduct A/B testing, and leverage insights from event data analysis to continuously optimize your event tracking strategy and drive better business outcomes.
# Derived Events & Attributes
Source: https://moengage.com/docs/user-guide/data/event-data/derived-events-and-attributes
Explore MoEngage auto-generated derived events and attributes. View lifecycle, acquisition, uninstall, reachability, and campaign activity categories.
MoEngage, by default, generates a few of the events and attributes. These are called derived events and derived attributes. These can be used in segmentation and analytics as filters to segment the users.
Know more about [List of derived User properties here](/docs/user-guide/data/user-data/derived-user-attributes).
## Events / User Activity
Category-wise list of events:
### Lifecycle
| Name | Description | Platform |
| - | - | - |
| App/Site Opened | Tracked when a user session begins on the app or website. Also, this is tracked only if the time difference between the user's Last Active Time and App/Site Open Time is more than 30 min. | Android, iOS, Web, TV |
| Viewed Web Page | Tracked when a user visits a web page. Select page URL as an event property to find the number of users visiting a particular page or use it to set up a Drop-off capture" Event Triggered Web Push. | Web, TV |
| App Exit | Tracked whenever App goes to background. | Android, iOS, TV |
| User Logout | Tracked when a user Logs out of the app/site or user reset. | Android, iOS, Web, TV |
| Push ID Register Android | Tracked when the MoEngage system registers the push ID for Android devices. Attribute registered_by has the status. | Android, TV (Android TV only) |
| User Merged | Tracked for a known user whenever a MoEngage user object is merged with it. | User Merging |
| App Update | Tracked when a user updates the App. | Android, iOS, TV |
### Acquisition & Uninstall
| Name | Description | Platform |
| - | - | - |
| Device ReInstall | Tracked when a reinstall is detected on a device. | Android, iOS |
| Device Uninstall | Tracked when a user uninstalls the app on a device. | Android, iOS, TV (Android TV only) |
| User ReInstall | Tracked when a reinstall is detected for an identified user in MoEngage. | Android, iOS |
### Reachability
| Name | Description | Platform |
| - | - | - |
| Accepted Web Push Soft-ask | Tracked when a user accepts the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
| Closed Web Push Soft-ask | Tracked when a user closes the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
| Denied Web Push Subscription | Tracked when a user denies receiving push notifications on the Web. | Web |
| Dismissed Web Push Subscription | Tracked when a user dismisses the push subscription prompt. | Web |
| Overlay clicked in 1-click HTTP subscription | Tracked when a user clicks a Subscription Message on your website as part of the HTTP Push Subscription flow. | Web |
| Overlay shown in 1-click HTTP subscription | Tracked when a user views a Subscription Message on your website as part of the HTTP Push Subscription flow. | Web |
| Subscribed to Web Push (Deprecated) | Tracked when a user is subscribed to Web Push Notifications. Use it to find the day-wise count of subscribers or set up a "Welcome" Event Triggered Web Push. **Note**: This event was used to track when a user subscribes to Web Push notifications. This event will be deprecated by July, 2024. This data can now be tracked using Subscribed to push with Platfrom = Web. | Web |
| Unsubscribed from Web Push (Deprecated) | Tracked when a user directly unsubscribes from the website/chrome settings or GCM communicates that a push token is invalid. **Note**: This event was used to track when a user unsubscribes to Web Push notifications. This event is deprecated by July, 2024. This data can now be tracked using Unsubscribed to push with Platfrom = Web | Web |
| Viewed Web Push Soft-ask | Tracked when a user views the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
| Subscribed to Push | Tracked when a user subscribes to Push Notifications. Note: *This event will not be generated for devices what when permission is granted by default. Eg. Android 12 and below devices* | Android, iOS, Web |
| Unsubscribed to Push | Tracked when a user changes push permission for a device from Subscribed to Unsubscribed Note: *This event will not be generated for devices where the permission is denied by default.* | Android, iOS, Web |
### Campaign Activity
| Name | Description | Channel / Platform |
| - | - | - |
| Allowed Web Push Subscription | Tracked when a user allows receiving push notifications on the Web. | Web |
| Displayed Web Push Subscription | When hard ask is shown to the user. | Web |
| Card Clicked | Tracked when the user clicks the Card in the App Inbox. | Android, iOS |
| Card Delivered | Tracked when a Card is delivered to the App Inbox after the user has opened the Inbox. | Android, iOS |
| Card Sent | Tracked when a Card notification is sent to the user, doesn't indicate if the notification is delivered to the App Inbox. | Android, iOS |
| Card Viewed | Tracked when the user views a Card or scrolls down to it in the App Inbox. | Android, iOS |
| Connector Sent | Tracked when a connector was sent successfully. | Connector |
| Email Bounced | Tracked when our system finds an email is hard bounced. Typically happens when an email address doesn't exist. This is tracked uniquely for every user based on the user ID. | Email |
| Email Clicked | Tracked when a user clicks on any link in the email. | Email |
| Email Complained | Tracked when a user marks the email as spam. | Email |
| Email Delivered | Tracked when our system receives a delivery confirmation for the Email sent to a user from the ESP. | Email |
| Email Deferred | Tracked when the receiving server delayed acceptance of the email message. | Email |
| Email Dropped | Tracked when an email is dropped. Email is dropped, when it's part of the bounce list, the unsubscribe list, or the spam report list. | Email |
| ESP Dropped Request (Formerly Email Unsubscribe Drop) | Tracked when an email request was sent to the ESP and then dropped due to the email ID being part of the suppression list (Unsubscribe a hard bounce, marked complaint) at the ESP. The reason for the drop can be found in one of the following attributes: - UNSUBSCRIBED_DROPPED_REASON = "User part of Unsubscribe list on the ESP. (applicable to SendGrid and Netcore ESP) - HARD_BOUNCE_DROPPED_REASON = "User part of Bounce list on the ESP". (applicable to SendGrid and Netcore ESP) - SPAM_DROPPED_REASON = "User part of Spam Complaint list on the ESP". (applicable to SendGrid and Netcore ESP) - MANUAL_SUPPRESSION_DROPPED_REASON = "User added to Suppression Manually" (applicable only to Netcore ESP) | Email |
| Email Opened | Tracked when a user opens an email. | Email |
| Email Sent | Tracked when our system sends an email to a user. | Email |
| Email Soft Bounced | Tracked when our system finds an email is soft-bounced. Typically happens when there is a temporary delivery issue. This is tracked uniquely for every user based on the user ID. | Email |
| Email Subscription Category Updated | Tracked when a user updates their preferences for email subscription categories. | Email |
| Email Unsubscribed | Tracked when a user unsubscribes from receiving emails. | Email |
| Email Viewed in Browser | Tracked when a user clicks on the view in the browser link present in the email. | Email |
| Facebook Audience Synced | Tracked when Facebook API returns 2xx response for add or delete request to an audience. | Facebook |
| Google Ads Audience Synced | Tracked when the Google Ads API returns a 2xx response for an add or delete request to an audience. | Google Ads Audience |
| Mobile In-App Clicked | Tracked when a user clicks the In-App message | Android, iOS, TV |
| Mobile In-App Closed | Tracked when a user dismisses an In-App message by clicking on the close button on the device. | Android, iOS, TV |
| Mobile In-App Shown | Tracked when an In-App message is shown to the user on the device. | Android, iOS, TV |
| Mobile In-App Auto Dismissed | Tracked when the In-App message closes by itself after the time duration given while creating the campaign. | Android, iOS, TV |
| Notification Clicked Android | Tracked when a user clicks a notification on an Android device. | Android |
| Notification Clicked iOS | Tracked when a user clicks a notification on an iOS device. | iOS |
| Notification Clicked Web | Tracked when a user clicks a notification on the browser. | Web |
| Notification Clicked Windows | Tracked when a user clicks a notification on a Windows device. | Windows |
| Notification Dismissed iOS | Tracked when the user dismisses the notification on an iOS device. | iOS |
| Notification Received Android | Tracked when a user receives a notification on an Android device. | Android |
| Notification Received iOS App Active | Tracked when the App is in the foreground and the user receives the notification on iOS. | iOS |
| Notification Received iOS | Tracked when a user receives a notification on an iOS device. | iOS |
| Notification Received Web | Tracked when a user receives a notification on a browser. | Web |
| Notification Sent iOS | Tracked when the Notification sending service accepts to send the notification on an iOS device. | iOS |
| On-site Message Shown | Tracked when an on-site messaging campaign is shown to a user. | Web, TV |
| On-site Message Clicked | Tracked when an on-site messaging campaign is clicked by a user. | Web, TV |
| On-site Message Closed | Tracked when an on-site messaging campaign is closed by a user. | Web, TV |
| On-site Message auto Dismissed | Tracked when the on-site message closes by itself after the time duration given while creating the campaign. | Web |
| Push Preference Changed iOS | Tracked when iOS device push preference is changed. It has a modified status. **Note**: This event is deprecated. It was used to track when a user unsubscribes to Push notifications.
Subscribed to push event with platform attribute as iOS
Unsubscribed to push event with platform attribute as iOS
| iOS |
| Web Personalization Message Shown | Tracked when a web personalization campaign is shown to a user. | Web |
| Web Personalization Message Clicked | Tracked when a web personalization campaign is clicked by a user. | Web |
| SMS Delivered | Tracked when our system receives a delivery receipt for the SMS sent to a user. | SMS |
| SMS Sent | Tracked when our system sends SMS to a user. alert_id, transaction_id, sender_name, reference_name | SMS |
| SMS Clicked | Tracked when a user clicks on any of the links in the SMS message body. | SMS |
| SMS Keyword Received | Tracks when the system receives a keyword as the response. | SMS |
| SMS Keyword Response Sent | Tracked when the system sent an SMS auto response message to a user. | SMS |
| User Entered Flow | Tracked when a user falls into the target audience and has qualified for the entry in the Flow. | Flows |
| User Exited Flow | Tracked when a user exits from a Stop Cell of the Flow. | Flows |
| User removed from campaign due to control group | Generated while sending a campaign out with the control group defined. | Flows/Campaign Channels |
| User added to control group | Generated while creating a global control group. | Flows/Campaign Channels |
| User removed from control group | Generated when the global control group is updated. Specifically when the global control group % is reduced or the global control group is refreshed. | Flows/Campaign Channels |
| WhatsApp Message Clicked | Tracked when a WhatsApp Message is read by the user. It will only be available for users who have read receipts enabled. | Flows/Campaign Channels |
| WhatsApp Message Delivered | Tracked when a WhatsApp Message is delivered to a user. | Flows/Campaign Channels |
| WhatsApp Message Delivery Failed | Tracked when provider failed to send/deliver a WhatsApp Message for a user. | Flows/Campaign Channels |
| WhatsApp Message Read | Tracked when a WhatsApp Message is read by the user. It will only be available for users who have read receipts enabled. | Flows/Campaign Channels |
| WhatsApp Message Sent | Tracked when a WhatsApp message is sent to a user. | Flows/Campaign Channels |
### Billable Standard Events
Billable Standard Events are predefined events in MoEngage that are tracked by the platform at your request. Unlike other derived events (automatically tracked) or custom events (sent by you via SDK or integrations), Billable Standard Events are generated when you ask MoEngage to capture certain specific events/actions. Each occurrence of these events contributes to your billed event count.
Since Billable Standard Events are tracked on demand, you need to create a support ticket to enable one or more of the Billable Standard Events. Note that data will be available only from the date the event is enabled as per your request.
## Event Properties
Source-wise list of event properties:
### For SDK Events
| Name | Description |
| - | - |
| App Version | Mobile Application version on which this event was tracked. App Version is tracked with all events. |
| SDK Version | MoEngage SDK version on which this event was tracked. SDK Version is tracked with all events. |
| Platform | OS name on which this event was tracked, for example -Android, iOS, Web, and TV. The platform is tracked with all events. |
| OS Type | The type of the OS this event was tracked on. For example Android, iOS, Roku, WebOS, AndroidTV, tvOS, Tizen, FireOS, VizioTV, and Xbox. |
| utm_source | Source of a campaign e.g. search engine, newsletter, MoEngage |
| utm_medium | Medium of a campaign e.g. CPC, email, push |
| utm_campaign | UTM Campaign name e.g. Summer sale |
| utm_id | UTM campaign ID e.g. 12DSW55 |
| utm_content | Content information of the campaign e.g. logoclick |
| utm_term | Term used for paid search e.g. red+shirt |
| Device Density DPI | Resolution of the device display (in dots per inch) |
| Device Height | Width of the screen (in pixels) |
| Device Manufacturer | Manufacturer of the device e.g. Apple |
| Device Model | Model Name of the device e.g. Dell Inspiron |
| Device Screen Dimension | Dimension of the screen in Width\*Height format |
| Device Width | Height of the screen (in pixels) |
| Network Type | Type of the network. For example, Wifi, 4G |
| OS Version | Version of the operating system e.g. iOS 11 |
| timestamp | User time while performing the event. This is in epoch time. |
| First Session | Generated for all the events tracked with MoEngage web SDK. Value is True for the first session of the user only. |
| Logged In Status | Generated for all the events tracked with MoEngage web SDK. Value is True if the user has logged in on the device. |
> [!NOTE]
>
> * Some MoEngage-tracked events or system events (e.g., App/Site opened) have device information tracked as [event properties](/docs/user-guide/data/event-data/derived-events-and-attributes#event-properties). Such event properties are available for analysis and segmentation.
> * [Device attributes](/docs/user-guide/data/event-data/derived-events-and-attributes#device-attributes) tracked by MoEngage SDKs are not available for analysis and segmentation.
### For Campaign Events
| Name | Description |
| - | - |
| Campaign Id | ID of the campaign associated with this event. |
| Campaign Name | Represents the name of the campaign, the message was part of. |
| Campaign Type | Represents the type of campaign, the message was part of. |
| Readable Campaign Id | Represents the ID of the campaign, the message was part of. |
| Parent Campaign id | Tracked when a periodic campaign is run. Represents the campaign ID of the parent periodic campaign, child instances of which are re-run on a recurring basis. |
| Parent Flow Id | Tracked when the journey campaign is run. Represents the Flow ID of the parent journey campaign. |
| Parent Flow Name | Tracked when the journey campaign is run. Represents the flow name of the parent journey campaign. |
| Locale Id | Tracked when the campaign is sent using Localization. Represents the ID of the message locale. |
| Locale Name | Tracked when the campaign is sent using Localization. Represents the name of the message locale. |
| Variation Id | Tracked when a campaign is sent using A/B Testing. Represents the ID of message variation. |
| Version Id | Tracked when the journey campaign is run. Represents the Version Name that the journey campaign belong to |
| URL | Tracked when display filter is selected in the in-app campaign. |
| Exit Reason | Tracked when a user exits the flow. This is tracked as an attribute of the 'User Exited Flow' event. |
| Reasons | Tracked when an email request is dropped from the ESP to convey the reason behind dropping the request. This is tracked as an attribute of the 'ESP Dropped Request' event |
| Email Subject | Represents the Subject of the Email Campaign. This is tracked as part of all Email Events |
| Channel Content Type | Represents the Content type (Transactional vs Promotional) for Email Campaigns. This is tracked as part of all Email Events |
| Campaign Type | Represents the Channel (Email, SMS, Push, etc...) through which the Campaign was sent. |
| Delivery Type | Represents the Delivery type (One-Time, Periodic, etc...) of the Campaign |
| Campaign Tags | Represents the Tags added to the Campaign. This is tracked in all Campaign Related Events |
## Device Attributes
MoEngage SDKs collect the following device attributes:
> [!NOTE]
>
> MoEngage SDKs collect the following device attributes at the device level; these attributes are linked to a specific device instance, not to the user's profile:
>
> **Available for Segmentation**
>
> The following device attributes are copied into user properties and are available in segmentation as a user property:
>
> * **Advertising Identifier** (iOS/Windows): Available as the "Advertising Identifier" user property
> * **moe_gaid** (Android): Google Advertising ID
> * **Browser Details (moe_w_ds)**: For web users, includes platform, browser, and manufacturer
> * **Mobile User (moe_mweb)**: Whether the user accessed on mobile web
>
> **Not Available for Segmentation**
>
> All other device attributes listed below are not available as user properties in segmentation:
>
> * **iOS:** IDFV, os_ver, device_tz, model, model_name
> * **Web/MWeb:** os, os_platform, os_ver, model, device_ts, device_tz, push_id
> * **TV:** os_key, moe_os_type, unique_id, push_id, status, OS_VERSION, MODEL, app_version
### iOS
| **Identifier** | **Information** | Tracking Type |
| - | - | - |
| ADVERTISING_IDENTIFIER | An alphanumeric string unique to each device used only for serving advertisements [IDFA](https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier "https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier") iOS version 14.5 and above Advertisement identifier will be tracked only if the developer asked permission for it. Below iOS 14.5 it is tracked automatically. | Default |
| IDFV | An alphanumeric string that uniquely identifies a device to the app’s vendor - [IDFV (identifierForVendor)](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor "https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor") | Default |
| os_ver | Current iOS version of the device | Optional |
| device_tz | Device Timezone | Optional |
| model | Device model type eg:iPhone"/"iPad" | Optional |
| model_name | Specific Device Model Name eg:iPhone 7",iPhone X" etc | Optional |
### Android
| **Identifier** | **Information** | Tracking Type |
| - | - | - |
| OS Version | Current Android version of the device | Default |
| API level | -- | Optional |
| Model Name | Device Model Name e.g. S22 | Optional |
| Product Name | Device Product Name e.g. Galaxy | Default |
| Manufacturer | Device Manufacturer e.g. Samsung | Default |
| Google Advertising Identifier (GAID) | GAID of the device | Default |
| GAID tracking status | GAID tracking status | Default |
| Carrier | Device Carrier e.g. Airtel, T-Mobile | Default |
| Device Density | Device screen density in PPI | Default |
| Device Width | Device width in pixel | Default |
| Device Height | Device height in pixel | Default |
| Android Id | -- | Default |
| Network Type | Device Network Type e.g. 3G, 5G | Optional |
| Device Timezone | Device Time Zone e.g. PST, IST, GMT | Optional |
### Web
| **Identifier** | **Information** | Tracking Type |
| - | - | - |
| os | Web / MWeb | Optional |
| os_platform | User Agent. Information about the browser. | Optional |
| os_ver | Browser Name | Optional |
| model | Browser Name | Optional |
| device_ts | Device Timestamp | Optional |
| device_tz | Device Timezone | Optional |
| push_id | Push token generated by SDK | Optional |
### TV
| **Identifier** | **Information** | Tracking Type |
| - | - | - |
| os_key | The platform will be set to TV for all TV devices. | Optional |
| moe_os_type | The operating system of the TV device. | Optional |
| unique_id | -- | Optional |
| push_id | Only present for Android TV and Amazon Fire TV | Default |
| status | Calculated based on re-install, uninstalls, and more. Default value: 1 | Optional |
| OS_VERSION | The OS version that is installed on the TV. | Optional |
| MODEL | The model name of the TV device. | Optional |
| app_version | The app version of the app where the event was tracked. | Optional |
> [!NOTE]
>
> * As of now, only the ADVERTISING IDENTIFIER is available on the dashboard for segmentation and analytics usage. IDFA and IDFV will not be collected if data tracking is opted out with GDPR opt-out methods.
> * Attributes marked as optional under tracking type may or may not be tracked depending on end-user consent or SDK implementation.
# Event Time and Received Time
Source: https://moengage.com/docs/user-guide/data/event-data/event-time-and-received-time
Understand the difference between event time and server received time in MoEngage. Learn how UTC time zones affect your analytics and event queries.
# Introduction
MoEngage stores all the time data in UTC time (Except the event). MoEngage queries your action & user analysis on the UTC time using the time zone offset of your App time zone. MoEngage collects Event Time and Server Time.
# Event Time
Event Time is the time on the device when the event was performed. Event Time is displayed in the User Profile. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile).
For events that are not generated at the device ([MoEngage generated events](/docs/user-guide/data/event-data/derived-events-and-attributes)) or events that don't have device time ([Data API events](https://www.moengage.com/docs/api/event/track-event)), the event time is recorded in the User Timezone. If it is unavailable, then the App timezone is shown. If neither is available, then UTC time is taken as the Event Time.
# Received Time (Server Time)
Whenever an event is received on the MoEngage servers from the device, the time is set as the Event Received Time (or Server Time).
For events that are not generated at the device ([MoEngage generated events](/docs/user-guide/data/event-data/derived-events-and-attributes) and [Data API events](https://www.moengage.com/docs/api/event/track-event)) the Received Time is the App time zone in the user profile.
All Segmentation and Analytics queries use Received Time for the event time range selection.
In [User Profile](/docs/user-guide/data/user-data/user-profile) for all events, there is Event Time (time at which the event is performed) and Event Received time (time at which the event is received at MoEngage).

# Difference between Event Time and Receive Time
Event Time and Event Receive Time (Server Time) are generally the same or might have a difference of a few seconds. But at times, Event Time and Server Time are not the same and the time differences are higher. The reasons are:
* Data reaches the MoEngage server with a delay - The events do not reach to MoEngage servers in time due to Internet issues, App crashes, App removal from memory (especially with Chinese OEMs), etc.
* Event Time is not accurate - Device time is not accurate which leads to inaccurate event time.
The high time difference between Event Time and Server Time provides a slightly deviated analysis for very few users. For these users, the segmentation, analytics, and user profile results might have slightly deviated. The impact is less than 0.5% of the user events.
There is no impact on the campaign analysis in the campaign detail pages and the campaign stats dashboard.
# Analyze the Volume of Data Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/analyze-the-volume-of-data-exports
Calculate and monitor your MoEngage data export volume. Track event counts exported via Streams or Data Warehouse Exports to manage monthly usage.
## Introduction
In this article, you will learn how to calculate/analyze the volume of events that were exported from your MoEngage App using either [Streams](https://www.moengage.com/docs/api/data/moengage-streams) or [Data Warehouse Exports](/docs/user-guide/data/exports/events/data-warehouse). This can help you track the amount of data that you are receiving and your monthly export volume usage.
## Total Volume of Events Exported
Please contact your MoEngage Customer Success Manager for the total volume of events being exported.
## Calculate the Volume of Individual Events
In case you want a detailed event-wise breakdown of the total volume, you can calculate it. However, this is currently a manual process. Note that there can be some discrepancies between the number of events shown on the MoEngage Dashboard and the actual number of events received by you.
### Step 1: Get the List of Events Being Exported
> [tab] Data Warehouses
>
> If you have set up automated exports through the App Marketplace, you can view all your exports on the **Integrate** tab on the Partner page. The following is an example for [S3 Exports](https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/s3-exports):
>
> 1. On your MoEngage Dashboard go to **App Marketplace** > **Amazon S3** > **Integrate**.
> 2. View the list of integrations you have currently active: 
> 3. Click the three dots on the integration card, and click **Edit**.
> 4. Under **Export Details**, look at the **Select events** option:
> 1. All Events: If you have selected *All events*, getting a breakdown for each event might be a more time-consuming task.
> 2. Selected events: If you have selected a few events you want to export, make a list of these events. You will need this list later.
> [tab] Streams
>
> If you have set up Streams for your account, you can speak to your Customer Success Manager for the latest configuration.
### Step 2: Analyze the Volume of Each Event Exported
With MoEngage Analytics, you can obtain a comprehensive breakdown of the total count for each event. As and when MoEngage receives an event, it is forwarded to your destination without any modifications. This ensures that the volume of events displayed on the MoEngage Dashboard accurately corresponds to the volume of events received by you.
1. On your MoEngage Dashboard go to **Analyze** > **Behavior**.
2. Select your events from the list of events being exported. Click **+ Add Event** to add multiple events. A breakdown of 10 events at a time will be provided: 
3. Under **Filter Users**, select **All Users**.
4. Under **Behavior Options**, select **Total Events**.
5. Set the duration as the duration you want to check. Typically, this is a window of 30 days.
6. Click **Apply** when ready to see your report.
7. After your results are loaded, look at the Behavior Table: 
8. If your second column is not "Sum", you can click the down arrow next to the column and select "Sum". This should show the total number of events that have occurred in the selected period.
9. Click **Download CSV** to export this report.
10. Repeat this process for all the events you are exporting. We suggest that you monitor only events that highly impact your analysis such as "Email Sent", "Email Opened", and so on.
> [!NOTE]
>
> The report on the MoEngage Dashboard is in the App Timezone. MoEngage Automated Data Exports happen in the UTC Timezone. Please account for this difference when you are generating reports at your end.
[YouTube video player](https://www.youtube.com/embed/y990V153UC0)
# Data Export Glossary
Source: https://moengage.com/docs/user-guide/data/exports/events/data-export-glossary
Reference guide for MoEngage event export options. Understand Streams, data warehouse destinations, cloud storage exports, and supported event types.
# Introduction
With MoEngage Event Exports, you can forward events to various third-party tools. We offer the following capabilities:
1. **MoEngage Streams** - Streams allow you to forward events like user actions, campaign interaction events, and so on available in MoEngage to a pre-defined API endpoint in near real-time.
2. **Data Warehouses** - MoEngage supports multiple data warehouses as destinations to forward events directly to your tables. We support:
1. [Amazon Redshift](/docs/user-guide/data/exports/events/data-warehouse/redshift-exports)
2. [Google BigQuery](/docs/user-guide/data/exports/events/data-warehouse/bigquery-exports) (via GCS)
3. [Snowflake](/docs/user-guide/data/exports/events/data-warehouse/snowflake-exports)
3. **Cloud Storages** - MoEngage also supports multiple cloud storages as destinations to forward events as JSON files in your buckets.
1. [Amazon S3](/docs/user-guide/data/exports/events/data-warehouse/s3-exports)
2. [Google Cloud Storages](/docs/user-guide/data/exports/events/data-warehouse/google-cloud-storage-gcs-exports)
3. [SFTP](/docs/partner-guide/data-and-analytics/cloud-storage/sftp)
# Export Schema
The export schema depends on the type of destination. Each category (Data Warehouse, Cloud Storages, APIs) has a consistent schema to account for various MoEngage Events and User-Defined Events.
## Streams (API)
MoEngage will make a Bulk API call to your provided API Endpoint. Here is the generic structure:
JSON
```json wrap theme={null}
{
"app_name": "The name of your app.",
"source": "MOENGAGE",
"moe_request_id": "MoEngage unique request id for each request.",
"events": [
{
"event_name": "Name of your event",
"event_code": "Event code",
"event_uuid": "Unique code of this event. This helps in determining each unique event being captured by MoEngage.",
"event_time": "EPOCH_TIMESTAMP_OF_EVENT_TRIGGERED_TIME_IN_UTC",
"event_type": "CAMPAIGN_EVENT",
"event_source": "MOENGAGE",
"push_id": "Recipient device’s push token",
"email_id": "Recipient's email ID",
"mobile_number": "Recipient's mobile number",
"uid": "MoEngage Customer ID",
"event_attributes": {
"campaign_id": "ID of the campaign",
"campaign_name": "Name of the campaign",
"campaign_type": "Type of the campaign",
"campaign_channel": "Channel of the campaign"
},
"user_attributes": {
"moengage_user_id": "MoEngage Internal User ID"
},
"device_attributes": {
"moengage_device_id": "MoEngage Device ID"
}
}
]
}
```
### Schema
| | |
| - | - |
| **Key Name** | **Description** |
| app_name | The name of your app on MoEngage. |
| source | The source from which this event was captured. |
| moe_request_id | Unique MoEngage API Request ID. |
| events | Events object array. |
### Event Object Schema
| | |
| - | - |
| **Key Name** | **Description** |
| event_name | The display name of the event. |
| event_code | The event code or the internal name of the event. |
| event_uuid | Unique code of the event that was captured. |
| event_time | The time the event occurred, as a UTC epoch timestamp in seconds. This is the Event Time, not the time MoEngage received the event. For more information, see [Event Time and Received Time](/docs/user-guide/data/event-data/event-time-and-received-time). |
| event_type | The type of event:
ACQUISITION
CAMPAIGN_ACTIVITY
LIFECYCLE
REACHABILITY
UNINSTALL
USER_ACTION_EVENT
|
| source | The source from which this event was captured. |
| push_id | The recipient’s device push token. This attribute will only be sent for PUSH-related Campaign Events. |
| email_id | The recipient's email ID. This attribute will only be sent for EMAIL-related Campaign Events. |
| mobile_number | The recipient's mobile number. This attribute will only be sent for SMS-related Campaign Events. |
| uid | MoEngage customer_id to uniquely identify a user in MoEngage. |
| event_attributes | Event properties object in this format: attribute_name: value |
| user_attributes | User properties object in this format: attribute_name: value |
| device_attributes | Device attributes object in this format: attribute_name: value |
#### **Event Properties Object**
The event properties might vary according to the event being exported. Refer to the event definitions below to see which attributes are exported.
#### **User Properties Object**
The user properties might vary according to your configuration. Refer to the user properties definitions below to see which attributes are exported.
* moengage_user_id - This attribute is always exported. This is the internal MoEngage ID of your user.
#### **Device Attributes Object**
The device attributes might vary according to your configuration. Refer to the device properties definitions below to see which attributes are exported.
* moengage_device_id - This attribute is always exported. This is the internal Device ID of your user.
## Data Warehouses Destinations
MoEngage will create a single table in your Data warehouse and export all your selected events to that table.
### Amazon Redshift
We will create a table called `moengage_events`.
### Snowflake
We will create a table called `moe_events_`.
### Table Structure
The overall structure of the table will remain fixed for all types of events. Any new user property or event property that is exported will be part of the `user_attributes` or `event_attributes` column respectively. All the events will be dumped in a single table containing all necessary information such as event names, event times, etc for easy analysis.
We follow the below generic schema:
* Any column beginning with *event_attributes\_* contains an event property. This will be followed by the event property name like *event_attributes_campaign_name*.
* Any column beginning with *user_attributes\_* contains a user property. This will be followed by the user property name like *user_attributes_moengage_user_id*.
* Any column beginning with device_attributes contains a device attribute. This will be followed by the device attribute name like *device_attributes_moengage_device_id*.
* We also have three JSON (or equivalent) fields called *event_attributes*, *user_attributes*, and *device_attributes*. Each of these fields contains raw JSON fields in the form of a dictionary.
| | | | |
| - | - | - | - |
| **Key Name** | **Type** | **Description** | **NULL** |
| app_name | character varying(256) | The name of your app on MoEngage. | NOT NULL |
| device_attributes | Either of:
super
variant
| Device attributes dictionary in JSON object format: JSON `{ ` `"attribute": "value", ` `"attribute": "value" ` `}` | NULL |
| device_attributes\_ moengage_device_id | character varying(256) | This is the internal Device ID of your user. | NULL |
| email_address | character varying(256) | The recipient's email ID. This attribute will only be sent for EMAIL-related Campaign Events. | NULL |
| event_attributes | Either of:
super
variant
| Event properties dictionary in JSON object format: JSON `{ ` `"attribute": "value", ` `"attribute": "value" ` `}` | NULL |
| event_attributes\_ app_version | character varying(256) | Refer to common event properties. | NULL |
| event_attributes\_ campaign_channel | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ campaign_id | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ campaign_name | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ campaign_type | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ first_session | boolean | Refer to common event properties. | NULL |
| event_attributes\_ locale_id | character varying(256) | Tracked when the campaign is sent using Localization. Represents the id of the message locale. | NULL |
| event_attributes\_ locale_name | character varying(256) | Tracked when the campaign is sent using Localization. Represents the name of the message locale. | NULL |
| event_attributes\_ logged_in_status | character varying(256) | Refer to common event properties. | NULL |
| event_attributes\_ parent_campaign_id | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ parent_flow_id | character varying(256) | The flow ID. Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ parent_flow_name | character varying(256) | The name of the flow. Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ platform | character varying(256) | Refer to common event properties. | NULL |
| event_attributes\_ readable_campaign_id | character varying(256) | Refer to common event properties of campaign-related events. | NULL |
| event_attributes\_ sdk_version | character varying(256) | Refer to common event properties. | NULL |
| event_attributes\_ timestamp | Either of: - bigint - timestamp_ntz | Refer to common event properties. | NULL |
| event_attributes\_ url | character varying(256) | Tracked when display filter is selected in the in-app campaign. | NULL |
| event_attributes\_ variation_id | character varying(256) | Represents the id of message variation. Refer to common event properties of campaign-related events. | NULL |
| event_code | character varying(256) | The event code or the internal name of the event. | NOT NULL |
| event_name | character varying(256) | The display name of the event. | NOT NULL |
| event_source | character varying(256) | The source from which this event was captured. | NOT NULL |
| event_time | Either of:
bigint
timestamp_ntz
| The time the event occurred, in UTC. This is the Event Time, not the time MoEngage received the event. For more information, see [Event Time and Received Time](/docs/user-guide/data/event-data/event-time-and-received-time). | NOT NULL |
| event_type | character varying(256) | The type of event: - ACQUISITION - CAMPAIGN_ACTIVITY - LIFECYCLE - REACHABILITY - UNINSTALL - USER_ACTION_EVENT | NOT NULL |
| event_uuid | character varying(256) | Unique code of the event that was captured. | NOT NULL |
| mobile_number | character varying(256) | The recipient's mobile number. This attribute will only be sent for SMS-related Campaign Events. | NULL |
| push_id | character varying(256) | The recipient’s device push token. This attribute will only be sent for push-related Campaign Events. | NULL |
| uid | character varying(256) | MoEngage customer_id to uniquely identify a user in MoEngage. | NULL |
| user_attributes | Either of:
super
variant
| User properties dictionary in JSON object format: JSON `{ ` `"attribute": "value", ` `"attribute": "value" ` `}` | NULL |
| user_attributes\_ moengage_user_id | character varying(256) | This is the internal MoEngage ID of your user. | NULL |
### Google BigQuery (Generic)
MoEngage exports events to your BigQuery tables via GCS Buckets using the BigQuery Transfer File service. There are two ways you can create a table for your events in BigQuery:
1. Create a table specific to your exported events by using the schema of your exported files.
2. Create a table that has a generic schema.
If you want to create a generic schema and are unsure of your events, you can use this schema:
JSON
```json wrap theme={null}
[
{
"mode": "NULLABLE",
"name": "db_name",
"type": "STRING"
},
{
"mode": "NULLABLE",
"name": "export_hour",
"type": "INTEGER"
},
{
"mode": "NULLABLE",
"name": "export_day",
"type": "DATE"
},
{
"mode": "NULLABLE",
"name": "event",
"type": "JSON"
},
{
"mode": "NULLABLE",
"name": "app_name",
"type": "STRING"
},
{
"mode": "NULLABLE",
"name": "export_doc_id",
"type": "STRING"
}
]
```
## Cloud Storages Destinations
MoEngage will export compressed files to your cloud storage.
### Generic Export Schema
* **File format:** .json.gz
* Each uncompressed file will have newline-delimited events in JSON format (each line is a single event).
* Each file can have multiple types of events in them. We don’t create a single file for each type of event.
* The event JSON format is described below:
JSON
```json wrap theme={null}
{
"app_name": "export_sample_files",
"export_hour": "13",
"export_doc_id": "63a186ac116xxxxb254fbb23",
"db_name": "export_sample_files",
"event": {
"email_id": "john.doe@example.com",
"uid": "user1",
"event_type": "CAMPAIGN_EVENT",
"event_code": "MOE_EMAIL_SENT",
"event_name": "Email Sent",
"user_attributes": {
"moengage_user_id": "6387301exxxxxx6c828aee2c"
},
"event_source": "MOENGAGE",
"event_attributes": {
"campaign_name": "Test email1",
"campaign_type": "GENERAL",
"moe_campaign_channel": "Email",
"moe_delivery_type": "One Time",
"campaign_id": "63918ad73bbxxxxxxb728ede",
"campaign_channel": "EMAIL"
},
"event_uuid": "ffbxxedc-4eb8-xxxx-xxxx-a0c87eaxxxxx",
"event_time": 1668600246,
"device_attributes": {
"moengage_device_id": "test_device_id"
}
},
"export_day": "2022-12-21"
}
```
### Schema
| | |
| - | - |
| **Key Name** | **Description** |
| app_name | The name of your app on MoEngage. |
| export_hour | The hour at which the export was created. |
| export_doc_id | The document ID of the export. |
| db_name | The name of your app on MoEngage. |
| export_day | The day on which the export was created. |
| event | Event object. |
### Event Object Schema
| | |
| - | - |
| **Key Name** | **Description** |
| event_name | The display name of the event. |
| event_code | The event code or the internal name of the event. |
| event_uuid | Unique code of the event that was captured. |
| event_time | The time the event occurred, as a UTC epoch timestamp in seconds. This is the Event Time, not the time MoEngage received the event. For more information, see [Event Time and Received Time](/docs/user-guide/data/event-data/event-time-and-received-time). |
| event_type | The type of event:
ACQUISITION
CAMPAIGN_ACTIVITY
LIFECYCLE
REACHABILITY
UNINSTALL
USER_ACTION_EVENT
|
| event_source | The source from which this event was captured. |
| push_id | The recipient’s device push token. This attribute will only be sent for PUSH-related Campaign Events. |
| email_id | The recipient's email ID. This attribute will only be sent for EMAIL-related Campaign Events. |
| mobile_number | The recipient's mobile number. This attribute will only be sent for SMS-related Campaign Events. |
| uid | MoEngage customer_id to uniquely identify a user in MoEngage. |
| event_attributes | Event properties dictionary in this format: attribute_name: value |
| user_attributes | User properties dictionary in this format: attribute_name: value |
| device_attributes | Device attributes dictionary in this format: attribute_name: value |
#### **Event Properties Object**
The event properties might vary according to the event being exported. Refer to the event definitions below to see which attributes are exported.
#### **User Properties Object**
The user properties might vary according to your configuration. Refer to the user properties definitions below to see which attributes are exported.
* moengage_user_id - This attribute is always exported. This is the internal MoEngage ID of your user.
#### **Device Attributes Object**
The device attributes might vary according to your configuration. Refer to the device properties definitions below to see which attributes are exported.
* moengage_device_id - This attribute is always exported. This is the internal Device ID of your user.
### Amazon S3
MoEngage will create a pre-defined file path inside the folder you specify while setting up the S3 Exports.
We will dump files in the following locations:
*s3://\/\[\\_]\/export_day=``/event_exports\_\.json.gz*
### Google Cloud Storage
MoEngage will create a pre-defined file path in your GCS Bucket. We will dump files in the following locations:
*gs\://\/event-exports/\/\/export_day=YYYY-MM-DD/export_hour=HH/``.json.gz*
### SFTP
MoEngage will create a pre-defined file path on your SFTP Server. We will dump files in the following locations:
*sftp\://\/\[\/]\/export_day=``/event_exports\_\.json.gz*
# Events Exported
All MoEngage-tracked attributes start with moe\_.
## User Properties
> [tab] Lifecycle
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | First Seen | cr_tcr_t | First seen time of the user. The time when the user is created in MoEngage systems. |
> | LTV | t_rev | Life time value of the user. This is the total sum of revenue attributes present in the *Conversion goal* event performed by a user. LTV is updated every time the conversion goal event is executed by the user. |
> | Last Seen | u_l_a | The time of the most recent App/Site Open event for the user. |
> | No. of Conversions | t_trans | No. of conversion events done by the user, Conversion Goal can be modified on the settings page. |
> | No. of Sessions | u_s_c | No.of sessions done by the user. This is the number of times a user has performed the App/Site Open event. |
> [tab] Acquisition and Uninstall
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | Campaign Name | campaign_name | Name of the campaign advertisement through which the user installed the app. |
> | Publisher Name | publisher_name | Name of the Publisher through which the user installed the app. |
> | Install Status | installed | Current status of the user, If the user has the app installed on his device or user has been active on the web device. |
> | Uninstall Time | uninstall_time | The time when our system found a user has uninstalled the app. |
> | Device ReInstall | moe_d_r_ins | Tracked when a reinstall is detected on a device. |
> | User ReInstall | moe_u_r_ins | Tracked when an identified user has reinstalled the app. |
> [tab] Reachability and Localization
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | Push Opt In Status (iOS) | PUSH_PREFERENCE | Push permission status of a user on an iOS device. |
> | Reachability Push Android | moe_rsp_android | Reachability status code for Android Push Notifications. |
> | Reachability Push iOS | moe_rsp_ios | Reachability Push iOS is True (200) when the user is reachable on at least one iOS device. |
> | Reachability Push Web | moe_rsp_web | Reachability Push Web is True (200) when the user is reachable on at least one web device. |
> | Web Push Subscription Page URL | Web Subscription URL | Page URL of the web page on which a user subscribed to web push. Use it to find where the subscriptions are happening on your website or categorize your subscribers to send targeted notifications. |
> | Web Push Subscription Status | moe_sub_w | Denotes the web push subscription status of a user - True / False. Use it to find your aggregate subscribers and users who unsubscribed after subscribing once. |
> | Last Known City | moe_ip_city | This attribute is based on the user's last known probable location, which is derived using reverse IP lookup. |
> | Last Known Country | moe_ip_country | |
> | Last Known Pincode/Zipcode | moe_ip_pin | |
> | Last Known State | moe_ip_subdivision | |
> | User TimeZone Offset (Mins) | moe_dtzo | Difference of the user time zone with respect to GMT in minutes. |
> [tab] Device Data and Email Suppression Type
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | Hard Bounce | moe_hard_bounce | Denotes if emails to the user have hard bounced. This value resets to its default state (false) whenever the email ID on the user profile is changed. |
> | Spam | moe_spam | Denotes if the user has reported an email as spam. |
> | Unsubscribe | moe_unsubscribe | Denotes if the user has unsubscribed from an email. |
> | Advertising Identifier | ADVERTISING_IDENTIFIER | Advertising Identifier of the device on which the app is installed. This is only available for iOS & Windows. |
> | Browser Details | moe_w_ds | Browser details of web users include - Platform, Browser, and Manufacturer. |
> | Google Advertising ID | MOE_GAID | Advertising Identifier of the device on which the app is installed. This is only available for Android. |
> | Mobile User | moe_mweb | Denotes if the user accessed the website on mobile. |
> [tab] Tracked Standard Attributes
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | Birthday | u_bd | Birth date of the user. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client. |
> | Creation Source | moe_it | Denotes the source through which a user was created. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client. |
> | Email (Standard) | u_em | Email address of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client |
> | Email Unsubscribed Categories | moe_em_unsub_categories | Denotes the List of email categories user has unsubscribed. |
> | First Name | u_fn | First Name of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Gender | u_gd | Gender of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | ID | uid | Unique Id that the app has set for a user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Last Name | u_ln | Last Name of the User. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Locale Country | LOCALE_COUNTRY_DISPLAY | The country of the user derived from the device locale settings, for example, The United States. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Locale Language | LOCALE_LANGUAGE_DISPLAY | The language of the user derived from device locale settings, for example, English. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Location | geo | Latitude and Longitude of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Mobile Number (Standard) | u_mb | Mobile Number of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. |
> | Name | u_n | Full Name of the user. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client. |
> | SMS Subscription Status | moe_sms_subscription | SMS Subscription Status of the user. This is a standard attribute where the SMS Subscription Status is tracked based on the user's subscription preferences. |
## Device Attributes
These are properties derived from your users' device data. Note that these attributes will still be shown under user properties in your exports.
> [tab] iOS
>
> | **Key Name** | **Attribute Key** | **Description** | **Optional** |
> | - | - | - | - |
> | Advertising Identifier (iOS & Windows) | ADVERTISING_IDENTIFIER | An alphanumeric string unique to each device used only for serving advertisements) - [IDFA](https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier "https://developer.apple.com/documentation/adsupport/asidentifiermanager/1614151-advertisingidentifier") iOS version 14.5 and above Advertisement identifier will be tracked only if the developer asked permission for it. Below iOS 14.5 it is tracked automatically. | Yes |
> | IDFV | device_IDFV | An alphanumeric string that uniquely identifies a device to the app’s vendor - [IDFV (identifier for vendor)](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor "https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor") | Yes |
> | OS Version | os_ver | Current iOS version of the device | No |
> | Device Timezone | moe_dtzo | Device Timezone | No |
> | model | MODEL | | No |
> [tab] Android
>
> | **Key Name** | **Attribute Key** | **Description** | **Optional** |
> | - | - | - | - |
> | OS Version | OS_VERSION | Current Android version of the device | Yes |
> | API level | OS_API_LEVEL | Os API level/API version: Android API version 16, 20 etc | No |
> | Manufacturer | manufacturer | Device Manufacturer e.g. Samsung | Yes |
> | Google Advertising Identifier(GAID) | MOE_GAID | GAID of the device | Yes |
> | Device Width | width | Device width in pixel | Yes |
> | Device Height | height | Device height in pixel | Yes |
> | Android Id | android_id | -- | Yes |
> | Network Type | networkType | Device Network Type e.g. 3G, 5G | No |
> | Device Timezone | moe_dtzo | Device Time Zone e.g. PST, IST, GMT | No |
> [tab] Web
>
> | **Key Name** | **Attribute Key** | **Description** | **Optional** |
> | - | - | - | - |
> | os | os_key | Web / MWeb | No |
> | os_platform | os_platform | User Agent. Information about the browser. | No |
> | os_ver | | Browser Name | No |
> | model | MODEL | Browser Name | No |
> | device_ts | device_ts | Device Timestamp | No |
> | device_tz | device_tz | Device Timezone | No |
> | push_id | push_id | Push token generated by SDK | No |
> | mi_push_id | mi_push_id | Push ID for MI Devices | No |
## MoEngage (Standard) Events
MoEngage, by default, tracks a few standard events.
### Common Event Properties
These attributes are automatically tracked when MoEngage captures a standard event.
> [tab] SDK Events
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | App Version | appVersion | App version on which this event was tracked. |
> | SDK Version | sdkVersion | MoEngage SDK version on which this event was tracked. |
> | Platform | os | OS on which this event was tracked. |
> | utm_source | moe_source | Source of a campaign e.g. search engine, newsletter, MoEngage. |
> | utm_medium | moe_source_medium | Medium of a campaign e.g. CPC, email, push. |
> | utm_campaign | moe_source_campaign_name | UTM Campaign name e.g. Summer sale |
> | utm_id | moe_source_campaign_id | UTM campaign ID e.g. 12DSW55 |
> | utm_content | moe_source_content | Content information of the campaign e.g. logoclick |
> | utm_term | moe_source_term | Term used for paid search e.g. red+shirt |
> | First Session | moe_first_visit |
Generated for all the events tracked with MoEngage web SDK.
Value is True for the first session of the user only.
|
> | Logged In Status | moe_logged_in_status |
Generated for all the events tracked with MoEngage web SDK.
Value is True if the user has logged in on the device.
|
> [tab] Campaign Events
>
> | **Key Name** | **Attribute Key** | **Description** |
> | - | - | - |
> | Campaign Id | campaign_id | Id of the campaign associated with this event. |
> | Campaign Name | campaign_name | Represents the name of the campaign, the message was part of. |
> | Campaign Channel | campaign_channel | Represents the channel via which the campaign/message was sent. |
> | Campaign Type | campaign_type | Represents the type of campaign, the message was part of. |
> | Campaign Tags | moe_campaign_tags | Represents the comma-separated values of one or more tags that are attached to a campaign. |
> | Readable Campaign Id | moe_campaign_id | Represents the id of the campaign, the message was part of. |
> | Parent Campaign id | parent_campaign_id | Tracked when a periodic campaign is run. Represents the campaign ID of the parent periodic campaign, child instances of which are re-run on a recurring basis. |
> | Parent Flow Id | parent_flow_id | Tracked when the journey campaign is run. Represents the Flow ID of the parent journey campaign. - This attribute will only be sent for Flows-related events. |
> | Parent Flow Name | parent_flow_name | Tracked when the journey campaign is run. Represents the flow name of the parent journey campaign. - This attribute will only be sent for Flows-related events. |
> | Locale Id | locale_id | Tracked when the campaign is sent using Localization. Represents the id of the message locale. |
> | Locale Name | locale_name | Tracked when the campaign is sent using Localization. Represents the name of the message locale. |
> | Variation Id | variation_id | Tracked when a campaign is sent using A/B Testing. Represents the id of message variation. |
### Standard Events
These events are automatically tracked with MoEngage.
> [tab] Lifecycle Events
>
> | **Event Name** | **Event Code** | **Description** | **Platform** |
> | - | - | - | - |
> | App/Site Opened | MOE_APP_OPENED | Tracked when a user session begins on the app or website. Also, this is tracked only if the time difference between the user's Last Active Time and App/Site Open Time is more than 30 min. | Android, iOS, Web |
> | Viewed Web Page | MOE_PAGE_VIEWED | Tracked when a user visits a web page. Select page URL as an event property to find the number of users visiting a particular page or use it to set up a Drop-off capture" Event-Triggered Web Push. | Web |
> | App Exit | MOE_APP_EXIT | Tracked whenever the App goes to background. | Android, iOS |
> | User Logout | MOE_LOGOUT | Tracked when a user Logs out of the app/site or user reset. | Android, iOS, Web |
> | Push ID Register Android | TOKEN_EVENT | Tracked when the MoEngage system registers the push ID for Android devices. Attribute registered_by has the status. | Android |
> | User Merged | MOE_USER_MERGED | Tracked for a known user whenever a MoEngage user object is merged with it. | User Merging |
> | App Update | UPDATE | Tracked when a user updates the App. | Android, iOS |
> [tab] Acquisition and Uninstall Events
>
> | **Event Name** | **Event Code** | **Description** | **Platform** |
> | - | - | - | - |
> | Install | INSTALL | Tracked when a user installs the app on the device. | Android, iOS |
> | Device ReInstall | REINSTALL | Tracked when a reinstall is detected on a device. | Android, iOS |
> | Device Uninstall | Device Uninstall | Tracked when a user uninstalls the app on a device. | Android, iOS |
> | User ReInstall | MOE_USER_REINSTALL | Tracked when a reinstall is detected for an identified user in MoEngage. | Android, iOS |
> [tab] Reachability Events
>
> | **Event Name** | **Event Code** | **Description** | **Platform** |
> | - | - | - | - |
> | Accepted Web Push Soft-ask | MOE_WEB_OPTIN_ACCEPTED | Tracked when a user accepts the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
> | Closed Web Push Soft-ask | MOE_WEB_OPTIN_CLOSED | Tracked when a user closes the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
> | Denied Web Push Subscription | MOE_OPT_IN_BLOCKED | Tracked when a user denies receiving push notifications on the Web. | Web |
> | Dismissed Web Push Subscription | MOE_OPT_IN_DISMISSED | Tracked when a user dismisses the push subscription prompt. | Web |
> | Overlay clicked in 1-click HTTP subscription | MOE_HTTP_OVERLAY_CLICKED | Tracked when a user clicks a Subscription Message on your website as part of the HTTP Push Subscription flow. | Web |
> | Overlay shown in 1-click HTTP subscription | MOE_HTTP_OVERLAY_SHOWN | Tracked when a user views a Subscription Message on your website as part of the HTTP Push Subscription flow. | Web |
> | Subscribed to Web Push | MOE_USER_SUBSCRIBED | Tracked when a user is subscribed to Web Push Notifications. Use it to find the day-wise count of subscribers or set up a Welcome" Event-Triggered Web Push. | Web |
> | Unsubscribed from Web Push | MOE_WEB_UNSUBSCRIBED | Tracked when a user directly unsubscribes from the website/chrome settings or GCM communicates that a push token is invalid. | Web |
> | Viewed Web Push Soft-ask | MOE_WEB_OPTIN_BANNER_LOAD | Tracked when a user views the Push Permission Soft-ask on your website as part of the 2-step Push Opt-in mechanism. | Web |
> [tab] Campaign Activity Events
>
> | **Event Name** | **Event Code** | **Description** | **Platform** |
> | - | - | - | - |
> | Allowed Web Push Subscription | MOE_OPT_IN_ALLOWED | Tracked when a user allows receiving push notifications on the Web. | Web |
> | Displayed Web Push Subscription | MOE_OPT_IN_SHOWN | When hard ask is shown to the user. | Web |
> | Onsite Message Template clicked | MOE_ONSITE_MESSAGE_CLICKED | On clicking the Onsite Messaging template. | Web |
> | Onsite Message Template shown | MOE_IN_APP_SHOWN | On a load of Onsite Messaging template. | Web |
> | Card Clicked | MOE_CARD_CLICKED | Tracked when the user clicks the Card in the App Inbox. | Android, iOS |
> | Card Delivered | MOE_CARD_DELIVERED | Tracked when a Card is delivered to the App Inbox after the user has opened the Inbox. | Android, iOS |
> | Card Sent | MOE_CARD_SENT | Tracked when a Card notification is sent to the user, doesn't indicate if the notification is delivered to the App Inbox. | Android, iOS |
> | Card Viewed | MOE_CARD_IMPRESSION | Tracked when the user views a Card or scrolls down to it in the App Inbox. | Android, iOS |
> | Connector Sent | WEBHOOK_SENT | Tracked when a connector was sent successfully. | Connector |
> | Email Bounced | MOE_EMAIL_HARD_BOUNCE | Tracked when our system finds an email is hard bounced. Typically happens when an email address doesn't exist. This is tracked uniquely for every user based on the user ID. | Email |
> | Email Clicked | MOE_EMAIL_CLICK | Tracked when a user clicks on any link in the email. | Email |
> | Email Complained | MOE_EMAIL_SPAM | Tracked when a user marks the email as spam. | Email |
> | Email Deferred | MOE_EMAIL_DEFERRED | Tracked when the receiving server delayed acceptance of the email message. | Email |
> | Email Delivered | MOE_EMAIL_DELIVERED | Tracked when an email is delivered to the user. | Email |
> | Email Dropped | MOE_EMAIL_DROP | Tracked when an email is dropped. Email is dropped, when it's part of the bounce list, the unsubscribe list, or the spam report list. | Email |
> | Email Opened | MOE_EMAIL_OPEN | Tracked when a user opens an email. | Email |
> | Email Sent | MOE_EMAIL_SENT | Tracked when our system sends an email to a user. | Email |
> | Email Soft Bounced | MOE_EMAIL_SOFT_BOUNCE | Tracked when our system finds an email is soft-bounced. Typically happens when there is a temporary delivery issue. This is tracked uniquely for every user based on the user ID. | Email |
> | Email Subscription Category Updated | MOE_EMAIL_SUBSCRIPTION_UPDATED | Tracked when a user updates their preferences for email subscription categories. | Email |
> | Email Unsubscribed | MOE_EMAIL_UNSUBSCRIBE | Tracked when a user unsubscribes from receiving emails. | Email |
> | Email Unsubscribe Drop | MOE_EMAIL_DROPPED_UNSUBSCRIBE | Tracked when an email is dropped because the user is part of an unsubscribe list. This is tracked at SendGrid. This event is currently under BETA. | Email |
> | Email Viewed in Browser | MOE_EMAIL_VIB | Tracked when a user clicks on the view in the browser link present in the email. | Email |
> | Facebook Audience Synced | MOE_FB_AUDIENCE_SYNC | Tracked when Facebook API returns 2xx response for add or delete request to an audience. | Facebook |
> | Google Ads Audience Synced | MOE_GOOGLE_ADS_AUDIENCE_SYNC | Tracked when the Google Ads API returns a 2xx response for an add or delete request to an audience. | Google Ads Audience |
> | In-App Clicked Android | MOE_IN_APP_CLICKED | Tracked when a user clicks In-App message on an Android device. | Android |
> | In-App Clicked iOS | iOS_IN_APP_CLICKED | Tracked when a user clicks In-App message on an iOS device. | iOS |
> | In-App Clicked Windows | WINDOWS_IN_APP_CLICKED | Tracked when a user clicks In-App message on a Windows device. | Windows |
> | In-App Closed Android | MOE_IN_APP_DISMISSED | Tracked when a user dismisses an In-App message by clicking on the close button on an Android device. | Android |
> | In-App Closed iOS | iOS_IN_APP_CLOSE_CLICKED | Tracked when a user dismisses an In-App message by clicking on the close button on an iOS device. | iOS |
> | In-App Closed Windows | WINDOWS_IN_APP_CLOSE_CLICKED | Tracked when a user dismisses an In-App message by clicking on the close button on a Windows device. | Windows |
> | In-App Shown Android | MOE_IN_APP_SHOWN | Tracked when an In-App message is shown to the user on an Android device. | Android |
> | In-App Shown iOS | iOS_IN_APP_SHOWN | Tracked when an In-App message is shown to the user on an iOS device. | iOS |
> | In-App Shown Windows | WINDOWS_IN_APP_SHOWN | Tracked when an In-App message is shown to the user on a Windows device. | Windows |
> | Notification Clicked Android | NOTIFICATION_CLICKED_MOE | Tracked when a user clicks a notification on an Android device. | Android |
> | Notification Clicked iOS | NOTIFICATION_CLICKED_IOS_MOE | Tracked when a user clicks a notification on an iOS device. | iOS |
> | Notification Clicked Web | NOTIFICATION_CLICKED_WEB_MOE | Tracked when a user clicks a notification on the browser. | Web |
> | Notification Clicked Windows | NOTIFICATION_CLICKED_WINDOWS_MOE | Tracked when a user clicks a notification on a Windows device. | Windows |
> | Notification Dismissed iOS | NOTIFICATION_DISMISSED_IOS_MOE | Tracked when the user dismisses the notification on an iOS device. | iOS |
> | Notification Received Android | NOTIFICATION_RECEIVED_MOE | Tracked when a user receives a notification on an Android device. | Android |
> | Notification Received iOS App Active | NOTIFICATION_RECEIVED_IOS_APP_ACTIVE | Tracked when the app is in foreground and the user receives the notification on iOS. | iOS |
> | Notification Received iOS | NOTIFICATION_RECEIVED_MOE | Tracked when a user receives a notification on an iOS device. | iOS |
> | Notification Received Web | NOTIFICATION_RECEIVED_WEB_MOE | Tracked when a user receives a notification on a browser. | Web |
> | Notification Sent Windows | | Tracked when a user receives a notification on a Windows device. | Windows |
> | Notification Sent iOS | n_i_s | Tracked when a user receives a notification on an iOS device. | iOS |
> | Notification Swiped Android | NOTIFICATION_CLEARED_MOE | Tracked when a notification is dismissed by the user with a swipe gesture on Android. | Android |
> | On-site Message Shown | MOE_ONSITE_MESSAGE_SHOWN | Tracked when an on-site messaging campaign is shown to a user. | Web |
> | On-site Message Clicked | MOE_ONSITE_MESSAGE_CLICKED | Tracked when an on-site messaging campaign is clicked by a user. | Web |
> | On-site Message Closed | MOE_ONSITE_MESSAGE_DISMISSED | Tracked when an on-site messaging campaign is closed by a user. | Web |
> | Push Preference Changed iOS | MO_PUSH_PREFERENCE_CHANGED | Tracked when iOS device push preference is changed. It has a modified status. | iOS |
> | Web Personalization Message Shown | MOE_WEBP_MESSAGE_SHOWN | Tracked when a web personalization campaign is shown to a user. | Web |
> | Web Personalization Message Clicked | MOE_WEBP_MESSAGE_CLICKED | Tracked when a web personalization campaign is clicked by a user. | Web |
> | Web Personalization Message Closed | MOE_WEBP_MESSAGE_DISMISSED | Tracked when a web personalization campaign is closed by a user. | Web |
> | Web Personalization Message Delivered | MOE_WEBP_MESSAGE_DELIVERED | Tracked when a web personalization campaign is delivered to the user. | Web |
> | SMS Delivered | SMS_DELIVERED | Tracked when our system receives a delivery receipt for the SMS sent to a user. | SMS |
> | SMS Delivery Failed | MOE_SMS_DELIVERY_FAILED | Tracked when our system receives a delivery failure receipt for the SMS sent to a user. | SMS |
> | SMS Sent | SMS_SENT | Tracked when our system sends an SMS to a user. | SMS |
> | SMS Clicked | MOE_SMS_CLICKED | Tracked when a user clicks on any of the links in the SMS message body. | SMS |
> | User Entered Flow | USER_ENTERED_FLOW | Tracked when a user falls in the target audience and has qualified for the entry in the Flow. | Flows |
> | User Exited Flow | USER_EXITED_FLOW | Tracked when a user exits from a Stop Cell of the Flow. | Flows |
> | WhatsApp Message Clicked | MOE_WHATSAPP_CLICKED | Tracked when a WhatsApp Message is read by the user. It will only be available for users who have read receipts enabled. | Flows/Campaign Channels |
> | WhatsApp Message Delivered | MOE_WHATSAPP_DELIVERED | Tracked when a WhatsApp Message is delivered to a user. | Flows/Campaign Channels |
> | WhatsApp Message Delivery Failed | MOE_WHATSAPP_DELIVERY_FAILED | Tracked when the provider failed to send/deliver a WhatsApp Message for a user. | Flows/Campaign Channels |
> | WhatsApp Message Read | MOE_WHATSAPP_READ | Tracked when a WhatsApp Message is read by the user. It will only be available for users who have read receipts enabled. | Flows/Campaign Channels |
> | WhatsApp Message Sent | MOE_WHATSAPP_SENT | Tracked when a WhatsApp message is sent to a user. | Flows/Campaign Channels |
> [tab] Control Group Events
>
> | **Event** | **Scope** | **Description** |
> | - | - | - |
> | `MOE_CAMPAIGN_CONTROL_GROUP` | Global Control Group | Raised when a user is added to the **Global Control Group** (GCG) — i.e., when the GCG is created or updated. |
> | `MOE_USER_REMOVED_FROM_CONTROL_GROUP` | Global Control Group | Raised when a user is removed from the **Global Control Group** as it's updated. |
> | `MOE_CAMPAIGN_USER_REMOVED_DUE_TO_CONTROL_GROUP` | GCG or campaign-specific | Raised **during a campaign send**, when a user who belongs to either the Global Control Group or a campaign-specific control group is excluded from that send. Carries a `control_type` attribute indicating which control group (GCG vs. campaign-specific) caused the exclusion. |
## User-Defined (Custom) Events
### Common Event Properties
These attributes are automatically tracked when you track a custom/user-defined event.
| | | |
| - | - | - |
| Key Name | Attribute Key | Description |
| App Version | appVersion | App version on which this event was tracked. |
| SDK Version | sdkVersion | MoEngage SDK version on which this event was tracked. |
| MOE Event Category | moe_event_category | Represents the Event category - Example: Tracked User Events |
| MOE Event Source | moe_event_source | Represents the Event Source - Example: s2s, INTERNAL |
# BigQuery Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/bigquery-exports
Export campaign interaction events from MoEngage to Google BigQuery. Follow the step-by-step guide to set up permissions and configuration.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
[BigQuery](https://cloud.google.com/bigquery) is a fully managed, serverless data warehouse available on the Google Cloud Platform (GCP). It allows you to perform complex analytics on terabytes of data in real time without managing infrastructure.
## How Does MoEngage Work with BigQuery?
The MoEngage and BigQuery integration directly transfers user and event data to Google BigQuery for advanced analytics.
> [!NOTE]
>
> This is a direct integration and does not require Google Cloud Storage (GCS) to export your data.
## Integration
> [!TIP]
>
> * Ensure you have a BigQuery account with the required permissions to create/edit BigQuery instances, roles, and policies.
> * It is optional to create a new user. However, you must have access to create a new user in your BigQuery database.
> * Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery#step-2-enable-ip-whitelisting).
> * Ensure you have a BigQuery connection in the App Marketplace.
To create a BigQuery connection, refer to [Google BigQuery](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery).
### Export Events from MoEngage to BigQuery
#### Step 1: Ensure Your User's Assigned Role Has Required Permissions
To successfully set up and execute a BigQuery export, your service account or user must have the following permissions based on the action being performed:
* **To Create a Connection**: To establish a new BigQuery connection within the MoEngage App Marketplace, the user must have the *BigQuery Data Viewer* and *BigQuery Job User* roles. This allows MoEngage to validate the project and dataset details. For more information, refer [here](/docs/user-guide/data/imports/setting-up-a-data-warehouse-import).
* **To Perform Exports**: To execute the actual data transfer, your service account must be assigned the *BigQuery Data Editor* role. This grants MoEngage the necessary permissions to read and write data to your specific BigQuery tables.
#### Step 2: Add a New BigQuery Export in the MoEngage App Marketplace
> [!NOTE]
>
> * For a full list of events and attributes, refer to the [Data Exports Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * The `event_time` of exported events is always in UTC.
> * MoEngage does not currently support exporting historical data.
To add a new BigQuery export, perform the following steps:
1. On the left navigation menu in the MoEngage UI, click **App marketplace**.
2. On the App Marketplace page, search for **BigQuery**. 
3. Click the **Google BigQuery** tile.
4. On the Google BigQuery page, go to the **Integrate** tab and click **+Add Export**.
5. Enter the following details:
| Field | Required | Description |
| - | - | - |
| **Export name** | Yes | Type a name for the BigQuery export. Ensure your export name contains at least three characters. |
| **BigQuery connection** | Yes | Select your BigQuery connection. |
| **Dataset ID** | Yes | Select the specific dataset in BigQuery where your data will be exported. |
| **Table name** | Optional | Enter the name for the export table. If left blank, MoEngage creates a name for you with the prefix *moe_events*. **Note:** To avoid errors, allow MoEngage to automatically create this table. |
| **User Properties** | Optional | Select the specific user properties you want to include in the export. |
| **Select events** | Yes | Select the events to export to BigQuery. You can choose to export all events, including existing and new events coming into MoEngage, or manually select specific events to export. |
|  | | |
6. Click **Save export**.
Now, MoEngage populates the newly created table with events every hour.
#### Export Process and Frequency
After you save the export, MoEngage creates a destination table in your dataset. New event data is then appended to this same table at hourly intervals:
**Initial action**: MoEngage creates the table when the first export is triggered.
**Recurring action**: MoEngage adds (appends) data to the same table every hour.
#### Sample Table Structure
If you do not specify a table name in the export configuration, MoEngage creates a single table in your dataset using the following format:\
`moe_events_`
> [!NOTE]
>
> This table is created once per connection. All hourly exports and different event types configured under this connection are consolidated and appended to this specific table.
The overall structure of the table remains fixed for all event types. Any new user property or event property that is exported will be included in the user_attributes or event_attributes column, respectively. All events are consolidated in a single table containing necessary information, such as event names and event times, for easy analysis:
| Field | Type | NULL |
| - | - | - |
| app_name | VARCHAR | NOT NULL |
| event_name | VARCHAR | NOT NULL |
| event_code | VARCHAR | NOT NULL |
| event_uuid | VARCHAR | NOT NULL |
| event_time | TIMESTAMP | NOT NULL |
| event_type | VARCHAR | NOT NULL |
| event_source | VARCHAR | NOT NULL |
| uid | VARCHAR | NULL |
| user_attributes_moengage_user_id | VARCHAR | NULL |
| device_attributes_moengage_device_id | VARCHAR | NULL |
| push_id | VARCHAR | NULL |
| email_address | VARCHAR | NULL |
| mobile_number | VARCHAR | NULL |
| event_attributes_app_version | VARCHAR | NULL |
| event_attributes_sdk_version | VARCHAR | NULL |
| event_attributes_platform | VARCHAR | NULL |
| event_attributes_campaign_id | VARCHAR | NULL |
| event_attributes_campaign_name | VARCHAR | NULL |
| event_attributes_campaign_type | VARCHAR | NULL |
| event_attributes_campaign_channel | VARCHAR | NULL |
| event_attributes_readable_campaign_id | VARCHAR | NULL |
| event_attributes_parent_campaign_id | VARCHAR | NULL |
| event_attributes_parent_flow_id | VARCHAR | NULL |
| event_attributes_parent_flow_name | VARCHAR | NULL |
| event_attributes_variation_id | VARCHAR | NULL |
| event_attributes_locale_id | VARCHAR | NULL |
| event_attributes_locale_name | VARCHAR | NULL |
| event_attributes_url | VARCHAR | NULL |
| event_attributes_timestamp | TIMESTAMP | NULL |
| event_attributes_first_session | BOOLEAN | NULL |
| event_attributes_logged_in_status | STRING | NULL |
| event_attributes | JSON | NULL |
| user_attributes | JSON | NULL |
| device_attributes | JSON | NULL |
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
Exports to BigQuery run hourly. MoEngage will retry an export multiple times before marking it as failed. The export will be paused after 3 consecutive scheduled export failures.
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination table, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage appends the data to the destination table.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
# Databricks Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/databricks-exports
Export campaign interaction events from MoEngage to Databricks using a direct export or OpenSharing (zero-copy sharing). Configure either method for scalable event analytics.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
[Databricks](https://www.databricks.com/resources/ebook/maximize-your-organizations-potential-data-and-ai?scid=7018Y000001Fi1AQAS\&utm_medium=paid+search\&utm_source=google\&utm_campaign=15418435374\&utm_adgroup=130717555576\&utm_content=ebook\&utm_offer=maximize-your-organizations-potential-data-and-ai\&utm_ad=703594935116\&utm_term=databricks\&gad_source=1\&gclid=CjwKCAjwvr--BhB5EiwAd5YbXpGh4ugWZyyOwJrqbfr-c5cZhP9HVrGMKQmBuZRlVcC_BRLco-zKVxoCmZkQAvD_BwE) is a platform that allows organizations to store, analyze, and process large volumes of structured and semi-structured data in a highly scalable and efficient manner. With its unique architecture, organizations can consolidate their data, perform quick analytics, and gain valuable data-driven insights accessible to all users.
## How Does MoEngage Work with Databricks?
With this integration, you can export data from campaign interaction events to your Databricks tables.
### Delivery Methods
MoEngage delivers event data to Databricks in two ways:
* **OpenSharing (Zero-Copy Sharing)**: Your workspace queries MoEngage-hosted data in place through the Delta Sharing protocol. This is the recommended method.
* **Direct export**: MoEngage writes events into a table in your own schema. Use this method when your workspace does not have Unity Catalog enabled.
Both methods produce the same table schema and refresh hourly. The following table compares them:
| | OpenSharing (Zero-Copy Sharing) | Direct Export |
| - | - | - |
| **How data arrives** | Your workspace queries MoEngage-hosted data live through the Delta Sharing protocol. | MoEngage writes events into a table in your schema. |
| **Credentials MoEngage needs** | None. You provide a sharing identifier, which is not a secret. | `WRITE` access to your Databricks catalog and schema. |
| **IP allowlisting** | Not required. | Required if your system enforces it. |
| **Where data is stored** | In a dedicated MoEngage-hosted catalog that you mount. | In your own catalog and schema. |
| **Requires Unity Catalog** | Yes. | No. |
| **Setup time** | Varies. Setup can take weeks or longer, depending on your workspace setup and enablement. | Self-serve on the App Marketplace. |
> [!NOTE]
>
> The two methods use separate storage layers. Records already delivered through a direct export do not appear in an OpenSharing catalog, and vice versa. To move between methods, contact your MoEngage Customer Success Manager (CSM). OpenSharing setup may take a few weeks or more, depending on your workspace setup, so plan accordingly.
## Integration
### Prerequisites
The prerequisites depend on the delivery method you choose. Click the tab for your method:
> [tab] OpenSharing (Zero-Copy Sharing)
>
> * Ensure your Databricks workspace has Unity Catalog enabled.
> * Retrieve your sharing identifier, formatted as `::`. For more information, refer to [Step 1: Request Enablement](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports#set-up-your-export).
> [tab] Direct Export
>
> * Ensure you have a Databricks account with relevant permissions to create/edit Databricks instances, roles, and policies. It is optional to create a new user; you must have access to create a new user in your Databricks database.
> * Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/databricks#step-4-enable-ip-whitelisting).
> * Ensure you have a [Databricks Connection](/docs/partner-guide/data-and-analytics/data-warehouses/databricks) on the App marketplace.
### Set Up Your Export
> [!NOTE]
>
> * For the full list of events and attributes, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * The event_time of the exported events is always in UTC.
> * MoEngage does not support exporting historical data. Data flows from the point you enable the export.
The setup steps differ by delivery method. Click the tab for the method you are using:
> [tab] OpenSharing (Zero-Copy Sharing)
>
> With OpenSharing, your workspace queries MoEngage-hosted data directly through the Delta Sharing protocol instead of receiving file-based exports. You do not exchange credentials or write tokens, and your queries always read the current data. You query the shared catalog with your existing SQL editors, notebooks, and BI dashboards through standard Unity Catalog workflows.
>
> The following diagram shows how data moves between MoEngage and your workspace:
>
> 
>
> **Step 1: Request Enablement**
>
> To request OpenSharing, perform the following steps:
>
> 1. In your Databricks workspace sidebar, click **Catalog**.
>
> 2. Click **Share**, and then click **OpenSharing**.
>
> 
>
> 3. On the **OpenSharing** page, click **Sharing ID** to copy your sharing identifier.
>
> 
>
> Send the sharing identifier to your MoEngage CSM.
>
> **Step 2: Accept the Share**
>
> MoEngage usually provisions the share within seven business days. Your CSM then sends you the name of your data share.
>
> To accept the share, perform the following steps:
>
> 1. In your Databricks workspace, click **Catalog** > **OpenSharing**, and then click the **Shared with me** tab.
>
> 
>
> 2. Click the MoEngage provider that matches the name your CSM sent you.
>
> 3. Next to the share, click **Mount to catalog**.
>
> 
>
> 4. Enter a catalog name, for example, `moengage_shared_data`, and then confirm it.
>
> **Step 3: Configure Your Export**
>
> To configure the export in MoEngage, perform the following steps:
>
> 1. On the left navigation menu in the MoEngage dashboard, click **App marketplace**.
> 2. On the **App marketplace** page, search for **Databricks**, and then click the **Databricks** tile.
> 3. Click the **Integrate** tab.
>
> Create the export as described in [Add a New Databricks Export on the MoEngage App Marketplace](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports#add-a-new-databricks-export-on-the-moengage-app-marketplace). In the **Export into schema** list, select the shared catalog's schema. The list shows the same value your CSM shared with you.
>
> OpenSharing provisions the connection for you, so MoEngage does not prompt you for a connection, service principal credentials, or write access.
>
> **Step 4: Query Your Data**
>
> The first rows can take up to 30 minutes to appear in your shared catalog. To verify the data, perform the following steps:
>
> 1. Run the following query:
>
> ```sql theme={null}
> SELECT * FROM ..;
> ```
>
> Replace the placeholders with your catalog, schema, and table names.
>
> 2. Click **Catalog Explorer**.
>
> 
>
> 3. Click a table, and then click **Sample Data**.
>
> Catalog Explorer lists the shared catalog under **Shares received**, along with its schemas and tables. The **Sample Data** view previews records and attribute definitions.
>
> If you want MoEngage to walk you through the schema, request a technical schema review from your CSM.
>
> **Step 5: Manage Access Within Your Organization**
>
> Because the shared catalog sits in your own infrastructure, you control access through Unity Catalog. Assign the `USE CATALOG` and `SELECT` privileges to the users or groups that need the data.
>
> MoEngage has no write access to the catalog, and either party can end the connection at any time. Tell your CSM about any changes to your workspace setup or sharing identifier, because these changes can interrupt delivery.
> [tab] Direct Export
>
> **Step 1: Grant Your User's Role the Required Permissions**
>
> MoEngage needs `WRITE` access to your Databricks database to store data. You can grant these permissions to an existing database user or create a new database user for MoEngage.
>
> Use the following code to configure write access for data storage in your Databricks database:
>
> ```text wrap theme={null}
> GRANT USE CATALOG ON CATALOG `` TO ``;
> GRANT USE SCHEMA, CREATE TABLE ON SCHEMA ``.`` TO ``;
> ```
>
> Change the following values:
>
> * `` - The name of your catalog.
> * `` - The name of your database or schema.
> * `` - The email ID of the user who created the token.
>
> **Step 2: Use a Unity Catalog Volume for Faster Exports (Recommended)**
>
> This step is optional. MoEngage can use a Unity Catalog volume to export data more efficiently. To use this method, create a dedicated volume and grant MoEngage access to it.
>
> Use the following code to create the volume and grant access:
>
> ```sql wrap theme={null}
> -- Create the volume. This is a one-time activity, and Databricks provisions the storage.
> CREATE VOLUME IF NOT EXISTS ..;
>
> -- Grant MoEngage read and write access on the volume.
> GRANT READ VOLUME, WRITE VOLUME ON VOLUME ..
> TO ``;
> ```
>
> Change the following values:
>
> * `` - The name of your catalog.
> * `` - The name of your database or schema.
> * `` - The name of the volume you are creating.
> * `` - The service principal's application ID (if using OAuth or a Service Principal PAT) or the user's email address (if using a User PAT).
>
> Enter the volume name in the **Unity Catalog Volume** field when you add the export.
>
> **Step 3: Add the Export on the App Marketplace**
>
> Continue with [Add a New Databricks Export on the MoEngage App Marketplace](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports#add-a-new-databricks-export-on-the-moengage-app-marketplace), below.
#### Add a New Databricks Export on the MoEngage App Marketplace
Both delivery methods use this step. With OpenSharing, the connection already exists, so you only choose the schema, events, and attributes.
To add a new Databricks export, perform the following steps:
1. On the left navigation menu in the MoEngage dashboard, click **App marketplace**.
2. On the **App marketplace** page, search for **Databricks**.

3. Click the **Databricks** tile.
4. On the **Databricks** page, click the **Integrate** tab, and then click **+ Add Export**.
5. Enter the following details:
| Field | Required | Description |
| - | - | - |
| **Export name** | Yes | Type a name for the Databricks export. |
| **Databricks connection** | Yes | Select your Databricks connection. |
| **Export into schema** | Yes | Select the schema that MoEngage uses to create new tables and export your events into. |
| **Unity Catalog Volume** | Optional | Enter the name of the volume you created for MoEngage. Leave it empty if you are not using a volume. To create one and grant MoEngage access, refer to the **Direct Export** tab under [Set Up Your Export](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports#set-up-your-export). |
| **User properties** | Optional | Select the user properties (user properties and device properties) you want to export with your events. |
| **Select events** | Yes | Select the events you want to export to Databricks. You can choose to export all events, including existing and new ones coming into MoEngage, or manually select specific events to export. |

6. Click **Save**.
### Export Process and Frequency
Both delivery methods refresh hourly, and neither requires you to run manual sync jobs.
For a direct export, MoEngage creates a destination table in your schema after you save the export, and then appends new event data at hourly intervals:
* **Initial action**: MoEngage creates the table when the first export is triggered.
* **Recurring action**: MoEngage appends data to the same table every hour.
For OpenSharing, MoEngage refreshes the shared datasets every hour. Your queries read the current state of the data, so there is no table for MoEngage to write into on your side.
### Sample Table Structure
MoEngage creates a single table using the following format:\
`moe_events_`.
For a direct export, this table is created in your schema. For OpenSharing, it appears in the shared catalog you mounted.
> [!NOTE]
>
> This table is created per connection. All hourly exports and different event types configured under this connection are consolidated and appended to this specific table.
The overall structure of the table remains fixed for all event types. Any new user property or event property that is exported is included in the user_attributes or event_attributes column, respectively. All events are consolidated in a single table containing necessary information, such as event names and event times, for easy analysis:
| Field | Type | NULL |
| - | - | - |
| app_name | VARCHAR | NOT NULL |
| event_name | VARCHAR | NOT NULL |
| event_code | VARCHAR | NOT NULL |
| event_uuid | VARCHAR | NOT NULL |
| event_time | TIMESTAMP | NOT NULL |
| event_type | VARCHAR | NOT NULL |
| event_source | VARCHAR | NOT NULL |
| uid | VARCHAR | NULL |
| user_attributes_moengage_user_id | VARCHAR | NULL |
| device_attributes_moengage_device_id | VARCHAR | NULL |
| push_id | VARCHAR | NULL |
| email_address | VARCHAR | NULL |
| mobile_number | VARCHAR | NULL |
| event_attributes_app_version | VARCHAR | NULL |
| event_attributes_sdk_version | VARCHAR | NULL |
| event_attributes_platform | VARCHAR | NULL |
| event_attributes_campaign_id | VARCHAR | NULL |
| event_attributes_campaign_name | VARCHAR | NULL |
| event_attributes_campaign_type | VARCHAR | NULL |
| event_attributes_campaign_channel | VARCHAR | NULL |
| event_attributes_readable_campaign_id | VARCHAR | NULL |
| event_attributes_parent_campaign_id | VARCHAR | NULL |
| event_attributes_parent_flow_id | VARCHAR | NULL |
| event_attributes_parent_flow_name | VARCHAR | NULL |
| event_attributes_variation_id | VARCHAR | NULL |
| event_attributes_locale_id | VARCHAR | NULL |
| event_attributes_locale_name | VARCHAR | NULL |
| event_attributes_url | VARCHAR | NULL |
| event_attributes_timestamp | TIMESTAMP | NULL |
| event_attributes_first_session | BOOLEAN | NULL |
| event_attributes_logged_in_status | VARCHAR | NULL |
| event_attributes | VARIANT | NULL |
| user_attributes | VARIANT | NULL |
| device_attributes | VARIANT | NULL |
The schema is the same for both delivery methods. Custom column naming is not supported.
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
Exports to Databricks run hourly. MoEngage will retry an export multiple times before marking it as failed. The export will be paused after 3 consecutive scheduled export failures.
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination table, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage appends the data to the destination table.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
> [accordion] Can I move from a direct export to OpenSharing?
>
> Yes. Contact your MoEngage CSM to change delivery methods. The two methods use the same schema but separate storage layers, so records already delivered through your direct export do not appear in the OpenSharing catalog.
> [accordion] Can I rename the columns or tables in the OpenSharing catalog?
>
> No. The schema is standardized and custom naming is not supported. You choose which events and attributes to export during configuration, as described in [Step 3: Configure Your Export](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports#set-up-your-export).
> [accordion] Who do I contact after the OpenSharing connection is live?
>
> Your MoEngage CSM is the primary contact for maintaining the connection, resolving technical questions, and adjusting your data requirements.
# Google Cloud Storage (GCS) Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/google-cloud-storage-gcs-exports
Export campaign interaction events from MoEngage to Google Cloud Storage buckets. Then import the exported files into BigQuery for further analysis.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
[Google Cloud Storage](https://cloud.google.com/storage) is an enterprise public cloud storage platform that can house large unstructured data sets.
## How Does MoEngage Work with GCS?
The MoEngage and GCS integration exports Campaign Interaction Events to your Google Cloud Storage buckets. You can then import these files into BigQuery for further processing and analysis.
## Integration
### Prerequisites
* Ensure you have a Google Cloud Platform account with permission to create a bucket, a service account, and custom roles.
* Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/cloud-storage/google-cloud-storage#step-4-enable-ip-whitelisting).
* Ensure you have a [GCS Connection](/docs/partner-guide/data-and-analytics/cloud-storage/google-cloud-storage) on the App marketplace. The service account needs `storage.objects.create` and `storage.buckets.get` on the bucket, and `resourcemanager.projects.getIamPolicy` on the project to test the connection.
### Set Up Your Export
> [!NOTE]
>
> * For the full list of events and attributes, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * The event_time of the exported events is always in UTC.
#### Add a New GCS Export on the MoEngage App Marketplace
1. On your MoEngage dashboard, go to the **App Marketplace**.
2. Search for **Google Cloud Storage**.
3. Go to the **Integrate** tab, and click **+ Add Integration**.

4. Give your connection an identifiable name.
5. Enter your bucket name.
6. Optionally, select your bucket region. You can find this on your Bucket Details page.
7. Upload the service account credential JSON file that you downloaded earlier. You can verify your Client ID and Client Email upon upload.
8. Select which events you want to export. By default, each event is exported with standard attributes.

9. Optionally, you can test the connection. MoEngage attempts to verify whether the details you entered are correct. If there is an issue, an error is displayed that you can rectify.
### Verify You Are Receiving Data Correctly
MoEngage uploads files using the following path structure:
```text wrap theme={null}
gs:///event-exports///export_day=YYYY-MM-DD/export_hour=HH/.json.gz
```
Go to your bucket and verify that the files are present:

### Export Process and Frequency
MoEngage dumps the data at hourly intervals.
### Sample File
The exported files are in the `.json.gz` format. [Download a sample file](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/event_exports_sample_files.json.gz) to inspect the structure. The exact contents will differ based on the events and attributes you opt to export.
```json JSON theme={null}
{
"app_name": "App Name",
"export_hour": "6",
"db_name": "MoEngage App Name",
"event": {
"uid": "user id",
"event_type": "CAMPAIGN_EVENT",
"event_code": "MOE_EMAIL_SENT",
"event_name": "Email Sent",
"user_attributes": {
"moengage_user_id": "userid1",
"user_attr1": "value1",
"user_attr2": "value2"
},
"event_source": "MOENGAGE",
"email_id": "test@xyz.com",
"event_attributes": {
"campaign_name": "Campaign name",
"moe_campaign_tags": [
"Tag1",
"Tag2"
],
"campaign_type": "GENERAL",
"moe_campaign_channel": "Email",
"moe_delivery_type": "One Time",
"campaign_id": "moengage campaign id",
"campaign_channel": "EMAIL"
},
"event_uuid": "3b918064-08dc-47ae-b674-c23797475a8d",
"event_time": 1653022310,
"device_attributes": {
"moengage_device_id": "device id if applicable"
}
},
"export_day": "2022-05-20"
}
```
For a list of supported events and attributes, refer to our [Data Export Glossary](https://www.moengage.com/docs/user-guide/data/exports/events/data-export-glossary).
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
Exports to Google Cloud Storage run hourly. MoEngage will retry an export multiple times before marking it as failed. The export will be paused after 3 consecutive scheduled export failures.
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination bucket, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
> [!NOTE]
>
> MoEngage tests the connection before it turns the export back on. If the service account doesn't have `resourcemanager.projects.getIamPolicy` on the project, the test fails and you can't turn on the export. For the permissions, refer to [Google Cloud Storage](/docs/partner-guide/data-and-analytics/cloud-storage/google-cloud-storage#note-on-required-permissions).
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage backfills the data into the date folders it would have written to at the time, rather than writing it to a new location.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
# Redshift Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/redshift-exports
Export campaign interaction events from MoEngage directly to your Amazon Redshift cluster. Set up the data warehouse integration for event analytics.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
[Amazon Redshift](https://aws.amazon.com/redshift/) is a fast and powerful, fully managed, petabyte-scale data warehouse service that forms part of the larger cloud-computing platform Amazon Web Services.
## How Does MoEngage Work with Redshift?
The MoEngage and Redshift integration exports Campaign Interaction Events data directly to your Amazon Redshift cluster.
## Integration
### Prerequisites
* Ensure you have an Amazon Web Services account with permission to create/edit Redshift clusters, roles, and policies.
* It is optional to create a new user; you must have access to create a new user in your Redshift cluster.
* Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Allow MoEngage IPs to access your cluster](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift#step-3-allow-moengage-ips-to-access-your-cluster).
* Ensure you have a [Redshift Connection](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift) on the App marketplace.
### Set Up Your Export
> [!NOTE]
>
> * For the full list of events and attributes, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * The event_time of the exported events is always in UTC.
#### Add a New Redshift Export on the MoEngage App Marketplace
1. On your MoEngage Dashboard, go to the App Marketplace.
2. Search for "Redshift".
3. Go to the "Integrate" tab, and click on "+ Add Integration".

4. Fill out the connection details of your Redshift cluster.


| Field | Description | Example |
| - | - | - |
| Connection Name | Give this connection an identifiable name. | `My Redshift Instance 1` |
| Host Name | On your AWS Console, navigate to your Redshift cluster. Under **General information**, the hostname is listed as your Redshift endpoint. Paste the part before the colon `:`. For example, if the Endpoint is `redshift-cluster-1.xxxxxxxzgxxx.us-east-1.redshift.amazonaws.com:5439/dev` then your Host Name will be `redshift-cluster-1.xxxxxxxzgxxx.us-east-1.redshift.amazonaws.com`.  | Format should be `[name].[id].[region].redshift.amazonaws.com` |
| Port | Enter your port number. On your AWS Console, navigate to your Redshift cluster. Under the **Properties** tab, find your port number and database name in the **Database configurations**. By default, the Redshift port number is 5439.  | `5439` |
| Database | The name of your Redshift database. | `moengage_exports` |
| Username | Enter the username you want MoEngage to connect as. This can either be an existing user, or the one you created in [Step 2](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift#step-2-create-a-new-database-user-for-moengage). | — |
| Password | Enter the password of the database user. | — |
| IAM Role ARN | Enter the ARN of the IAM Role you created in [Step 5](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift#step-5-create-a-new-redshift-iam-role). To find the ARN, on your AWS Console, go to IAM Console. In the side menu, under Access Management, click on **Roles**. Select the IAM Role you created in [Step 5](/docs/partner-guide/data-and-analytics/data-warehouses/amazon-redshift#step-5-create-a-new-redshift-iam-role). Under the **Summary** section, you will find the ARN listed. Copy and paste it into the input field.  | Format should be `arn:aws:iam::[aws-account-id]:role/[role-name]` |
| Export into schema | MoEngage will create tables in the schema you provide. Unless specifically configured, the usual value for schema name is "public". | — |
| Select events to export | Select which events you want to export to your Redshift cluster. | — |
5. Optionally, you can choose to test the connection. MoEngage will attempt to verify if the details you entered are correct. If there is an issue, an error will be shown that you can rectify.
6. Once the test connection is successful, you can save the connection details and MoEngage will begin exporting events shortly to your Redshift cluster.
### Verify You Are Receiving Data Correctly
MoEngage will create the following two tables in your schema:
1. `test_connection_moengage` - We will use this table to verify if your connection details are valid from time to time.
2. `moengage_events` - We will dump (append) all your events in this table.

You can verify if data is correctly flowing in your warehouse by querying `moengage_events` table:

### Export Process and Frequency
We will dump the data at hourly intervals.
### Sample Table Structure
The final table definition will depend on the exact configurations of your exports.
| Field | Type | NL |
| - | - | - |
| `app_name` | character varying(256) | NN |
| `event_name` | character varying(256) | NN |
| `event_code` | character varying(256) | NN |
| `event_uuid` | character varying(256) | NN |
| `event_time` | bigint | NN |
| `event_type` | character varying(256) | NN |
| `event_source` | character varying(256) | NN |
| `uid` | character varying(256) | NULL |
| `user_attributes_moengage_user_id` | character varying(256) | NULL |
| `device_attributes_moengage_device_id` | character varying(256) | NULL |
| `push_id` | character varying(512) | NULL |
| `email_address` | character varying(256) | NULL |
| `mobile_number` | character varying(256) | NULL |
| `event_attributes_app_version` | character varying(256) | NULL |
| `event_attributes_sdk_version` | character varying(256) | NULL |
| `event_attributes_platform` | character varying(256) | NULL |
| `event_attributes_campaign_id` | character varying(256) | NULL |
| `event_attributes_campaign_name` | character varying(256) | NULL |
| `event_attributes_campaign_type` | character varying(256) | NULL |
| `event_attributes_campaign_channel` | character varying(256) | NULL |
| `event_attributes_readable_campaign_id` | character varying(256) | NULL |
| `event_attributes_parent_campaign_id` | character varying(256) | NULL |
| `event_attributes_parent_flow_id` | character varying(256) | NULL |
| `event_attributes_parent_flow_name` | character varying(256) | NULL |
| `event_attributes_variation_id` | character varying(256) | NULL |
| `event_attributes_locale_id` | character varying(256) | NULL |
| `event_attributes_locale_name` | character varying(256) | NULL |
| `event_attributes_url` | character varying(256) | NULL |
| `event_attributes_timestamp` | bigint | NULL |
| `event_attributes_first_session` | boolean | NULL |
| `event_attributes_logged_in_status` | character varying(256) | NULL |
| `event_attributes` | super | NULL |
| `user_attributes` | super | NULL |
| `device_attributes` | super | NULL |
| `created_at` | character varying(256) | NULL |
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
Exports to Redshift run hourly. MoEngage will retry an export multiple times before marking it as failed. The export will be paused after 3 consecutive scheduled export failures.
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination table, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage appends the data to the destination table.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
# S3 Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/s3-exports
Export user events and campaign data from MoEngage to Amazon S3 buckets in JSON format. Analyze exported data for deeper insights into user behavior.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
You can export all user events and campaign events that MoEngage receives or generates by using S3 Exports. Analyze the exported data to learn about user behavior, campaign interactions, and customer preferences.
## How Does MoEngage Work with S3?
[Amazon S3](https://aws.amazon.com/s3/) is a highly scalable storage system offered by Amazon Web Services. Integrating your S3 buckets allows MoEngage to share periodic exports of your data in JSON format.
## Integration
> [!WARNING]
>
> Don't restrict your export bucket by IP address. MoEngage can reach your bucket through an AWS private endpoint, where its requests have no public IP address, so an `aws:SourceIp` condition blocks them and your exports fail. Control access with the IAM role or bucket policy you set up instead. For details, see [Amazon S3](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-1-set-up-authentication).
Perform the following steps to configure your S3 integration:
### Step 1: Create an S3 Bucket
Even if you already have an S3 bucket, we recommend creating a new bucket specifically for MoEngage data transfers to enforce strict least-privilege security boundaries.
1. Open the [AWS S3 console](https://console.aws.amazon.com/s3/) and sign in or create an AWS account.
2. Select **S3** from the **Storage** category.
3. Click **Create Bucket**, type an identifiable name, and select your preferred physical region.
### Step 2: Add an Export on the App Marketplace
After you [connect your S3 bucket in the App Marketplace](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-4-connect-amazon-s3-on-the-app-marketplace), open the **Amazon S3** page. Under the **Setup exports to S3** section, click **+ Add export** to open the **Export details** panel.
1. Configure the export by using the following parameters:
| Field | Required | Description |
| - | - | - |
| **Export name** | Yes | Type a unique and identifiable name for the export (for example, `File-exports2`). |
| **S3 connection** | Yes | Select a saved connection from the dropdown list. If the connection uses the IAM policy authentication method, configure an IAM policy in your AWS account first. MoEngage uses this permission to deliver files to your S3 bucket during exports. For more information, see [Set Up Authentication](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-1-set-up-authentication). |
| **Folder path** | Yes | Type the path to the target folder where MoEngage must export your files. Do not begin or end the string with a slash. Select the **Export all files in one folder** check box to write every export to a single folder instead of date-partitioned subfolders. The resolved file path is rendered live below the field so that you can confirm the destination before saving. The format depends on whether you selected the check box:
**How do I find the folder path?** From the list of objects in your **S3** bucket, open the folder where you want to dump the files. On the **Properties** tab, locate the folder's **S3 URI**. Your folder path is the part after `s3://[your-bucket-name]/`, excluding the trailing slash. |
| **User properties** | No | Select user properties and device properties from the list to include them alongside event records in each export. |
| **Select events** | Yes | Select **All events** to export every existing and future event, or select **Select events manually** to pick events from the list. |
| **Frequency** | Yes | Select how often MoEngage must export these events:
**Every 15 mins**: MoEngage exports files at 15-minute intervals.
**Daily**: MoEngage exports files at the end of each day, at 02:00 UTC.
**Weekly**: MoEngage exports files every Monday at 02:00 UTC.
You cannot change the export frequency after saving. To use a different frequency, create a new export. |
| **File encryption** | No | Select the **File encryption** check box to encrypt every exported file by using PGP. MoEngage encrypts the GZIPPED file with your public key and appends the `.gpg` extension (for example, `event-exports_1735198203.json.gz.gpg`). After you decrypt the file, unzip it to view the exported contents. |
2. Click **Test**. \
MoEngage attempts to write a temporary placeholder file to verify your S3 bucket configuration, folder path, and write permissions.
3. When the test passes, click **Save**. MoEngage displays a confirmation popup that calls out the locked frequency. Review the message and click **Save** again to activate the export.
4. To discard the configuration without saving, click **Cancel**. 
## Events and Attributes
With the MoEngage and S3 integration, you can export all events coming into MoEngage to your S3 buckets. By default, MoEngage tracks standard events and user properties through its SDKs. Read about our [standard events and attributes here](/docs/user-guide/data/event-data/derived-events-and-attributes). You can also export any custom user-defined event you track in MoEngage.
## Data Export Format
* **File format**: JSON
* **Compression type**: GZip
* **Export frequency**: Every 15 mins, daily, or weekly
* **Sample folder path**:
* *Date-partitioned*: `s3:///[_]/export_day=2025-10-28/event_exports_.json.gz`
* *Single folder*: `s3:///[]//event_exports_.json.gz`
MoEngage generates the `` as a unique identifier for each export file.
## Sample Export Data
```json User Action Event theme={null}
{
"app_name": "App Name",
"export_hour": "10",
"db_name": "MoEngage App Name",
"event": {
"uid": "user id",
"event_type": "USER_ACTION_EVENT",
"event_code": "VIEW_RADAR",
"event_name": "VIEW_RADAR",
"user_attributes": {
"moengage_user_id": "userid1",
"user_attr1": "value1",
"user_attr2": "value2"
},
"event_source": "MOENGAGE",
"event_attributes": {
"event_attr1": "value1",
"event_attr2": "value2"
},
"event_uuid": "62045d15-8d5e-4cfd-ac49-5919bffb401d",
"event_time": 1652820710,
"device_attributes": {
"moengage_device_id": "device id"
}
},
"export_day": "2022-05-20"
}
```
```json Campaign Event theme={null}
{
"app_name": "App Name",
"export_hour": "6",
"db_name": "MoEngage App Name",
"event": {
"uid": "user id",
"event_type": "CAMPAIGN_EVENT",
"event_code": "MOE_EMAIL_SENT",
"event_name": "Email Sent",
"user_attributes": {
"moengage_user_id": "userid1",
"user_attr1": "value1",
"user_attr2": "value2"
},
"event_source": "MOENGAGE",
"email_id": "test@xyz.com",
"event_attributes": {
"campaign_name": "Campaign name",
"moe_campaign_tags": [
"Tag1",
"Tag2"
],
"campaign_type": "GENERAL",
"moe_campaign_channel": "Email",
"moe_delivery_type": "One Time",
"campaign_id": "moengage campaign id",
"campaign_channel": "EMAIL"
},
"event_uuid": "3b918064-08dc-47ae-b674-c23797475a8d",
"event_time": 1653022310,
"device_attributes": {
"moengage_device_id": "device id if applicable"
}
},
"export_day": "2022-05-20"
}
```
Download a sample file from [here](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/event_exports_sample_files.json.gz). This is a GZIPPED file; extract it before you view the contents.
## Integrate AWS Key Management Service with Amazon S3
1. Create an AWS Key Management Service (KMS) Customer Master Key (CMK) by using the AWS Management Console, AWS CLI, or AWS SDKs. Skip this step if your AWS KMS key is already generated.
2. Enable the AWS KMS key for use with S3 by adding permissions to the AWS KMS key policy. The following example key policy allows the key to be used for S3 encryption:
> [!WARNING]
>
> The **Principal** ARN in this example is for workspaces on DC-01 to DC-04. Use the export role ARN for your data center:
>
> * **DC-01 to DC-04:** `arn:aws:iam::612427630422:role/service-role/core_s3_export-role-e1qw8ulf`
> * **DC-06:** `arn:aws:iam::163129101105:role/core_s3_export-role-e1qw8ulf`
>
> For any other data center, contact MoEngage Support for your export role ARN before you create the key policy. The wrong ARN makes **Test Connection** fail with an `AccessDenied` error on `kms:GenerateDataKey`.
```json wrap theme={null}
{
"Version": "2012-10-17",
"Id": "key-policy",
"Statement": [
{
"Sid": "Allow use of the key for S3 encryption",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::612427630422:role/service-role/core_s3_export-role-e1qw8ulf"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": [
"arn:aws:s3:::your-bucket",
"arn:aws:s3:::your-bucket/*"
]
}
]
}
```
3. Configure the S3 bucket to use the AWS KMS key for encryption. You can do this while creating the bucket or by modifying the bucket properties.
4. In the S3 Management Console, navigate to the bucket where you want to enable server-side encryption.
5. Click the **Properties** tab and scroll down to the **Default encryption** section.
6. Under **Encryption**, select **Server-side encryption with AWS Key Management Service keys (SSE-KMS)**, then select the AWS KMS key you created from the drop-down menu. Use only your KMS key's AWS KMS ARN.
7. Click **Save** to apply the encryption configuration to the bucket. S3 automatically encrypts your objects by using the AWS KMS key you integrated.
8. Provide MoEngage with the AWS KMS Key ARN so that MoEngage can whitelist it.
> [!NOTE]
>
> **Why is whitelisting the KMS key ARN necessary?**
>
> * The AWS KMS Key ARN (Amazon Resource Name) uniquely identifies the KMS key that you want to grant access to, which is why MoEngage requires it for whitelisting.
> * Whitelisting a KMS key ARN specifies that only authorized entities or services with access to that specific key can perform encryption or decryption operations.
> * Whitelisting the KMS key ARN adds an extra security layer by ensuring that only authorized resources can interact with the key, which reduces the risk of data breaches or unauthorized access.
> * By specifying the KMS key ARN in the whitelist, you get granular control over which resources can access and use the key, improving the overall security of your key management and encryption processes.
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
MoEngage will retry an export multiple times before marking it as failed. The export will be paused if multiple scheduled exports fail, depending on your chosen export frequency:
| Export frequency | Condition |
| - | - |
| 15 minutes | 3 consecutive scheduled export failures |
| Daily | 1 scheduled export failure |
| Weekly | 1 scheduled export failure |
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination bucket, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage backfills the data into the date folders it would have written to at the time, rather than writing it to a new location.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting data in my S3 bucket?
>
> It typically takes up to 30 minutes for MoEngage to set up the automated data exports for your account and for data to appear in your bucket.
> [accordion] Can I export additional events at a later time?
>
> Yes. If you need to export new events later, edit your export configuration on the App Marketplace and add the new events.
> [accordion] Can I change my existing S3 export frequency?
>
> No. You cannot modify the frequency of an Amazon S3 export after creation. To change the export frequency (for example, from Daily to Weekly), create a new S3 export with the desired frequency settings. Ensure your storage bucket is prepared to receive data from the new file path generated by the new configuration.
> [accordion] What happens when I change my export frequency?
>
> If you move from a more frequent export to a less frequent export, you might experience temporary data duplication when you first make the change. If you move from a less frequent export to a more frequent export, there is a rare possibility of data loss in high-volume cases.
> [accordion] Can I export historical data using automated data exports?
>
> Currently, you cannot export data from before you configured automated data exports. After you configure exports, MoEngage begins exporting data for each event from the time you enabled them.
> [accordion] Is there any pricing involved for automated data exports?
>
> If automated data exports are not covered in your billing plan and you want to enable them later, contact your Customer Success Manager to include them. Based on the monthly volume of data MoEngage places in your S3 bucket, additional charges may apply.
> [accordion] Does data exports guarantee the latest user properties?
>
> No. Data exports primarily exports your events in near real-time, and MoEngage updates user properties asynchronously. Because of this, MoEngage cannot currently guarantee the latest user property values in exported files.
# SFTP Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/sftp-exports
Export campaign events from MoEngage to your SFTP server securely. Set up periodic file transfers for campaign interaction data and user event imports.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
Secure File Transfer Protocol (SFTP) is a network protocol for securely accessing, transferring, and managing large files and sensitive data over any reliable data stream. Designed by the Internet Engineering Task Force as an extension of Secure Shell (SSH) version 2.0, SFTP provides secure file transfer capabilities.
## How Does MoEngage Work with SFTP?
MoEngage allows customers to automatically import users and events from their SFTP servers and export events from MoEngage through flat files.
Integration with SFTP servers will allow MoEngage to:
* Share periodic exports of campaign interaction events in JSON format.
* Support for username-password authentication.
* Support for VPC/private endpoints of the hosts.
You can export all user events and campaign events that are received or generated by MoEngage to your SFTP servers. You can further analyze the exported data to gain insights into user behavior, preferences, and more.
> [!NOTE]
>
> MoEngage utilizes the Paramiko (4.0.0) library to establish a native connection to your SFTP servers. This routine upgrade ensures that all integrations remain robust and comply with modern encryption standards.
## Integration
### Prerequisites
* Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/cloud-storage/sftp#enable-ip-whitelisting).
* Ensure you have connection access to your SFTP server. To create one, refer to [Configure a New SFTP Connection](/docs/partner-guide/data-and-analytics/cloud-storage/sftp#configure-a-new-sftp-connection).
* The export option is enabled only when you set up at least one connection.
* MoEngage requires permissions to create folders and write files on your SFTP server. Give full write access to a dedicated MoEngage directory on your SFTP server.
### Set Up Your Export
> [!NOTE]
>
> * The export option is enabled only when you set up at least one connection.
> * MoEngage requires permissions to create folders and write files on your SFTP server. It is recommended to give full write access to a dedicated MoEngage directory on your SFTP server.
> * Exports to SFTP are part of the Streams add-on. Please reach out to your dedicated MoEngage CSM (customer success manager) to get it enabled for your account.
To enable SFTP Exports on the MoEngage App Marketplace:
1. On your MoEngage UI, go to the App Marketplace.
2. Search for "SFTP".
3. Go to the **Integrate** tab and click **+ Add export**.
4. Enter the export details:

| Field | Description | Example |
| - | - | - |
| Export name | Give the export a name. | SFTP Export |
| SFTP connection | Select an existing SFTP connection from the list of connections you created in [Configure a New SFTP Connection](/docs/partner-guide/data-and-analytics/cloud-storage/sftp#configure-a-new-sftp-connection). | SFTP Connection |
| Folder path | The folder path to which MoEngage will dump the files. You can see the preview of the final file path below. | `/exports/` |
| Export all files in one folder | Select this option if you want MoEngage to dump all the files in a single folder. If this is disabled, MoEngage will create a new folder for each day inside the folder path provided by you. You can see the preview of the final file path below. | Toggle on/off |
| User properties | Select user properties (user properties and device properties) you want to export with your events. User properties, including device and custom properties, are available in Data Management for that Database/App. | (drop-down) |
| Select events | Select the events you want to export to your SFTP server. The available options are:
**All events**
**Select events manually**
You can choose to export "All events" (existing and new events coming into MoEngage in the future) or cherry-pick events manually and export only those events. | All events / Select events manually |
| Select events (drop-down) | This drop-down list is visible only if you select **Select events manually** under **Select events**. The events on this drop-down list are auto-populated with all the events in Data Management for that Workspace. | (drop-down) |
| Frequency | Select how often you want to export these events. MoEngage offers three frequencies:
**Every 15 mins**: MoEngage will dump files at 15-minute intervals.
**Daily**: MoEngage will dump files at the end of each day, 02:00 UTC.
**Weekly**: MoEngage will dump files on every Monday, 02:00 UTC.
A preview of next dump is displayed in case of Daily and Weekly. | Every 15 mins / Daily / Weekly |
> [!WARNING]
>
> MoEngage does not recommend frequently changing your export frequency, as this might result in data loss or duplication.
5. Click **Save export**. Your export will be saved and when the **Export status** toggle is turned on, MoEngage will start exporting files to the specified folder path on your SFTP server based on the selected export frequency.
> [!NOTE]
>
> MoEngage utilizes the Paramiko (4.0.0) library to establish a native connection to your SFTP servers. This routine upgrade ensures that all integrations remain robust and comply with modern encryption standards.
### Events and Attributes
With the MoEngage and SFTP integration, you can export all events coming into MoEngage to your SFTP servers. By default, MoEngage tracks some standard events and user properties through its SDKs. You can read about our [standard events and attributes here](/docs/user-guide/data/event-data/derived-events-and-attributes). You can also export any custom user-defined event you tracked in MoEngage.
### Data Export Format
| Information | Description |
| - | - |
| File Format | JSON |
| Compression Type | GZip |
| Export Frequency | Every 15 mins, Daily, or Weekly |
| Sample Folder Path | `sftp:///[/]/export_date={DD-MM-YYYY}/{filename=event_export}_[_].json.gz` |
In the sample folder path:
* `` is the prefix folder path given by you.
* `` is the connection name sluggified as entered by you.
* File number is optional in case we split the files.
**Note**: The file naming convention change will be effective December 25, 2025. The file naming format for exports is being updated from an epoch timestamp to a unique string. Ensure any data pipelines are configured to handle the new format.
* **Current name (epoch timestamps)**: export_day=2025-10-28/event_exports_1761689701.json.gz
* **New name (unique str)** : export_day=2025-10-28/event_exports_50492790da7cc2a0674fb51fa5046e3c.json.gz
You can download a sample file from [here](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/event_exports_sample_files.json.gz). This is a GZIPPED file and you must extract it before you can view the files.
For the full list of events and attributes exported, refer to the [Data Exports Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
MoEngage will retry an export multiple times before marking it as failed. The export will be paused if multiple scheduled exports fail, depending on your chosen export frequency:
| Export frequency | Condition |
| - | - |
| 15 minutes | 3 consecutive scheduled export failures |
| Daily | 1 scheduled export failure |
| Weekly | 1 scheduled export failure |
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a login user that does not have write permission on the destination folder, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage backfills the data into the date folders it would have written to at the time, rather than writing it to a new location.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
# Snowflake Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/data-warehouse/snowflake-exports
Export campaign interaction events from MoEngage directly to Snowflake tables. Configure the integration for scalable data warehousing and analytics.
> [!NOTE]
>
> This feature is part of the Streams paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Overview
[Snowflake](https://docs.snowflake.com/en/user-guide-getting-started) is a data platform that allows organizations to store, analyze, and process large volumes of structured and semi-structured data in a highly scalable and efficient manner. With its unique architecture, Snowflake allows organizations to consolidate their data, perform quick analytics, and gain valuable data-driven insights accessible to all users.
## How Does MoEngage Work with Snowflake?
The MoEngage and Snowflake integration exports Campaign Interaction Events data directly to your Snowflake tables.
## Integration
### Prerequisites
* Ensure you have a Snowflake account with relevant permissions to create/edit Snowflake instances, roles, and policies. It is optional to create a new user; you must have access to create a new user in your Snowflake database.
* Ensure the MoEngage IPs for your data center are whitelisted. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/snowflake#enable-ip-whitelisting).
* Ensure you have a [Snowflake Connection](/docs/partner-guide/data-and-analytics/data-warehouses/snowflake) on the App marketplace.
* The **Add Integration** option for Snowflake in the App Marketplace appears only after the Streams add-on is enabled for your workspace (see note above).
### Set Up Your Export
> [!NOTE]
>
> * For the full list of events and attributes, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * The event_time of the exported events is always in UTC.
#### Step 1: Grant the Required Permissions
MoEngage will require `WRITE` access to your database so that we can write data into your Snowflake database. You can either grant these permissions to an existing database user or choose to create a new dedicated database user for MoEngage:
```sql wrap theme={null}
-- Create a role for the MoEngage user
CREATE ROLE MOENGAGE_ROLE;
-- Allow the user to run queries in the warehouse
GRANT USAGE ON WAREHOUSE TO ROLE MOENGAGE_ROLE;
-- Let the user see this database
GRANT USAGE ON DATABASE TO ROLE MOENGAGE_ROLE;
-- Let the user see all schemas in this database
GRANT USAGE ON SCHEMA . TO ROLE MOENGAGE_ROLE;
-- Let the user create a table in your schema
GRANT CREATE TABLE ON SCHEMA . TO ROLE MOENGAGE_ROLE;
-- Let the user insert data in your tables
GRANT INSERT, SELECT ON ALL TABLES IN SCHEMA . TO ROLE MOENGAGE_ROLE;
-- Create the MoEngage user (MOENGAGE_USER is username here)
CREATE USER MOENGAGE_USER WITH DEFAULT_ROLE = MOENGAGE_ROLE DEFAULT_WAREHOUSE = PASSWORD = '';
-- Grant the role to the user
GRANT ROLE MOENGAGE_ROLE TO USER MOENGAGE_USER;
```
Remember to change the following values:
1. `` - The name of the warehouse you want MoEngage to use while executing queries.
2. `` - The name of the database you want to import data from.
3. `` - Give a strong password to the newly created database user.
#### Step 2: Create a New Export in the App Marketplace
> [!NOTE]
>
> * For the full list of events and attributes exported, refer to the [Data Exports Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
> * Please note that the `event_time` of the exported events will always be in UTC.

On your MoEngage dashboard, navigate to **App Marketplace** > **Snowflake**.
1. Click **Integrate** > **Add Integration**.
2. Select your Snowflake connection.
3. Select which schema MoEngage will use to create new tables and export your events into.
4. Select the events and additional user properties you want to export to Snowflake.
5. Click **Save Export**.
MoEngage will start dumping events to the newly created table every hour.
### Export Process and Frequency
After you save the export, MoEngage creates a destination table in your schema. New event data is then appended to this same table at hourly intervals:
* **Initial action**: MoEngage creates the table when the first export is triggered.
* **Recurring action**: MoEngage adds (appends) data to the same table every hour.
MoEngage exports the data at hourly intervals.
### Sample Table Structure
MoEngage creates a single table in your schema using the following format:
`moe_events_`
> [!NOTE]
>
> This table is created once per connection. All hourly exports and different event types configured under a single connection are consolidated and appended to this same table.
The overall structure of the table remains fixed for all types of events. Any new user property or event property that is exported will be included in the `user_attributes` or `event_attributes` column, respectively. All events are consolidated in a single table containing necessary information, such as event names and event times, for easy analysis:
| Field | Type | NL |
| - | - | - |
| `app_name` | VARCHAR | NN |
| `event_name` | VARCHAR | NN |
| `event_code` | VARCHAR | NN |
| `event_uuid` | VARCHAR | NN |
| `event_time` | TIMESTAMP_NTZ | NN |
| `event_type` | VARCHAR | NN |
| `event_source` | VARCHAR | NN |
| `uid` | VARCHAR | NULL |
| `user_attributes_moengage_user_id` | VARCHAR | NULL |
| `device_attributes_moengage_device_id` | VARCHAR | NULL |
| `push_id` | VARCHAR | NULL |
| `email_address` | VARCHAR | NULL |
| `mobile_number` | VARCHAR | NULL |
| `event_attributes_app_version` | VARCHAR | NULL |
| `event_attributes_sdk_version` | VARCHAR | NULL |
| `event_attributes_platform` | VARCHAR | NULL |
| `event_attributes_campaign_id` | VARCHAR | NULL |
| `event_attributes_campaign_name` | VARCHAR | NULL |
| `event_attributes_campaign_type` | VARCHAR | NULL |
| `event_attributes_campaign_channel` | VARCHAR | NULL |
| `event_attributes_readable_campaign_id` | VARCHAR | NULL |
| `event_attributes_parent_campaign_id` | VARCHAR | NULL |
| `event_attributes_parent_flow_id` | VARCHAR | NULL |
| `event_attributes_parent_flow_name` | VARCHAR | NULL |
| `event_attributes_variation_id` | VARCHAR | NULL |
| `event_attributes_locale_id` | VARCHAR | NULL |
| `event_attributes_locale_name` | VARCHAR | NULL |
| `event_attributes_url` | VARCHAR | NULL |
| `event_attributes_timestamp` | TIMESTAMP_NTZ | NULL |
| `event_attributes_first_session` | BOOLEAN | NULL |
| `event_attributes_logged_in_status` | VARCHAR | NULL |
| `event_attributes` | VARIANT | NULL |
| `user_attributes` | VARIANT | NULL |
| `device_attributes` | VARIANT | NULL |
## Export Failure Policy
MoEngage pauses an export that keeps failing. While it is paused, MoEngage collects the events the export would have delivered, and you replay them after you fix the problem.
### When MoEngage Pauses an Export
Exports to Snowflake run hourly. MoEngage will retry an export multiple times before marking it as failed. The export will be paused after 3 consecutive scheduled export failures.
When MoEngage pauses an export, it alerts you and shows the export as **Paused** on the App Marketplace.
### What Happens While an Export Is Paused

MoEngage collects the events the export would have delivered and keeps only the most recent 7 days. If the export stays paused for longer than a week, MoEngage drops the oldest days as newer ones come in.
If an export pauses more than once before you replay, MoEngage combines the data from all those pauses, provided it falls within the 7-day window.
### Resume an Export
#### Find the Failure Reason
On the App Marketplace, click the **Integrate** tab, and then hover over the **Paused** label on the export. MoEngage names the reason for the failure, such as a missing write permission on the destination table, and tells you how to fix it.

#### Enable the Export
Fix the cause at your end, and then turn on **Export status** for the export. Do this as soon as you can, because the 7-day window keeps moving while the export stays paused.
When you enable the export, MoEngage stops collecting and sets aside what it has: the last 7 days of paused data, or all of it if the pause was shorter. This is the data you can replay. It stays fixed from then on, and does not reduce further even if you wait to replay it.
### Replay Paused Data
#### Request a Replay
MoEngage saves the data it collected while the export was paused. An export with data waiting shows a **Replay available** label on the **Integrate** tab.
To replay, perform the following steps:
1. Hover over the **Replay available** label, or open the kebab menu on the export.
2. Click **Replay paused data**.

3. In the **Replay paused data** dialog box, click **Confirm**.

A replay sends everything MoEngage collected while the export was paused. MoEngage appends the data to the destination table.
You can replay at any time until 30 days from the date the oldest paused data was collected. After that, the data is no longer available.
> [!NOTE]
>
> Replay before the export pauses again. If it pauses a second time before you replay, MoEngage adds the new paused data to the data still waiting from the first pause. The combined data is then trimmed back to the most recent 7 days, so if the two pauses are more than 7 days apart, the older data is lost.
>
> For example, your export pauses on day 1. You enable it but do not replay. It pauses again on day 20. Since that is 19 days later, the day 1 data falls outside the 7 day window and is gone, even though its 30 day replay window had not expired. If the second pause had happened within 7 days of the first, the day 1 data would still be included.
#### Replay Results
When the replay finishes, MoEngage emails the user who requested it with one of the following results:
| Result | What it means |
| - | - |
| Successful | MoEngage delivered all the collected data. The replay option is no longer available. |
| Partially Successful | MoEngage delivered some of the collected data, and then hit an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
| Failed | MoEngage delivered none of the collected data, because of an error. The replay stops and MoEngage pauses the export again. The email states why the replay did not finish. Fix the cause, enable the export, and then replay again. For the data you can replay, refer to [What Happens While an Export Is Paused](#what-happens-while-an-export-is-paused). |
You can run only one replay per export at a time.
#### Avoid Duplicate Data
Every replay sends the whole collection again, because MoEngage does not deduplicate. If you replay more than once, deduplicate at your end on the `event_uuid` field, which is unique for each event. For the fields in the export, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
### Export Paused Alerts
MoEngage alerts you when it pauses an export, so you can fix the issue and replay the data collected while the export was paused.
MoEngage subscribes workspace admins to the Data Exports system alert by default, and adds the user who creates or updates an export. To subscribe or unsubscribe anyone else, go to the Alert Management page. Subscribing or unsubscribing changes notifications only for that person, and does not affect anyone else's subscription.
## Frequently Asked Questions
> [accordion] What does the Replay available label mean?
>
> MoEngage is holding data it collected while the export was paused. Hover over the label or open the kebab menu, and then click **Replay paused data**.
> [accordion] My export was paused for three weeks. Why can I replay only part of it?
>
> MoEngage keeps only the most recent 7 days of paused data, so a three-week pause leaves only the last 7 days to replay.
> [accordion] Why did my replay come back as Partially Successful?
>
> MoEngage delivered some of the data and not the rest, usually because the destination rejected part of it. Fix the cause and replay again. The next replay sends the whole collection, not only the part that failed.
> [accordion] Can I run two replays at the same time?
>
> No. You can run only one replay per export at a time. Wait for the result email before you request another.
> [accordion] I replayed twice and I see duplicate rows. Why?
>
> Every replay sends the whole collection again, because MoEngage does not deduplicate. Deduplicate at your end on the `event_uuid` field, which is unique for each event.
> [accordion] How soon will I start getting the data?
>
> It typically takes up to 30 minutes for the automated data exports to be set up for your account and for you to start seeing data there.
> [accordion] Can I export additional events at a later time?
>
> Yes, if you need to export new events at a later time, you can always edit your configuration on the App Marketplace and get the new events added to your exports.
> [accordion] Can I export historical data using Automated Data Exports?
>
> As of now, you cannot export historical data using Automated Data Exports. Once configured, you will start seeing data for each event from the time you enabled your exports.
> [accordion] Is there any pricing involved for Automated Data Exports?
>
> If your billing plan does not cover this already and you need to get this enabled at a later time, you would need to work with your Customer Success Manager to get this included in your billing plan. Based on the amount of data that MoEngage will place in your Data warehouse/Partner/API on a monthly basis, this could lead to additional charges.
> [accordion] Does Data Exports guarantee the latest user properties?
>
> No, Data Exports is primarily built to export your Events in near real-time and user properties in MoEngage are updated asynchronously so it is currently not possible to guarantee the latest values of user properties in the exports.
# Overview - Event Exports
Source: https://moengage.com/docs/user-guide/data/exports/events/overview-events-exports
Get started with MoEngage event exports. Compare destinations and delivery frequencies, then set up the integration for your data warehouse, cloud storage, or API endpoint.
## Introduction
MoEngage Event Exports let you forward the events MoEngage receives or generates, such as user actions and campaign interaction events, to a destination outside MoEngage. This page helps you choose the right destination for your use case. Once you pick one, its dedicated help doc walks you through the setup.
> [!NOTE]
>
> Event exports are part of the Streams add-on. Contact your MoEngage customer success manager (CSM) to enable them for your account.
## Choose Your Export Destination
MoEngage supports three categories of export destinations:
| Category | Destinations | Delivery |
| - | - | - |
| API | Streams | Near real-time, per event |
| Data Warehouse | Snowflake, Google BigQuery, Amazon Redshift, Databricks | Hourly |
| Cloud Storage | Amazon S3, Google Cloud Storage, SFTP | Every 15 minutes, daily, or weekly (Amazon S3 and SFTP); hourly (Google Cloud Storage) |
Select the destination that matches your setup:
> [card] [Streams](/docs/api/data/moengage-streams)
>
> Forward events to your own API endpoint in near real-time by using a Bulk API call.
> [card] [Snowflake](/docs/user-guide/data/exports/events/data-warehouse/snowflake-exports)
>
> Export events directly to Snowflake tables.
> [card] [Databricks](/docs/user-guide/data/exports/events/data-warehouse/databricks-exports)
>
> Export events to Databricks through a direct export or OpenSharing (zero-copy sharing).
> [card] [Google BigQuery](/docs/user-guide/data/exports/events/data-warehouse/bigquery-exports)
>
> Export events directly to BigQuery, without an intermediate Google Cloud Storage hop.
> [card] [Amazon Redshift](/docs/user-guide/data/exports/events/data-warehouse/redshift-exports)
>
> Export events directly to your Amazon Redshift cluster.
> [card] [Amazon S3](/docs/user-guide/data/exports/events/data-warehouse/s3-exports)
>
> Export events as JSON files to an S3 bucket, on a schedule you choose.
> [card] [SFTP](/docs/user-guide/data/exports/events/data-warehouse/sftp-exports)
>
> Export events as JSON files to your own SFTP server, on a schedule you choose.
> [card] [Google Cloud Storage](/docs/user-guide/data/exports/events/data-warehouse/google-cloud-storage-gcs-exports)
>
> Export events as JSON files to a GCS bucket, on a schedule you choose.
## How Exports Work
The following mechanics are common across data warehouse and cloud storage destinations. Streams, being a direct API call rather than a scheduled export, does not follow this flow.
You set up and manage every export from the **App Marketplace**: search for the destination, open its tile, and go to the **Integrate** tab to add or manage an export.
### Export Failure, Pause, and Replay
MoEngage will retry an export multiple times before marking it as failed. The export will be paused if multiple scheduled exports fail. While it is paused, MoEngage saves the events the export would have delivered. After you fix the problem and re-enable the export, you can replay the collected data:
* MoEngage keeps up to 7 days of collected data while an export is paused, dropping the oldest days if the pause runs longer.
* You can replay collected data up to 30 days from the date the oldest paused data was collected. The 7-day retention can cut this window short in case of multiple pauses, so not all days are always replayable. For a worked example, refer to the failure policy section on each destination's page.
* A replay resends the entire collection, so deduplicate on the `event_uuid` field at your end if you replay more than once.
The exact number of scheduled exports that need to fail before MoEngage pauses an export depends on its frequency (for example, hourly data warehouse exports pause after 3 consecutive scheduled exports fail, while daily or weekly cloud storage exports pause after 1). For the specific thresholds and replay steps, refer to the failure policy section on each destination's page.
MoEngage notifies you when it pauses an export through the **Data Exports** system alert, so you can fix the issue and replay the data. MoEngage subscribes workspace admins by default, along with the user who creates or updates the export. To manage who else receives this alert, refer to [Alert Management](/docs/user-guide/settings/reports-and-alerts/alert-management/getting-started/overview-alert-management).
## Further Reading
For the full event and attribute schema exported to each destination, refer to the [Data Export Glossary](/docs/user-guide/data/exports/events/data-export-glossary).
To track how much data you are exporting against your monthly usage, refer to [Analyze the Volume of Data Exports](/docs/user-guide/data/exports/events/analyze-the-volume-of-data-exports).
# Outbound Segment Sync
Source: https://moengage.com/docs/user-guide/data/exports/segments/outbound-segment-sync
Sync MoEngage customer segments to ad networks, loyalty platforms, and data warehouses. Automate outbound segment sharing for targeted engagement.
> [!NOTE]
>
> This feature is part of the Connected Segments paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Introduction
*Outbound Segment Sync* allows you to sync and send valuable customer segments created in MoEngage to any other platform in your tech stack. You can sync these segments across various platforms, including ad networks, loyalty platforms, recommendation engines, and experimentation tools. This helps drive various business use cases, including targeted engagement and data-driven decision-making.

## Use Cases
Brands can use Outbound Segment Sync to sync impactful segments across tools, enabling targeted engagement and other business strategies.
* **Sync segments to a Data Warehouse:** Gain deeper insights and enhance data-driven decision making by seamlessly syncing segments to your data warehouse for in-depth analysis.
* **Sync segments to a Loyalty platform:** Enhance customer loyalty programs by syncing segments, enabling personalized rewards and promotions tailored to individual preferences.
* **Sync segments to an In-App Personalization platform:** Create highly personalized user experiences by syncing segments, ensuring that each user receives content and features that match their preferences.
* **Sync segments to an Ad network:** For precision-targeted advertising campaigns, sync your segments, ensuring your ads reach the most relevant audiences.
* **Sync customer segments to an Experimentation platform:** Conduct A/B/n tests with precision by syncing segments to compare different customer groups' responses and behaviors.
* **Sync segments to a CRM platform:** Improve customer interaction tracking by syncing segments, providing better insights into customer behaviors and preferences.
* **Sync segments to a Customer Service platform:** Provide personalized support by syncing segments so your customer service teams can better understand and assist individual customers.
* **Sync segments from one MoEngage App to another:** Using Outbound Segment Sync with the Cohort Sync API makes it easy to sync your segments across multiple MoEngage apps. For more information, refer [Sync Segments from One MoEngage App to Another](/docs/user-guide/data/exports/segments/outbound-segment-sync#sync-segments-from-one-moengage-app-to-another).
# Integration
## Option 1: Use Partner Integrations
MoEngage provides preexisting partner integrations that simplify the configuration process and API endpoint testing. With just a few clicks, you can start syncing segments to partner platforms. For a worked example, refer to [Storyly](/docs/partner-guide/personalize-and-optimize/dynamic-content/storyly), which covers syncing a MoEngage segment to a partner from end to end.
## Option 2: Configure a Custom Destination Using an API Endpoint
To set up a destination by using API endpoints, navigate to the App Marketplace and select the Custom Destinations section. Add a custom destination and configure it by following the steps below.
## Step 1: Create a Connected App
To create a connected app:
1. On the left navigation menu in the MoEngage dashboard, click **App marketplace**.
2. On the App marketplace page, click **+ Create app**.

3. In the **Create app** dialog box, enter the following details:
| Field | Description |
| - | - |
| **App name** | Type the app name. |
| **App type** | Click **Outbound Segment Sync** (Export MoEngage segments to your app). |
4. Click **Create**.  This adds your connected app as a destination in MoEngage. You will be directed to the connected app page. 
## Step 2: Add an Integration
After creating the app, you must configure the integration details to inform MoEngage where and how to send the segment data.
1. On the connected app page in **App marketplace**, click the **Integrate** tab, and then click **+ Add integration**.
2. In the **Connection details** section, enter the following details to sync segments to your endpoint:
| Field | Description |
| - | - |
| **Integration Name** | Enter an integration name to identify your endpoint. |
| **URL Endpoint** | Enter a URL endpoint to sync the data. Example: `https://api.example.com/segments` If your system requires IP whitelisting, refer [here](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage). |
| **Key-Value Pairs** | \[Optional] Enter a list of key-value pairs that can be added to the headers and parameters as per your requirement. |
| **Authentication** | Supported options are Basic auth and No auth. |
| **User Identifier** | Choose the user identifier you want to sync from the MoEngage user segment to your endpoint. This should be a key that uniquely identifies a user at your destination. You can rename this key as per the user identifier at your destination. |
| **Request Body** |
`add_users`: This list contains the users to be added to a particular segment.
`remove_users`: This is the list that contains the users to be removed from a particular segment.
**Note:** Both `add_users` and `remove_users` fields are not mandatory in one request. Only one of these or both can exist in the request payload, or they can be an empty array as well.
You cannot remove these keys. However, they can be renamed as per your destination.
\[Optional] You can add a list of Key-Value pairs to the list of add and remove users as per your requirement.
|
| **Throttle** |
MoEngage will send 25000 requests per minute.
Each request can have between 100 and 10000 users simultaneously, which you can set in the throttle.
|
## Portfolio Support (Project-Level Routing)
You can route imported events to specific projects in your MoEngage portfolio workspace using column mapping. Map your project identifier column (such as `brand_name` or `app_id`) to the MoEngage attribute `moe_project_name`. Values must match your MoEngage project names exactly (matching is case-sensitive).
* **Successful routing**: If the value matches a project in your portfolio, MoEngage ingests the user or event at that project level.
* **Fallback**: If the mapping is missing, blank, or does not match a project name, MoEngage ingests the data at your global portfolio level.
## Language and Empty Values
MoEngage handles languages and empty values as follows:
* **Language**: You can import data in any language using UTF-8 decodable characters.
* **Empty values**: Empty values are still imported. MoEngage creates or updates the attribute with an empty value.
## Limits
Manual uploads have the following limits:
> [!WARNING]
>
> **Imported data is subject to archival**
>
> MoEngage archives inactive users, events, and devices every 14 days and deletes the archived data permanently. Registered users are archived after 365 days without activity or campaign engagement, and anonymous users after 60 days.
>
> Importing or updating user properties does not count as activity, so it does not postpone archival. Only events and campaign engagement do.
>
> Before you import, check the criteria in [Data Archival (Retention) Policy](/docs/user-guide/data/key-concepts/data-archival-retention-policy) to confirm which of your records qualify.
| Limit | Value |
| - | - |
| File size | Less than 150 MB per CSV. Split larger files. |
| Rows | A single CSV or JSON file supports up to your hourly row limit. Files exceeding your hourly row limit are rejected. A file with fewer than 5 rows may cause errors, add dummy rows if needed. |
| Columns/Attributes | 100 columns for users; 100 columns per event. |
**Rate limits** (defaults, contact MoEngage to increase):
| Import Type | Hourly | Daily |
| - | - | - |
| Users |
Growth: 1.5M/hr
Enterprise: 2.5M/hr
|
Growth: 15M/day
Enterprise: 25M/day
|
| Events | 5M/hr | 40M/day |
The hourly rate is the maximum ingested per hour; the daily rate is the total cap per day. When a rate limit is breached, you receive a *Rate limit breached* alert on the Data Imports dashboard.
To see how much of your hourly and daily import limit you have used, which imports are held back when a limit is reached, and which imports are consuming the most, refer to [Check Import Limits](/docs/user-guide/data/imports/overview-imports#check-import-limits).
## What Is Not Supported
Manual uploads do not support the following:
* Attribute type *list* and other complex types (JSON, dictionaries, and so on).
* Multi-line support in CSV files is disabled by default. Please get in touch with support if you need this feature. Newline formats other than `\n`, such as `Ctrl+M` and `\r`, are not supported. Enabling multi-line support can negatively impact the processing speed of your import.
* JSON files.
> [!NOTE]
>
> **File and row order is not guaranteed.**
>
> MoEngage processes files in parallel and does not preserve the order in which files were placed in the folder or uploaded. It also does not preserve row order within a file. If the final state of an attribute depends on sequence (for example, multiple updates to the same user), send one consolidated row per user.
# Run History
**Run history** on the import details page shows the run for your upload, so you can see when it was scheduled, when it finished, how long it took, and how the file performed. A manual upload is a one-time import, so it has a single run.
To open **Run history**, perform the following steps:
1. On the Data imports page, click the kebab menu under **Actions** for the import.
2. Click **View**.


The row shows when the run was scheduled, when it completed, its status, the number of files processed, and the total rows found, along with the counts for what you imported. MoEngage populates these statistics only after the run finishes. To see the file itself, click **View Files**, where you can download the file, and for a failed or partially successful file the error report as well.

For the full column reference and the run status logic, refer to [Run History](/docs/user-guide/data/imports/setting-up-a-file-import#run-history) and [Import Statuses](/docs/user-guide/data/imports/overview-imports#import-statuses).
# Manage Your Imports
To monitor your imports, understand import statuses, or trigger a run manually or via API, see [How Imports Work](/docs/user-guide/data/imports/overview-imports#how-imports-work) on the Imports Overview.
# Frequently Asked Questions
> [accordion] My imports have failed. How do I check what went wrong?
>
> Click the ellipsis on the right and click **View** to look up the Import details. Hover over the **Failed** Status to learn the reason.
> [accordion] What if a scheduled import adds the data into a recently archived segment?
>
> In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.
> [accordion] Can an import be stopped while it's running?
>
> Once an import process starts, it can't be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It's best to let the current import finish.
> [accordion] How can I stop future runs of a scheduled import?
>
> Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the **Archive** option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.
> [accordion] What should I do if an import seems stuck or is taking a long time?
>
> If an import appears to be stuck or is taking longer than usual, it's best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it's still processing can cause conflicts and may prevent the original import from completing successfully.
# Overview - Imports
Source: https://moengage.com/docs/user-guide/data/imports/overview-imports
Get started with MoEngage data imports. Compare sources, see which entity types each supports, and choose the right import path for users, events, and auxiliary data.
# Introduction
MoEngage lets you import users, events, and auxiliary data into your workspace from files (Amazon S3, SFTP, or a manual CSV upload) and directly from your data warehouse (Snowflake, BigQuery, or Databricks). This page helps you choose the right source for your use case. Once you pick a path, its dedicated setup page walks you through the entire process.
> [!NOTE]
>
> If your system requires IP whitelisting, refer to [IP Whitelisting in MoEngage](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage) before setting up a data import.
# Sources and Supported Entities
Each source supports a different set of entity types. Use this matrix to confirm your source can import the data you need.
**File Sources**
| Source | Registered Users | Anonymous Users | Events | Auxiliary Data |
| - | :-: | :-: | :-: | :-: |
| Amazon S3 | ✅ | ✅ | ✅ | ✅ |
| SFTP | ✅ | ✅ | ✅ | ✅ |
| Manual Upload (CSV) | ✅ | ✅ | ✅ | ✅ |
**Data Warehouses**
| Source | Registered Users | Anonymous Users | Events | Auxiliary Data |
| - | :-: | :-: | :-: | :-: |
| Snowflake | ✅ | ✅ | ✅ | ❌ |
| BigQuery | ✅ | ✅ | ✅ | ❌ |
| Databricks | ✅ | ✅ | ✅ | ❌ |
**Entity types:**
* **Registered Users**: Users already registered on MoEngage. Also used to update existing users in bulk.
* **Anonymous Users**: Users who have not yet registered on MoEngage.
* **Events** (Standard and User-Defined): Standard events such as Campaign Interaction Events, as well as your own user-defined events.
* **Auxiliary Data**: User data ingested into MoEngage temporarily for specific business purposes. Available for file-based sources only (S3, SFTP, and Manual Upload), not for data warehouses.
# Choose Your Import Path
Select the import method that matches where your data lives:
> [card] [Set Up a File Import](/docs/user-guide/data/imports/setting-up-a-file-import)
>
> Automate imports from files dropped in Amazon S3 or an SFTP server, on a one-time or periodic schedule.
> [card] [Set Up a Data Warehouse Import](/docs/user-guide/data/imports/setting-up-a-data-warehouse-import)
>
> Import directly from Snowflake, BigQuery, or Databricks tables and views. Connection-driven, with one-time or periodic syncs.
> [card] [Manual Uploads](/docs/user-guide/data/imports/manual-uploads)
>
> Upload a CSV directly in the dashboard for users or events. One-time only, no periodic scheduling.
> [card] [Auxiliary Data](/docs/user-guide/data/imports/auxiliary-data)
>
> Import supplementary data via S3, SFTP, or CSV, using a simple primary-key mapping model.
# How Imports Work
The following mechanics are common to every import source. Source-specific setup steps, limits, and failure behavior live on each source's setup page.
## Imports Dashboard
The Data Imports dashboard lists all your imports and their key details:
| **Column** | **Description** |
| - | - |
| **Name** | The name you gave the import while setting it up. |
| **Type** | The source of the import (S3, SFTP, CSV, Snowflake, BigQuery, or Databricks). The import type, One-Time or Periodic, is shown in brackets. |
| **Custom Segment** | If the user import saves to a segment, the segment name is displayed here. |
| **Created at** | The date and time the import was created. |
| **Last Sync Status** | The status of the most recent import run as a whole, not the status of the last file within that run (see statuses below). |
| **Files Processed** | The number of files processed to date. |
| **Rows Processed** | The total number of rows processed to date. |
| **Actions** | View Details, Edit, Duplicate, or Delete an import. |
> [!NOTE]
>
> Import schedule and detail times shown on the Data Imports dashboard use your app's configured timezone. If no app timezone is set, they display in UTC by default. Set the app timezone from **Settings** to see these times in your preferred timezone. This display timezone is separate from the requirement that mapped timestamp columns (such as **Event time** or **Updated at**) always be in UTC.
## Import Statuses
Every import on the dashboard carries one of the following statuses:
* **Scheduled**: The run is scheduled to execute in the future.
* **Pending**: One or more files in the run are held back because an hourly or daily import limit is reached. The run resumes on its own when the limit frees up, so no action is needed.
* **Processing**: The run is in progress.
* **Successful**: Every file in the run succeeded.
* **Partial Success**: The run finished with a mix of succeeded and failed files.
* **Failed**: Every file in the run failed. Hover over the status to see the reason.
* **Archived**: Someone archived the import. Archiving is a manual action rather than something MoEngage does on its own, and it cannot be undone, so an archived import cannot be restored. The run and file history of an archived import stays available.
* **Expired**: The import passed its end date. MoEngage sets this status itself, which is what separates it from **Archived**.
MoEngage derives the run status from the files in that run, in the following order:
| Condition | Run status |
| - | - |
| Any file is processing, or scheduled files are still queued | Processing |
| Any file is pending because a limit is reached or an internal retry is in progress | Pending |
| Every file reached a final state and all succeeded | Successful |
| Every file reached a final state and all failed | Failed |
| Every file reached a final state, with a mix of succeeded and failed | Partial Success |
A run that still contains a pending file stays **Pending**, even when other files in the same run have already failed. The run resolves to Partial Success only after every file reaches a final state.
To see how each scheduled run performed, click the kebab menu under **Actions**, and then click **View**. For more information, refer to [Run History](/docs/user-guide/data/imports/setting-up-a-file-import#run-history). You can export a copy of an imported file for up to 60 days. Keep your own copy of the files you import, because re-downloading a file from MoEngage is time-limited and not guaranteed.
## Check Import Limits
MoEngage applies separate hourly and daily import limits to three categories: **User imports**, **Event imports**, and **Aux data**. The Import limit overview tells you how much of each limit you have consumed, when the limits reset, which of your imports are held back, and which of them consumed the most.
These limits apply to file imports from Amazon S3, SFTP, and CSV upload. Data warehouse imports use a separate limit pool that this drawer does not cover.
### Open the Import Limit Overview
You can open the Import limit overview from the Data imports page, or while you are setting up an import.
To open it from the Data imports page, perform the following step:
1. Click **Check import limit**, beside **Import**.

To open it while you set up an import, perform the following steps:
1. Click **+ Import**, and then click **Users**, **Events**, or **Auxiliary data**.

2. In the dialog box, click **Check import limit**.

The dialog box also shows how much of your hourly and daily limit is left before you start, so you can tell whether an import is likely to be delayed before you set it up.
### Know Before You Reach a Limit
MoEngage notifies you as you approach a limit, so you can reschedule an import before it is held back. A banner appears at the top of the Data imports page when you reach 80% of a limit, warning that new imports might be delayed, and again when you reach a limit, naming the category and when imports resume. When more than one limit is reached, the banner names no resume time, because the affected limits can reset at different times; open the Import limit overview to see each one.
The banner appears on every tab, so a limit reached in one category is visible while you are viewing another. When you are below 80% on every limit, MoEngage shows no banner.

### Check How Much You Have Consumed
The Import limit overview shows one card for each category, with your hourly usage above and your daily usage below. The progress bar on each card shows how much of that limit you have consumed, as an amount against the limit and as a percentage.
To read the usage, perform any of the following actions:
1. Hover over the information icon beside **Usage** to view when each limit resets.
2. Click **Refresh** to update the figures.
3. Click the **User imports**, **Event imports**, or **Aux data** card to see the detail for that category.
Hourly limits reset on a rolling lookback window rather than at a fixed time, so usage ages out gradually. Daily limits reset every day at 12:00 AM UTC. The drawer does not refresh on its own, so the **Last updated at** timestamp shows when the figures were last read. After you select a card, the **Affected imports** and **Top contributing imports** sections below apply to that category.

### Check Which Imports Are Affected
**Affected imports** lists the imports held back by a limit, with a banner naming the limit that was reached and when the held-back files resume.

The table lists the following:
| Column | Description |
| - | - |
| Import name | The name of the affected import, linked to its details page. |
| Type | The source and schedule of the import, for example SFTP (Periodic). |
| Started at | When the import started, or is scheduled to start. |
| Status | **Pending** for an import with files held back, or **Scheduled** for an import that has not started. |
| Files processed | The number of files either currently being processed or finished processing so far. Shows `--` for an import that has not started. |
| Files left | The number of files still pending. Shows `--` for an import that has not started. |
The table lists every import held back because a limit was reached. If the hourly limit is reached, those imports resume as soon as the limit frees up. If the daily limit is reached, the pending and scheduled imports for that day resume the next day.
### Check Which Imports Consumed the Most
**Top contributing imports** shows which of your imports used the most of the limit, so you can find the cause before you add or reschedule an import. **Top contributing imports** appears after at least one import in the category completes a run.
The **Hourly** and **Daily** tabs change the period the table covers:
* Click **Hourly** for the imports that ran within the current rolling one-hour window.
* Click **Daily** for the imports that ran since the last reset at 12:00 AM UTC.
The table lists the following:
| Column | Description |
| - | - |
| Import name | The name of the import, linked to its details page. |
| Type | The source and schedule of the import. |
| Started at | When the import started. |
| Status | The status of the import. |
| Consumption | The volume the import consumed, as an absolute number and as a percentage of the total limit for that category and window. |

MoEngage sorts the table by the volume each import consumed and shows the top 5. Each percentage is that import's share of the limit for the category and window.
## Trigger Imports
You can trigger imports in the following ways:
1. **Manually**: Trigger a periodic import from the imports page by clicking **Actions**. Triggering an import within five minutes of its scheduled time may cause an error.
2. **API**: Trigger imports using the [File Imports Trigger API](https://www.moengage.com/docs/api/file-import/trigger-file-imports). Data Warehouses do not currently support these APIs.
# Mapping Files and Data Mapping
A mapping file contains the mappings between each source column and a MoEngage attribute, along with the data type of the column. The file must be in JSON format. Instead of mapping columns one by one on the dashboard, you can upload a mapping file to automate the mapping.
> [tab] CSV Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "ID", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "First Name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "First Seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "LTV", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "Install Status", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
> [tab] JSON Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "customer_id", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "user.first_name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "user.first_seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "attribution.lifetime_value", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "attribution.device_installed", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
For each column, provide the following fields:
1. **`column`** *(required)*: The column name from the source file. For Level 2 keys in a JSON file, use dot notation (`key1.key2`).
2. **`moe_attr`** *(required)*: The MoEngage attribute to map the column to. Ensure each column maps to a unique `moe_attr`.
3. **`type`** *(optional)*: The data type of the column. See the supported types below.
4. **`datetime_format`** *(optional)*: The date-time format. Mandatory for DateTime fields only.
5. **`is_skipped`** *(optional)*: A boolean field. Any column marked `true` is skipped during import.
### Standard User Properties for Reference
Map your source columns to MoEngage standard user properties using the keys below. For the exhaustive list, refer to your [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard.
| Key | Attribute Name on Dashboard | Datatype | Description |
| :- | :- | :- | :- |
| `uid` | ID | String | Unique ID that the app has set for a user. |
| `u_n` | Name | String | Full name of the user. |
| `u_fn` | First Name | String | First name of the user. |
| `u_ln` | Last Name | String | Last name of the user. |
| `u_em` | Email (Standard) | String | The email address of the user. For example, `john@example.com`. |
| `u_gd` | Gender | String | Gender of the user. |
| `u_bd` | Birthday | DateTime | Birth date of the user. Use this standard attribute instead of age; data sent as age is tracked as a custom attribute. |
| `u_mb` | Mobile Number (Standard) | String | Mobile number of the user. For example, `918888444411`. |
| `moe_geo_location` | Location | Array of `[lat,lng]` | The location of the user, in the format `{"lat": 12.11, "lon": 123.122}`. |
| `source` | Publisher Name | String | The publisher name of the install. For example, `Google Ads`. |
| `revenue` | LTV | Numeric | Lifetime value of the user. |
| `moe_unsubscribe` | Unsubscribe | Boolean | Email unsubscribe attribute. Emails are not sent to the user when set to `true`. |
| `moe_hard_bounce` | Hard Bounce | Boolean | Email hard bounce attribute. Emails are not sent to the user when set to `true`. |
| `moe_spam` | Spam | Boolean | Email spam attribute. Emails are not sent to the user when set to `true`. |
> [!WARNING]
>
> Track standard string attributes with the correct data type. For example, if **First Name** (`u_fn`) is ingested as a number or an array instead of a string, the sample users on the [Create segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments) page fail to load with a 500 error ("There seems to be an error"). To fix this, pin the attribute's data type to String on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard and re-send the corrected data for the affected users.
### Supported Attribute Types
| **Type** | **Description** | **Value in Mapping File** |
| - | - | - |
| String | Any string value. For example, `ABC`, `ABC XYZ`, `ABC123`. | `"type": "string"` |
| Double | Any decimal value. For example, `3.14159`, `241.23`, `-123.1`. | `"type": "double"` |
| Boolean | For example, `true`, `false`. | `"type": "bool"` |
| Date Time | Any date-time value. For example, `2019/02/22 17:54:14.933`. | `"type": "datetime"` |
> [!NOTE]
>
> MoEngage does not support the `|` (pipe) character in non-array type columns. Ensure your String, Numeric, and Boolean columns do not contain this character.
### Reserved Keywords for User Properties
MoEngage reserves the following keys. Do not use them when you map or track user properties.
* `USER_ATTRIBUTE_UNIQUE_ID`
* `USER_ATTRIBUTE_USER_EMAIL`
* `USER_ATTRIBUTE_USER_MOBILE`
* `USER_ATTRIBUTE_USER_NAME`
* `USER_ATTRIBUTE_USER_GENDER`
* `USER_ATTRIBUTE_USER_FIRST_NAME`
* `USER_ATTRIBUTE_USER_LAST_NAME`
* `USER_ATTRIBUTE_USER_BDAY`
* `USER_ATTRIBUTE_NOTIFICATION_PREF`
* `USER_ATTRIBUTE_OLD_ID`
* `MOE_TIME_FORMAT`
* `MOE_TIME_TIMEZONE`
* `USER_ATTRIBUTE_DND_START_TIME`
* `USER_ATTRIBUTE_DND_END_TIME`
* `MOE_GAID`
* `INSTALL`
* `UPDATE`
* `MOE_ISLAT`
* `status`
* `user_id`
* `source`
# Supported Datetime Formats
Use these formats in the `datetime_format` field of your mapping file, or when configuring date-time columns during setup.
| **Datetime Format** | **Examples** |
| - | - |
| `"datetime_format": "YYYY-MM-DD"` | 2022-01-22 |
| `"datetime_format": "YYYY/MM/DD"` | 2022/01/22 |
| `"datetime_format": "DD/MM/YYYY"` | 22/01/2022 |
| `"datetime_format": "DD-MM-YYYY"` | 22-01-2022 |
| `"datetime_format": "DD-MM-YYYY hh:mm:ss"` | 31-12-2022 12:10:33 |
| `"datetime_format": "DD/MM/YYYY hh:mm:ss"` | 31/12/2022 12:10:33 |
| `"datetime_format": "YYYY-MM-DD hh:mm:ss"` | 2019-02-22 17:54:14 |
| `"datetime_format": "YYYY/MM/DD hh:mm:ss"` | 2019/02/22 17:54:14 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ss.s"` | 31-12-2022T12:10:33.882 |
| `"datetime_format": "DD/MM/YYYYThh:mm:ss.s"` | 31/12/2022T12:10:33.882 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ssTZD"` |
|
# Frequently Asked Questions
> [accordion] My imports have failed. How do I check what went wrong?
>
> Click the ellipsis on the right and click **View** to look up the Import details. Hover over the **Failed** Status to learn the reason.
> [accordion] What if a scheduled import adds the data into a recently archived segment?
>
> In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.
> [accordion] Can an import be stopped while it's running?
>
> Once an import process starts, it can't be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It's best to let the current import finish.
> [accordion] How can I stop future runs of a scheduled import?
>
> Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the **Archive** option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.
> [accordion] What should I do if an import seems stuck or is taking a long time?
>
> If an import appears to be stuck or is taking longer than usual, it's best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it's still processing can cause conflicts and may prevent the original import from completing successfully.
# Set Up a Data Warehouse Import
Source: https://moengage.com/docs/user-guide/data/imports/setting-up-a-data-warehouse-import
Import users and events directly from Snowflake, BigQuery, and Databricks tables and views into MoEngage. Set up the connection, map columns, and schedule syncs.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
MoEngage imports users and events directly from tables and views in your data warehouse: Snowflake, BigQuery, or Databricks. Warehouse imports are connection-driven: you grant MoEngage read access, map your columns once, and run the import on a one-time or periodic schedule.
Select your warehouse in any tabbed section below and the page stays on that warehouse throughout.
# Types of Imports
MoEngage can import the following from your data warehouse:
* **Registered Users**: Users who are already registered on MoEngage. Also used to bulk-update existing users.
* **Anonymous Users**: Users who are not yet registered on MoEngage.
* **Events** (Standard and User-Defined): Standard events such as Campaign Interaction Events, as well as your own user-defined events.
> [!NOTE]
>
> Auxiliary Data is not supported for data warehouse imports. It is available for file-based sources only. See [Auxiliary Data](/docs/user-guide/data/imports/auxiliary-data).
# Prepare Your Data
MoEngage does not require a specific table schema. Every column can be mapped or skipped on the dashboard. Before you set up the import, note how MoEngage detects changed rows:
> [tab] User Imports
>
> For periodic User Imports, MoEngage syncs only the data that changed since the last sync. It uses a timestamp (date + time) column, commonly named `updated_at`, to identify changed rows. You can name this column anything, as long as it holds the timestamp of when the row last changed, and map it on the dashboard.
> [tab] Event Imports
>
> For Event Imports, you must map a column containing the event's timestamp (date + time) in UTC. MoEngage uses it to sync new events since the previous sync. To import standard MoEngage events, ensure the event names in your table match MoEngage's standard event names.
**Importing datetime attributes:** When you map a column that holds dates or times, create it as a **Date Time** attribute and select the matching format (see [Supported Datetime Formats](#supported-datetime-formats)). After the first successful import, an account Admin should open [Data Management](/docs/user-guide/settings/data-management/overview-data-management) and set the **allowed data type** to *datetime* for each new attribute, for both user and event properties. Until the data type is pinned, values may not be ingested or segmented as datetime.
## How Periodic Sync Detects Changed Rows
For **periodic** imports, MoEngage syncs each run over a fixed time window `[last_run_time, next_run_time)`, half-open and non-overlapping, advancing on a fixed wall-clock cadence (for an hourly import, `last_run_time + 1 hour`), never derived from the data seen. A row is included in a run only if its mapped reference timestamp (`Updated At` for users; `Updated At`, or `Event Time` when not mapped separately, for events) falls inside that window.
Because windows only ever move forward, **a row whose reference timestamp is earlier than the current `last_run_time` is permanently missed**, not delayed, and not caught up on a later run. This applies no matter why the timestamp is early: upstream pipeline delay, an intentional backfill, a missing `Updated At` mapping, or a timezone conversion that shifts the value backward. The first, historic run has no lower bound, which is why it never loses data this way. See the note in [Step 3](#step-3-select-the-import-frequency).
> [accordion] Deep dive: entity behavior, timezone pitfalls, and a worked example
>
> ### Users vs Events
>
> **Users**, a single `Updated At` column drives both *what changed* and *when it changed*; the two cannot be decoupled. To avoid permanent misses, ensure `Updated At` reflects **table write-time**, not business or event time. This is commonly done with a view whose column defaults to `CURRENT_TIMESTAMP` on insert, so even late-arriving writes get a current, ever-advancing timestamp.
>
> **Events**, two separate mappable columns:
>
> * `Event Time`, the true, possibly-backdated business timestamp, used for analytics.
> * `Updated At`, drives the delta filter; defaults to `Event Time` if not mapped separately.
>
> Mapping `Updated At` to table write-time lets genuinely backdated events still import via periodic sync without corrupting `Event Time` for analysis. If you leave `Updated At` defaulted to `Event Time`, backdated events carry the same permanent-miss risk as users. Events are immutable in MoEngage once imported, there is no update-in-place for a previously synced event.
>
> ### The Reference Column Must Be Genuine UTC
>
> Across all three warehouses, the mapped reference column's values must be genuine UTC. What MoEngage does with that column differs:
>
> > [tab] Snowflake
> >
> > MoEngage converts the column using `CONVERT_TIMEZONE('UTC', col)`. For a `TIMESTAMP_NTZ` column, the conversion first interprets the naive value using the session's effective timezone (session → user → account, in that precedence). If that timezone isn't actually UTC, an already-correct value is double-shifted. Check it with `SHOW PARAMETERS LIKE 'TIMEZONE'` and, if needed, set it at the user level for the MoEngage connection user.
>
> > [tab] BigQuery
> >
> > MoEngage applies no conversion, the raw column value is compared directly. The risk is specific to `DATETIME`-typed columns (naive, no timezone) holding non-UTC values. `TIMESTAMP`-typed columns are safe by construction, because BigQuery stores them as true UTC instants.
>
> > [tab] Databricks
> >
> > MoEngage applies no conversion and reads only `TIMESTAMP`-typed columns over its connector. (Databricks' `TIMESTAMP_NTZ` type isn't supported over JDBC/ODBC, so it isn't a path here.) Since `TIMESTAMP` is already UTC-normalized, the only realistic failure mode is your own pipeline writing local-time values into a UTC-typed column, a data-hygiene issue.
>
> An import can run in a timezone different from your workspace timezone, but schedule run times are always computed and stored in UTC. Choosing a non-UTC import timezone only changes the time the schedule appears to run in the UI, it does not change the window mechanics above.
>
> ### Worked Example
>
> > [tab] User Imports
> >
> > Suppose you create an hourly Users import at `10:07 UTC`. The first `next_run_time` fast-forwards to the next hour boundary, `11:00 UTC`, and the **historic run** imports every matching row up to `11:00`. Each table below shows the full source table state after a run, along with the run that imported each row.
> >
> > After the historic run (imports everything with `Updated At < 11:00`):
> >
> > | user_id | updated_at (UTC) | Imported in |
> > | - | - | - |
> > | u_100 | 10:50 | Historic run |
> >
> > Before Run 1, `u_101` is written with `Updated At = 11:30`. Run 1 covers the window `[11:00, 12:00)`:
> >
> > | user_id | updated_at (UTC) | Imported in |
> > | - | - | - |
> > | u_100 | 10:50 | Historic run |
> > | u_101 | 11:30 | Run 1 |
> >
> > `u_101` (`11:30`) falls inside `[11:00, 12:00)`, so Run 1 imports it cleanly.
> >
> > Before Run 2, two more rows land: `u_102` with `Updated At = 12:00:00`, and `u_103`, physically written to the table at `12:45` but carrying a backdated `Updated At = 09:15`. Run 2 covers `[12:00, 13:00)`:
> >
> > | user_id | updated_at (UTC) | Imported in |
> > | - | - | - |
> > | u_100 | 10:50 | Historic run |
> > | u_101 | 11:30 | Run 1 |
> > | u_102 | 12:00:00 | Run 2 |
> > | u_103 | 09:15 | Not imported |
> >
> > `u_102` sits exactly on the boundary: it was excluded from Run 1 (`< 12:00` fails there) and imported by Run 2 (`>= 12:00` passes), no gap, no double-count. `u_103` carries `Updated At = 09:15`, already earlier than Run 2's lower bound of `12:00`, and earlier than the `11:00` historic cutoff too, so no run's window contains it.
> >
> > Run 3 covers `[13:00, 14:00)`. No new rows have landed, and `u_103` is still sitting in the table:
> >
> > | user_id | updated_at (UTC) | Imported in |
> > | - | - | - |
> > | u_100 | 10:50 | Historic run |
> > | u_101 | 11:30 | Run 1 |
> > | u_102 | 12:00:00 | Run 2 |
> > | u_103 | 09:15 | Not imported |
> >
> > `u_103` never appears in any run, because `09:15` is earlier than every future `last_run_time`. It is permanently missed, even though it was added to the table only moments before Run 3.
>
> > [tab] Event Imports
> >
> > Events expose two mappable columns: `Event Time` (the true business timestamp, kept for analytics) and `Updated At` (drives the delta filter). This example uses the same hourly cadence (created `10:07 UTC`, historic cutoff `11:00`) and imports on `2024-01-16 UTC`. As before, each table shows the full source table state after a run.
> >
> > After the historic run (imports everything with `Updated At < 11:00`):
> >
> > | event | user_id | event_time (UTC) | updated_at (UTC) | Imported in |
> > | - | - | - | - | - |
> > | purchase | u_200 | 2024-01-16 10:40 | 2024-01-16 10:40 | Historic run |
> >
> > `u_200`'s `Updated At` (`10:40`) is before the `11:00` cutoff, so the historic run imports it.
> >
> > Before Run 1, two events are written. `u_201`'s event happened in real time at `11:45`. `u_202`'s event happened *yesterday* (`2024-01-15 18:00`) but only landed in the table today, with `Updated At` set to its true write-time (`11:20`). Run 1 covers `[11:00, 12:00)`:
> >
> > | event | user_id | event_time (UTC) | updated_at (UTC) | Imported in |
> > | - | - | - | - | - |
> > | purchase | u_200 | 2024-01-16 10:40 | 2024-01-16 10:40 | Historic run |
> > | purchase | u_201 | 2024-01-16 11:45 | 2024-01-16 11:45 | Run 1 |
> > | purchase | u_202 | 2024-01-15 18:00 | 2024-01-16 11:20 | Run 1 |
> >
> > `u_201` (`Updated At = 11:45`) falls inside `[11:00, 12:00)` and imports cleanly. `u_202` also imports, even though its `Event Time` is a day old, the delta filter reads `Updated At` (write-time `11:20`, inside the window), not `Event Time`. MoEngage stores the event at its real `Event Time` (`2024-01-15 18:00`), so analytics still reflect when it actually happened.
> >
> > Before Run 2, two more events are written. `u_203`'s `Updated At` is exactly `12:00:00`. `u_204` is a backdated event whose customer left `Updated At` **defaulted to `Event Time`** (`09:30`), so the two columns aren't decoupled. Run 2 covers `[12:00, 13:00)`:
> >
> > | event | user_id | event_time (UTC) | updated_at (UTC) | Imported in |
> > | - | - | - | - | - |
> > | purchase | u_200 | 2024-01-16 10:40 | 2024-01-16 10:40 | Historic run |
> > | purchase | u_201 | 2024-01-16 11:45 | 2024-01-16 11:45 | Run 1 |
> > | purchase | u_202 | 2024-01-15 18:00 | 2024-01-16 11:20 | Run 1 |
> > | purchase | u_203 | 2024-01-16 12:00:00 | 2024-01-16 12:00:00 | Run 2 |
> > | refund | u_204 | 2024-01-16 09:30 | 2024-01-16 09:30 | Not imported |
> >
> > `u_203`'s `Updated At` sits exactly on the boundary: it was excluded from Run 1 (`< 12:00` fails there) and imported by Run 2 (`>= 12:00` passes), no gap, no double-count. `u_204`'s `Updated At` is `09:30`, earlier than Run 2's lower bound of `12:00` and the `11:00` historic cutoff, so no window contains it, and it is missed. The only difference from `u_202`, which imported successfully, is that `u_202` mapped `Updated At` to write-time while `u_204` left it defaulted to `Event Time`.
> >
> > Run 3 covers `[13:00, 14:00)`. No new events have landed, and `u_204` is still in the table:
> >
> > | event | user_id | event_time (UTC) | updated_at (UTC) | Imported in |
> > | - | - | - | - | - |
> > | purchase | u_200 | 2024-01-16 10:40 | 2024-01-16 10:40 | Historic run |
> > | purchase | u_201 | 2024-01-16 11:45 | 2024-01-16 11:45 | Run 1 |
> > | purchase | u_202 | 2024-01-15 18:00 | 2024-01-16 11:20 | Run 1 |
> > | purchase | u_203 | 2024-01-16 12:00:00 | 2024-01-16 12:00:00 | Run 2 |
> > | refund | u_204 | 2024-01-16 09:30 | 2024-01-16 09:30 | Not imported |
> >
> > `u_204` still does not import, because `09:30` is earlier than every future `last_run_time`, so the miss does not self-correct. Because events are immutable once imported, there is no update-in-place to fix `u_204` later, recovery requires a one-time import (see below).
>
> ### Recovering Missed or Backdated Data
>
> Once data is already missed, periodic sync will not pick it up. To recover it, or to intentionally backfill, build a one-time view containing the corrected or missed records and run a **one-time import** against it. One-time imports have no lower-bound filter, so they capture every matching row regardless of reference timestamp. Alternatively, duplicate the import (which triggers a fresh historic run) or edit the schedule's start time backward to force `last_run_time` to recompute.
# Required Access Permissions
MoEngage requires `READ` access to your warehouse. Grant the permissions below to an existing database user or a dedicated MoEngage user.
> [tab] Snowflake
>
> Grant MoEngage `READ` access to the database you want to import from. For the connection setup and required grants, see the [Snowflake connection guide](/docs/partner-guide/data-and-analytics/data-warehouses/snowflake).
> [tab] BigQuery
>
> Grant MoEngage the necessary permissions on your dataset. For the full list and setup, see [Grant Permissions to MoEngage](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery).
> [tab] Databricks
>
> MoEngage's Databricks import is built on Unity Catalog. Grant the following to an existing or dedicated user, replacing `catalog_name`, `schema_name`, and `user@example.com` with your values:
>
> ```sql theme={null}
> -- Required: read data from all tables in the schema
> GRANT SELECT ON SCHEMA `catalog_name`.`schema_name` TO `user@example.com`;
> -- Required: access and reference the schema
> GRANT USE SCHEMA ON SCHEMA `catalog_name`.`schema_name` TO `user@example.com`;
> ```
>
> Both grants are required: `USE SCHEMA` allows MoEngage to access the schema, and `SELECT` allows it to read data from the tables within. Without `USE SCHEMA`, a user cannot access the schema even with `SELECT` on its tables.
## IP Whitelisting
MoEngage recommends that you whitelist all the MoEngage IPs listed for your data center under [Data Transfer](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage#data-transfer). MoEngage connects to your system from these IPs for data imports, data warehouse exports, streams, and connection tests on the App Marketplace. To find your data center, see [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
> [tab] Snowflake
>
> Add the MoEngage IPs to a network policy for the MoEngage user. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/snowflake#enable-ip-whitelisting).
> [tab] BigQuery
>
> Add the MoEngage IPs to a VPC Service Controls access level for your BigQuery project. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery#step-2-enable-ip-whitelisting).
> [tab] Databricks
>
> Add the MoEngage IPs to an IP access list for your workspace. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/data-warehouses/databricks#step-4-enable-ip-whitelisting).
# Set Up the Import
Set up your import in three steps: select your connection and table source, map your columns to MoEngage attributes, and select the import frequency.
> [!TIP]
>
> **Prerequisites**
>
> * An existing warehouse connection set up in the MoEngage App Marketplace with the permissions above.
> * Ensure the MoEngage IPs for your data center are whitelisted. For details, see [IP Whitelisting](#ip-whitelisting).
> * To import JSON as an Object data type, [Object Data Type support](/docs/user-guide/data/key-concepts/support-for-object-data-type) must be enabled for your account (optional).
To start, on the MoEngage sidebar go to **Data** > **Data imports**, open the **Data warehouses** tab, click **+ Import** in the upper-right corner, and select **Users** or **Events**.

Then select your warehouse tile and click **Continue**.
> [tab] Snowflake
>
> 
> [tab] BigQuery
>
> 
> [tab] Databricks
>
> 
## Step 1: Select Your Connection and Table Source
Enter a name for this import to identify it on the Imports Dashboard. Based on the import type, your next steps vary:
> [tab] User Imports
>
> Select whether to import **Registered users**, **Anonymous users**, or both together.
> [tab] Event Imports
>
> Select the event you want to import, or create a new one. If a single table holds multiple events, MoEngage uses the **Event Name** column to determine which rows to import, the value depends on the event you select. Event display names and event names can differ; view them on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) page. For example, the event *App/Site Opened* has the event name `MOE_APP_OPENED`.
>
> To create a new event, click **+ Create event** at the end of the **Select event** list and enter a unique name. New events appear on the Data Management page only after the first successful import.
Next, select the connection and the table or view to import from. If you have not created a connection, click **+ Add connection** to set one up in the App Marketplace. After selecting the connection, choose the **Schema/Dataset** and **Table/View**. If schemas fail to load, confirm you granted the permissions above.
For a table containing multiple events, first **Preview** the table, then select **Table contains multiple events** and mark the column that holds the event name. Preview again to confirm the filtered rows before proceeding.
> [tab] Snowflake
>
> 
>
> 
> [tab] BigQuery
>
> 
>
> 
> [tab] Databricks
>
> 
>
> 
## Step 2: Map Your Columns to MoEngage Attributes
Map each table column to a MoEngage attribute. For every column you see:
1. **Column name**: The source column, with a sample value from the fetched table.
2. **Map attribute**: The MoEngage attribute to map to. Some attributes accept multiple data types, so pick the column's data type. For DateTime columns, also pick the format.
3. **Action**: Optionally skip the column. Skipped columns are not imported.
Once a mandatory mapping is marked, you can no longer skip that column. To create a new attribute, click **+ Create attribute**, enter a name, and select a data type. New attributes appear on the Data Management page only after the first successful import.
### Mandatory Mappings
The timestamp column type differs by warehouse:
> [tab] Snowflake
>
> > [accordion] User Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID (Registered) / Anonymous ID (Anonymous) | A column with a unique user identifier, or an identifier such as email or mobile for anonymous users. For **All Users**, map both, users with an empty User ID are imported as anonymous. |
> > | Updated at | Determines which rows changed since the last sync. Must be a UTC timestamp of column type `TIMESTAMP_NTZ`. |
>
> > [accordion] Event Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID | Matches MoEngage user IDs to your events. |
> > | Event time | Timestamp (date + time) of when the event occurred, in UTC. Column type `TIMESTAMP`. Converted to your dashboard timezone. |
> > | Updated on | Determines which rows changed since the last sync; use for backdated events or upstream delays. UTC, column type `TIMESTAMP`. If unavailable, select *Use same as Event time*. |
> [tab] BigQuery
>
> > [accordion] User Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID | A column with a unique user identifier. |
> > | Updated on | Determines which rows changed since the last sync. Must be a UTC timestamp of column type `TIMESTAMP`. |
>
> > [accordion] Event Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID | Matches MoEngage user IDs to your events. |
> > | Event time | Timestamp (date + time) of when the event occurred, in UTC. Column type `DATETIME`. Converted to your dashboard timezone. |
> > | Updated on | Determines which rows changed since the last sync; use for backdated events or upstream delays. UTC, column type `DATETIME`. If unavailable, select *Use same as Event time*. |
> [tab] Databricks
>
> > [accordion] User Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID (Registered) / Anonymous ID (Anonymous) | A column with a unique user identifier, or an identifier such as email or mobile for anonymous users. For **All Users**, map both, users with an empty User ID are imported as anonymous. |
> > | Updated at | Determines which rows changed since the last sync. Must be a UTC timestamp of column type `TIMESTAMP`. |
>
> > [accordion] Event Imports
> >
> > | Mapping | Description |
> > | - | - |
> > | User ID | Matches MoEngage user IDs to your events. |
> > | Event time | Timestamp (date + time) of when the event occurred, in UTC. Column type `TIMESTAMP`. Converted to your dashboard timezone. |
> > | Updated on | Determines which rows changed since the last sync; use for backdated events or upstream delays. UTC, column type `TIMESTAMP`. If unavailable, select *Use same as Event time*. |
If you have [Unified Identity](/docs/user-guide/data/user-data/unified-identity-identity-resolution) enabled, you will have an option to map the additional identifiers as well. For the complete list of supported datetime formats, see [Supported Datetime Formats](#supported-datetime-formats) below.
### Mapping Files
Optionally, auto-map your columns by uploading a mapping file. Click **Upload mapping file** at the top-right of the mapping table and select your file. MoEngage auto-configures the mapping; if the mapping file references attributes that don't exist yet, a modal lets you create them during import.
A mapping file contains the mappings between each source column and a MoEngage attribute, along with the data type of the column. The file must be in JSON format. Instead of mapping columns one by one on the dashboard, you can upload a mapping file to automate the mapping.
> [tab] CSV Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "ID", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "First Name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "First Seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "LTV", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "Install Status", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
> [tab] JSON Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "customer_id", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "user.first_name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "user.first_seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "attribution.lifetime_value", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "attribution.device_installed", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
For each column, provide the following fields:
1. **`column`** *(required)*: The column name from the source file. For Level 2 keys in a JSON file, use dot notation (`key1.key2`).
2. **`moe_attr`** *(required)*: The MoEngage attribute to map the column to. Ensure each column maps to a unique `moe_attr`.
3. **`type`** *(optional)*: The data type of the column. See the supported types below.
4. **`datetime_format`** *(optional)*: The date-time format. Mandatory for DateTime fields only.
5. **`is_skipped`** *(optional)*: A boolean field. Any column marked `true` is skipped during import.
### Standard User Properties for Reference
Map your source columns to MoEngage standard user properties using the keys below. For the exhaustive list, refer to your [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard.
| Key | Attribute Name on Dashboard | Datatype | Description |
| :- | :- | :- | :- |
| `uid` | ID | String | Unique ID that the app has set for a user. |
| `u_n` | Name | String | Full name of the user. |
| `u_fn` | First Name | String | First name of the user. |
| `u_ln` | Last Name | String | Last name of the user. |
| `u_em` | Email (Standard) | String | The email address of the user. For example, `john@example.com`. |
| `u_gd` | Gender | String | Gender of the user. |
| `u_bd` | Birthday | DateTime | Birth date of the user. Use this standard attribute instead of age; data sent as age is tracked as a custom attribute. |
| `u_mb` | Mobile Number (Standard) | String | Mobile number of the user. For example, `918888444411`. |
| `moe_geo_location` | Location | Array of `[lat,lng]` | The location of the user, in the format `{"lat": 12.11, "lon": 123.122}`. |
| `source` | Publisher Name | String | The publisher name of the install. For example, `Google Ads`. |
| `revenue` | LTV | Numeric | Lifetime value of the user. |
| `moe_unsubscribe` | Unsubscribe | Boolean | Email unsubscribe attribute. Emails are not sent to the user when set to `true`. |
| `moe_hard_bounce` | Hard Bounce | Boolean | Email hard bounce attribute. Emails are not sent to the user when set to `true`. |
| `moe_spam` | Spam | Boolean | Email spam attribute. Emails are not sent to the user when set to `true`. |
> [!WARNING]
>
> Track standard string attributes with the correct data type. For example, if **First Name** (`u_fn`) is ingested as a number or an array instead of a string, the sample users on the [Create segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments) page fail to load with a 500 error ("There seems to be an error"). To fix this, pin the attribute's data type to String on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard and re-send the corrected data for the affected users.
### Supported Attribute Types
| **Type** | **Description** | **Value in Mapping File** |
| - | - | - |
| String | Any string value. For example, `ABC`, `ABC XYZ`, `ABC123`. | `"type": "string"` |
| Double | Any decimal value. For example, `3.14159`, `241.23`, `-123.1`. | `"type": "double"` |
| Boolean | For example, `true`, `false`. | `"type": "bool"` |
| Date Time | Any date-time value. For example, `2019/02/22 17:54:14.933`. | `"type": "datetime"` |
> [!NOTE]
>
> MoEngage does not support the `|` (pipe) character in non-array type columns. Ensure your String, Numeric, and Boolean columns do not contain this character.
### Reserved Keywords for User Properties
MoEngage reserves the following keys. Do not use them when you map or track user properties.
* `USER_ATTRIBUTE_UNIQUE_ID`
* `USER_ATTRIBUTE_USER_EMAIL`
* `USER_ATTRIBUTE_USER_MOBILE`
* `USER_ATTRIBUTE_USER_NAME`
* `USER_ATTRIBUTE_USER_GENDER`
* `USER_ATTRIBUTE_USER_FIRST_NAME`
* `USER_ATTRIBUTE_USER_LAST_NAME`
* `USER_ATTRIBUTE_USER_BDAY`
* `USER_ATTRIBUTE_NOTIFICATION_PREF`
* `USER_ATTRIBUTE_OLD_ID`
* `MOE_TIME_FORMAT`
* `MOE_TIME_TIMEZONE`
* `USER_ATTRIBUTE_DND_START_TIME`
* `USER_ATTRIBUTE_DND_END_TIME`
* `MOE_GAID`
* `INSTALL`
* `UPDATE`
* `MOE_ISLAT`
* `status`
* `user_id`
* `source`
**Mapping discrepancy rules:**
* Columns mapped to a non-existent MoEngage attribute (that you don't create via the modal) are left blank for manual mapping.
* Columns in the mapping file but not in your source table or view are ignored.
* Columns in the table but missing from the mapping file are left blank for manual mapping.
### Support for Object Data Type
MoEngage can import JSON columns as an Object data type (Object Data Type support must be enabled for your account). MoEngage maps only top-level attributes, nested attributes are not supported. You can map existing Object attributes or create new ones during mapping.
Store the JSON in the correct column type for your warehouse:
> [tab] Snowflake
>
> Change the column data type to `VARIANT`. The stored value must be valid JSON. For more information, see the [Snowflake JSON basics tutorial](https://docs.snowflake.com/en/user-guide/tutorials/json-basics-tutorial).
>
> ```json theme={null}
> { "Designation": "SSE", "Palace": "Bangalore", "age": 30, "name": "Shasha" }
> ```
> [tab] BigQuery
>
> Set the column data type to `JSON` when creating the table. The stored value must be valid JSON.
>
> ```json theme={null}
> { "Designation": "SSE", "Palace": "Bangalore", "age": 30, "name": "Shasha" }
> ```
> [tab] Databricks
>
> Change the column data type to `VARIANT`. The stored value must be valid JSON. For more information, see the [Databricks VARIANT type reference](https://docs.databricks.com/aws/en/sql/language-manual/data-types/variant-type).
>
> ```json theme={null}
> { "Designation": "SSE", "Palace": "Bangalore", "age": 30, "name": "Shasha" }
> ```
### Portfolio Support (Project-Level Routing)
You can route imported events to specific projects in your MoEngage portfolio workspace using column mapping. Map your project identifier column (such as `brand_name` or `app_id`) to the MoEngage attribute `moe_project_name`. Values must match your MoEngage project names exactly (matching is case-sensitive).
* **Successful routing**: If the value matches a project in your portfolio, MoEngage ingests the user or event at that project level.
* **Fallback**: If the mapping is missing, blank, or does not match a project name, MoEngage ingests the data at your global portfolio level.
### Save Users as a Segment
When importing users, turn on **Save as a custom segment** to add the imported users to a MoEngage segment. Enter a segment name and select the identifier column. Users are added to this segment on every sync (append only, no users are removed), so you can target them with campaigns.
### Import Behaviour
> [tab] User Imports
>
> For User Imports, select **Skip new users during this import** under Import Behaviour to bulk-update attributes without creating new users. MoEngage creates no new users from this import, and a row whose identifier is not already in MoEngage is ignored.
> [tab] Event Imports
>
> For event imports, select **Skip duplicate rows** to perform de-duplication on the selected column. MoEngage will skip any row with a duplicate value in that column, and only the first occurrence is ingested. If you do not select this option, MoEngage ingests all rows, including duplicates.
### Send Import Notifications
Turn on **Send import status to** and select up to **10 email recipients**. MoEngage emails you when an import is created, succeeds, or fails. When your mappings are complete, click **Next**.
## Step 3: Select the Import Frequency
Define when MoEngage syncs with your table:
* **One-Time**: Run as soon as possible or at a scheduled date and time. All matching rows are imported.
* **Periodic**: Run hourly, daily, weekly, or monthly, with intervals and advanced configurations.
Optionally, set the import to end after a number of occurrences or on a specific date. Click **Done**.
> [!WARNING]
>
> The first run of any import fetches all matching rows from your table (a historical import). Every subsequent run pulls only changed rows.
> [!NOTE]
>
> Import schedule and detail times shown on the Data Imports dashboard use your app's configured timezone. If no app timezone is set, they display in UTC by default. Set the app timezone from **Settings** to see these times in your preferred timezone. This display timezone is separate from the requirement that mapped timestamp columns (such as **Event time** or **Updated at**) always be in UTC.
# Supported Datetime Formats
Use these in the `datetime_format` field of your mapping file, or when configuring DateTime columns during mapping.
| **Datetime Format** | **Examples** |
| - | - |
| `"datetime_format": "YYYY-MM-DD"` | 2022-01-22 |
| `"datetime_format": "YYYY/MM/DD"` | 2022/01/22 |
| `"datetime_format": "DD/MM/YYYY"` | 22/01/2022 |
| `"datetime_format": "DD-MM-YYYY"` | 22-01-2022 |
| `"datetime_format": "DD-MM-YYYY hh:mm:ss"` | 31-12-2022 12:10:33 |
| `"datetime_format": "DD/MM/YYYY hh:mm:ss"` | 31/12/2022 12:10:33 |
| `"datetime_format": "YYYY-MM-DD hh:mm:ss"` | 2019-02-22 17:54:14 |
| `"datetime_format": "YYYY/MM/DD hh:mm:ss"` | 2019/02/22 17:54:14 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ss.s"` | 31-12-2022T12:10:33.882 |
| `"datetime_format": "DD/MM/YYYYThh:mm:ss.s"` | 31/12/2022T12:10:33.882 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ssTZD"` |
|
> [!NOTE]
>
> **Snowflake only:** Snowflake imports additionally support `"datetime_format": "YYYY-MM-DD hh:mm:ss.sTZD"`, for example, `2019-01-31 17:54:14.957299-08:00` or `2019-01-31 17:54:14.957299+08:00`.
# Duplicate Imports
You can configure only one unique import at a time. An import is a duplicate when **all** of these match an existing import:
1. **Import type**: Users or Events.
2. **Import sub-type**: Event name, or Registered / Anonymous / All users.
3. **Warehouse connection**.
4. **Schema/Dataset and Table/View**.
If any one of these differs, the import is unique.
# Limits
Data warehouse imports are subject to the following ingestion rate limits (defaults, contact MoEngage to increase):
> [!WARNING]
>
> **Imported data is subject to archival**
>
> MoEngage archives inactive users, events, and devices every 14 days and deletes the archived data permanently. Registered users are archived after 365 days without activity or campaign engagement, and anonymous users after 60 days.
>
> Importing or updating user properties does not count as activity, so it does not postpone archival. Only events and campaign engagement do.
>
> Before you import, check the criteria in [Data Archival (Retention) Policy](/docs/user-guide/data/key-concepts/data-archival-retention-policy) to confirm which of your records qualify.
| Phase | Hourly | Daily |
| - | - | - |
| Normal (default) | 600K rows/hr | 14M rows/day |
| Migration (upon request) | 15M rows/hr | 50M rows/day |
The first run of any import is a historical sync that pulls in all matching rows and uses the higher migration limit. Every subsequent periodic run uses the normal limit.
# Import Failure Policy
In the event of a connection failure (for example, credentials, network, or warehouse unavailability), a recurring import retries up to 10 times. If all retries fail, the import is marked FAILED.
| Policy | Description | Action |
| - | - | - |
| Automatic Retry | MoEngage retries the import up to 10 times to restore the connection. | None. MoEngage handles this automatically. |
| Import Failure | If all 10 retries fail, MoEngage marks the import FAILED and stops all future runs. | Investigate and restart (see below). |
### Restart a Failed Import
A FAILED import requires manual intervention:
1. Investigate and resolve the underlying issue on your warehouse (for example, update credentials, check permissions, or ensure warehouse availability).
2. Manually duplicate the import from the MoEngage UI to restart it.
3. Check the imported data for duplicates. Duplicating a failed import starts a new historical import, so if the original import previously succeeded, this may create redundant data. To control data flow, MoEngage recommends using views.
> [!NOTE]
>
> * The first successful run of any new recurring import is always a historical import (it fetches all data from the configured table/view).
> * Because the historical run pulls in all matching rows, a very large single import can fail to complete, for example, the run may time out or its schedule may expire, due to payload-size and processing-time limits. If you have a large dataset, split it into multiple smaller imports (for example, by date range) instead of importing everything in a single sync.
# Manage Your Imports
To monitor your imports, understand import statuses, or trigger a run manually or via API, see [How Imports Work](/docs/user-guide/data/imports/overview-imports#how-imports-work) on the Imports Overview.
# Frequently Asked Questions
> [accordion] My imports have failed. How do I check what went wrong?
>
> Click the ellipsis on the right and click **View** to look up the Import details. Hover over the **Failed** Status to learn the reason.
> [accordion] What if a scheduled import adds the data into a recently archived segment?
>
> In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.
> [accordion] Can an import be stopped while it's running?
>
> Once an import process starts, it can't be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It's best to let the current import finish.
> [accordion] How can I stop future runs of a scheduled import?
>
> Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the **Archive** option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.
> [accordion] What should I do if an import seems stuck or is taking a long time?
>
> If an import appears to be stuck or is taking longer than usual, it's best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it's still processing can cause conflicts and may prevent the original import from completing successfully.
> [accordion] Can I import data across tables?
>
> No. Writing manual queries (to perform joins, and so on) is not supported. Create a dedicated table or view with all the columns you want to import into MoEngage.
> [accordion] Do you support importing Views?
>
> Yes. MoEngage also supports importing data from your data warehouse Views. If you grant MoEngage access to read Views, they are automatically listed in the Table/View selection dropdown.
> [accordion] Can I do a historical import?
>
> Yes. Creating a one-time import is essentially the same as importing historical data, because MoEngage pulls in all the rows on the first sync.
> [accordion] My import shows status Successful but 0 rows were processed, what does this mean?
>
> A Successful status with 0 rows processed is not necessarily an error, it often means the run genuinely found no rows to process. The most common causes are:
>
> * **No new or changed rows since the last run.** After the first import, subsequent runs only include rows added or updated since the previous sync, based on the mapped reference (`Updated at`) column. If nothing changed, no rows are processed.
> * **No rows match the selected event.** For event imports, MoEngage processes only the rows whose **Event Name** column matches the event you selected. If none match, no rows are processed.
> * **The mapped reference column isn't genuine UTC**: Or it reflects business/event time rather than write-time, so backdated rows fall outside the current window and are permanently skipped (see the warehouse-specific guidance and periodic-sync behavior explained earlier on this page).
>
> To check whether 0 rows is expected, confirm that rows were added or updated after the last successful sync time, and that the **Event Name** values match the event you selected. The MoEngage UI does not currently expose your import's query window or query ID, so if none of these explanations fit, contact MoEngage Support for further investigation.
> [tab] Snowflake
>
> No Snowflake-specific questions beyond the above.
> [tab] BigQuery
>
> > [accordion] What should the BigQuery column data type be for JSON data to import as an Object Data Type?
> >
> > BigQuery requires the column type to be `JSON` at table creation.
>
> > [accordion] How does MoEngage import STRUCT columns in BigQuery?
> >
> > MoEngage imports `STRUCT` columns as Object data types, pulling in the struct's schema and creating a corresponding set of fields. You cannot cherry-pick or rename individual fields within a struct during import.
>
> > [accordion] How does MoEngage handle BigQuery TIMESTAMP columns with local time zones instead of UTC?
> >
> > MoEngage applies no timezone conversion to your reference column, it compares the raw value directly. `TIMESTAMP`-typed columns are safe, because BigQuery stores them as true UTC instants. The risk is with `DATETIME`-typed columns, which are naive (no timezone): if they hold non-UTC values, the delta filter uses those values as-is. Store UTC values in `DATETIME` columns, or use the `TIMESTAMP` type.
> [tab] Databricks
>
> > [accordion] Does MoEngage support Databricks Unity Catalog connections, and how does the setup differ?
> >
> > Yes. MoEngage's Databricks import is built on Unity Catalog, so the setup is the same as a standard Databricks connection.
>
> > [accordion] Are there specific version requirements for Databricks or Databricks SQL Warehouses?
> >
> > No, there are no specific version requirements for compatibility.
>
> > [accordion] What should the Databricks column data type be for JSON data to import as an Object Data Type?
> >
> > Databricks requires the column type to be `VARIANT` at table creation.
>
> > [accordion] How does MoEngage handle Databricks TIMESTAMP columns with local time zones instead of UTC?
> >
> > MoEngage applies no timezone conversion and reads only `TIMESTAMP`-typed columns over its JDBC/ODBC connector. `TIMESTAMP` is UTC-normalized, so the only realistic issue is your own pipeline writing local-time values into a UTC-typed column, a data-hygiene problem, not a type choice. (Databricks' naive `TIMESTAMP_NTZ` type isn't supported over the driver, so it isn't a path here.)
# Set Up a File Import
Source: https://moengage.com/docs/user-guide/data/imports/setting-up-a-file-import
Automate imports of users, events, and auxiliary data from files in Amazon S3 or an SFTP server into MoEngage. Prepare files, map columns, and schedule syncs.
MoEngage automates imports of users, events, and auxiliary data from files you drop in an Amazon S3 bucket or an SFTP server. You prepare your files, configure the connection and column mapping once, and MoEngage picks up new files on a one-time or periodic schedule.
Select your source in any tabbed section below and the page stays on that source throughout.
# Types of Imports
MoEngage can import the following from your files:
* **Registered Users**: Users who are already registered on MoEngage.
* **Anonymous Users**: Users who are not yet registered on MoEngage.
* **Events** (Standard and User-Defined): Standard events such as Campaign Interaction Events, as well as your own user-defined events.
* **Auxiliary Data**: Supplementary user data ingested temporarily. Auxiliary Data has its own setup. See [Auxiliary Data](/docs/user-guide/data/imports/auxiliary-data).
# Prepare Your Files
> [!NOTE]
>
> Keep your own copy of the files you import. Re-downloading a file from MoEngage is time-limited and not guaranteed.
## Supported File Types
MoEngage supports **CSV** and **NDJSON** files, in UTF-8 encoding.
| File Type | Users | Events | Auxiliary Data |
| - | :-: | :-: | :-: |
| CSV | ✅ | ✅ | ✅ |
| JSON (NDJSON) | ✅ | ✅ | ❌ |
## Naming Conventions
Name your files so that MoEngage can identify the import type and the run date:
> [!NOTE]
>
> Give every file a unique name. MoEngage skips any file name it has already processed, whether the previous import succeeded, partially succeeded, or failed.
A file name has two parts: `_.`.
* **Registered users**: prefix `registered_user_data_`, for example, `registered_user_data_01311997.csv`.
* **Anonymous users**: prefix `anonymous_user_data_`, for example, `anonymous_user_data_jan_2022.csv`.
* **Events**: prefix `_`, for example, for the event "Purchase Summary", `Purchase_Summary_31011997.csv`.
MoEngage also supports custom file names following `_.`, where the custom name uses letters, numbers, spaces, and underscores.
The `` suffix represents the day the import runs. For example, if an import runs on 7 January 2022 and the selected format is `ddmmyyyy`, MoEngage looks for files ending in `07012022.csv` or `07012022.json`. Configure the format on the dashboard during setup. Supported formats:
| Format | Description | Example |
| - | - | - |
| `{mm}_{yyyy}` | `mm`: month 01–12; `yyyy`: 4-digit year | `01_2022` |
| `{ddmmyyyy}` | `dd`: day 01–31; `mm`: month 01–12; `yyyy`: 4-digit year | `31012022` |
| `{yyyymmdd}` | `yyyy`: 4-digit year; `mm`: month 01–12; `dd`: day 01–31 | `20220112` |
| `{mon_yyyy}` | `mon`: lowercase 3-letter month (`jan`–`dec`); `yyyy`: 4-digit year | `jan_2022` |
| `{yyyymmdd}_{hhmm}` | date as above; `hh`: hours 00–23; `mm`: minutes 00–59 | `20220131_1259` |
> [!NOTE]
>
> Do not use `moe_` as a prefix for events, event properties, or user properties. It is a reserved system prefix.
**File extensions:**
* Without encryption: `.csv`, `.json`
* With PGP encryption: `.csv.asc`, `.json.asc`, `.csv.pgp`, `.json.pgp`
## File Structure
Structure your files according to the file type you import:
> [tab] CSV Files
>
> * The first row must be the column names (treated as the header row).
> * No duplicate column names (names are case-sensitive) and no missing column names.
> * Only the comma (`,`) is supported as a delimiter.
> * Avoid empty rows.
> * Attribute type *list* and other complex types (JSON, dictionaries, and so on).
> * Multi-line support in CSV files is disabled by default. Please get in touch with support if you need this feature. Newline formats other than `\n`, such as `Ctrl+M` and `\r`, are not supported. Enabling multi-line support can negatively impact the processing speed of your import.
>
> Sample files: [Registered Users](https://uploads-samples-cdn.moengage.com/registered_user_data.csv), [Anonymous Users](https://uploads-samples-cdn.moengage.com/anonymous_user_data.csv), [Events](https://uploads-samples-cdn.moengage.com/sample_event.csv), [Mapping File](https://uploads-samples-cdn.moengage.com/upload_mapping.json).
> [tab] JSON Files
>
> JSON files must be Newline-Delimited JSON (NDJSON) with a `.json` extension. Each line is a complete, self-contained JSON object separated by a newline:
>
> ```json wrap theme={null}
> {"user_id": "user123", "name": "John Doe", "email": "john.doe@example.com", "address": {"city": "New York", "zip": "10001"}}
> {"user_id": "user124", "name": "Jane Smith", "email": "jane.smith@example.com", "preferences": ["email_updates", "sms_alerts"]}
> ```
>
> Sample files: [Registered Users](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/registered_user_data.json), [Anonymous Users](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/anonymous_user_data.json), [Events](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/sample_event.json), [Mapping File](https://app-cdn.moengage.com/partners-integration-ui/app-marketplace-public/helpdoc/upload_mapping.json).
>
> #### File Structure and Mapping JSON Levels
>
> When you upload or select a JSON file, MoEngage generates a flattened, tabular preview of the data. This preview represents keys up to two levels deep (root level + one nested level) as distinct columns:
>
> ```json theme={null}
> {
> "item-id": 123,
> "item-type": "books",
> "item-cost": {
> "amount": {
> "cost-price": 100,
> "discount": 0
> },
> "currency": "USD"
> }
> }
> ```
>
> | Key | Level | Mappable? |
> | - | - | - |
> | `item-id`, `item-type` | 1 | Directly to an attribute. |
> | `item-cost` | 1 (object) | As a whole Object. |
> | `item-cost.amount` | 2 (object) | As a whole Object. |
> | `item-cost.currency` | 2 | Directly to an attribute. |
> | `cost-price`, `discount` | 3 | No, deeper than two levels. |
>
> #### Mapping Capabilities
>
> * **Mapping Primitive Keys**: Map any primitive key from Level 1 or Level 2 directly to a standard MoEngage attribute.
> * **Mapping Entire Objects or Arrays of Objects**: Map a complete JSON object or an array of objects to a single MoEngage attribute of type "Object" or "Array of Objects" respectively. When an entire object is mapped, its internal structure and all nested keys are preserved and imported. You cannot rename these keys within MoEngage.
> * **Cherry-Picking Fields**: To map only specific primitive fields from an object (up to Level 2) and not the entire parent object, skip the parent object attribute in the mapping table, then map its individual nested primitive keys.
> * **Mapping Files**: Use mapping files to automate your JSON key mappings. The mapping file references the flattened JSON paths (for example, `"column": "user_profile.id"`).
>
> #### Map Limitations
>
> **Level-2 Keys within an Array of Objects**: You cannot directly map individual Level 2 keys nested within an array of objects. You can map the entire array of objects to an "Array of Objects" attribute, which imports its full nested structure.
>
> #### Behavior During Data Ingestion
>
> * **Null or Blank Strings**: If a mapped key's value is null or an empty string, MoEngage skips it and does not update the corresponding data.
> * **Unmapped/Skipped Keys**: Any additional keys in your JSON file that are neither mapped nor marked as skipped are ignored and not ingested.
> [!NOTE]
>
> MoEngage does not support the `|` (pipe) character in non-array columns. Ensure String, Numeric, and Boolean columns do not contain this character.
## Folder Structure
Place all files into a single folder and configure the folder path during setup. MoEngage does not look inside subfolders or the root folder.
> [!NOTE]
>
> **File and row order is not guaranteed.**
>
> MoEngage processes files in parallel and does not preserve the order in which files were placed in the folder or uploaded. It also does not preserve row order within a file. If the final state of an attribute depends on sequence (for example, multiple updates to the same user), send one consolidated row per user.
## Array Support
> [tab] CSV Files
>
> * Simple arrays are supported. Nested and associated arrays are not supported.
> * The supported delimiter in the CSV is the pipe (`|`). For example: `[1|2|3]`.
> * The supported data types are Array String and Array Double (numeric). Select the type in the **Map column to attribute** list during column mapping.
> * All elements in an array must be homogeneous, either all integer/double or all string. If they are not, MoEngage attempts to typecast each element to the declared type and stores the result.
> * **Array typecasting**: If an array `["1" | 2 | "abc"]` is mapped as Array Double, MoEngage ingests `[1, 2]`, because `"abc"` cannot be cast to a number and is dropped.
>
> **Example**
>
> A CSV row with a String column, an Array String column, and an Array Double column:
>
> ```csv theme={null}
> user_id,tags,scores
> u123,["premium"|"beta_user"|"newsletter"],[4.5|3.8|5.0]
> ```
>
> * `tags` is mapped as **Array String**, MoEngage ingests `["premium", "beta_user", "newsletter"]`.
> * `scores` is mapped as **Array Double**, MoEngage ingests `[4.5, 3.8, 5.0]`.
>
> Each element sits between the pipe delimiters and the whole value is wrapped in square brackets, `[element1|element2|element3]`, with no spaces around the pipes.
> [tab] JSON Files
>
> * Simple arrays and array of objects are supported.
> * Pass a valid JSON array. For example: `[1, 2, 3]`.
> * The supported data types are Array String, Array Double (numeric), and Array Object. Select the type in the **Map column to attribute** list during column mapping.
> * All elements in an array must be homogeneous, either all integer/double or all string. If they are not, MoEngage attempts to typecast each element to the declared type and stores the result.
> * **Array typecasting**: If an array `["1", 2, "abc"]` is mapped as Array Double, MoEngage ingests `[1, 2]`, because `"abc"` cannot be cast to a number and is dropped.
>
> **Example**
>
> A JSON row with a String column, an Array String column, and an Array Double column:
>
> ```json theme={null}
> {"user_id": "u123","tags": ["premium", "beta_user", "newsletter"],"scores": [4.5, 3.8, 5.0],"subscriptions":[{"type":"email","status":"active"},{"type":"sms","status":"inactive"}]}
> ```
>
> * `tags` is mapped as **Array String**, MoEngage ingests `["premium", "beta_user", "newsletter"]`.
> * `scores` is mapped as **Array Double**, MoEngage ingests `[4.5, 3.8, 5.0]`.
> * `subscriptions` is mapped as **Array Object**, MoEngage ingests `[{"type":"email","status":"active"},{"type":"sms","status":"inactive"}]`.
# Limits
File imports have the following limits:
> [!WARNING]
>
> **Imported data is subject to archival**
>
> MoEngage archives inactive users, events, and devices every 14 days and deletes the archived data permanently. Registered users are archived after 365 days without activity or campaign engagement, and anonymous users after 60 days.
>
> Importing or updating user properties does not count as activity, so it does not postpone archival. Only events and campaign engagement do.
>
> Before you import, check the criteria in [Data Archival (Retention) Policy](/docs/user-guide/data/key-concepts/data-archival-retention-policy) to confirm which of your records qualify.
| Limit | Value |
| - | - |
| File size |
User imports: Less than 1 GB
Event imports: Less than 500 MB
Auxiliary data imports: Refer to [Auxiliary Data](/docs/user-guide/data/imports/auxiliary-data#limits)
|
| Rows | A single CSV or JSON file supports up to your hourly row limit. Files exceeding your hourly row limit are rejected. |
| Columns/Attributes | 100 columns for users; 100 columns per event. |
| File name prefix | Maximum 100 characters. |
| Number of files | Up to 250 files per import run. |
> [!NOTE]
>
> For a PGP-encrypted file, MoEngage decrypts the file first and then checks its size. The decrypted file must be less than 1 GB for user imports and less than 500 MB for event imports.
**Rate limits** (defaults, contact MoEngage to increase):
| Import Type | Hourly | Daily |
| - | - | - |
| Users |
Growth: 1.5M/hr
Enterprise: 2.5M/hr
|
Growth: 15M/day
Enterprise: 25M/day
|
| Events | 5M/hr | 40M/day |
The hourly rate is the maximum ingested per hour; the daily rate is the total cap per day. When a rate limit is breached, you receive a *Rate limit breached* alert on the Data Imports dashboard.
To see how much of your hourly and daily import limit you have used, which imports are held back when a limit is reached, and which imports are consuming the most, refer to [Check Import Limits](/docs/user-guide/data/imports/overview-imports#check-import-limits).
> [!TIP]
>
> Avoid scheduling a very large number of files at the same time. Doing so can create a processing backlog and delay ingestion, even when each file is small. Stagger or batch your scheduled imports over time instead of queuing a large number of files together.
# Required Access and Connection
Grant MoEngage access to your source before you create the import:
> [tab] Amazon S3
>
> Grant MoEngage read access to your S3 bucket and set up a connection in the App Marketplace. For the IAM permissions and connection setup, see [Set Up Authentication](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-1-set-up-authentication), [Grant Permissions](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-2-grant-permissions), and [Connect Amazon S3 in the App Marketplace](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-4-connect-amazon-s3-on-the-app-marketplace).
> [tab] SFTP
>
> Set up an [SFTP connection](/docs/partner-guide/data-and-analytics/cloud-storage/sftp) in the App Marketplace with the relevant permissions. For details, see [Configure a New SFTP Connection](/docs/partner-guide/data-and-analytics/cloud-storage/sftp).
## IP Whitelisting
MoEngage recommends that you whitelist all the MoEngage IPs listed for your data center under [Data Transfer](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage#data-transfer). MoEngage connects to your system from these IPs for data imports, data warehouse exports, streams, and connection tests on the App Marketplace. To find your data center, see [Data Centers in MoEngage](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
> [tab] Amazon S3
>
> If your bucket is in a different AWS region from your MoEngage data center, you can enable IP whitelisting for the MoEngage IPs. IP whitelisting isn't required if your bucket is in the same AWS region. For the steps, see [Enable IP Whitelisting for Imports](/docs/partner-guide/data-and-analytics/cloud-storage/amazon-s3#step-3-enable-ip-whitelisting-for-imports).
> [tab] SFTP
>
> Add the MoEngage IPs to the inbound allow rules of the firewall in front of your SFTP server. For the steps, see [Enable IP Whitelisting](/docs/partner-guide/data-and-analytics/cloud-storage/sftp#enable-ip-whitelisting).
# Set Up the Import
Set up your import in three steps: configure the connection and file format, map your columns to MoEngage attributes, and select the import frequency.
> [!NOTE]
>
> Contact your MoEngage Customer Success team to enable the **Data** menu on the left navigation if it is not visible.
On the MoEngage sidebar, go to **Data** > **Data imports**, click **+ Import**, and select **Users** or **Events**. Then select your source tile and click **Continue**.
## Step 1: Configure the Connection and File Format
Select whether to import **Registered users** or **Anonymous users** (for User imports), or select the event to import (for Event imports). Registered and anonymous imports expect different file names; see [Naming Conventions](#naming-conventions).
For events, your file names must begin with the event name of the chosen event. For example, the event "App/Site Opened" has the event name `MOE_APP_OPENED`, so file names begin with `MOE_APP_OPENED_`. To create a new event, click **+ Create event** and enter a unique name; new events appear in your app only after the first successful import.
Next, configure the connection and folder:
> [tab] Amazon S3
>
> 1. In the **S3 connection** list, select your connection (or click **+ Add connection**).
> 2. In the **File type** list, select **CSV** or **JSON**.
> 3. In the **Folder path** box, enter your directory path. Do not include the bucket name or trailing slashes, because MoEngage resolves the bucket name from your marketplace connection.
> 4. To import PGP-encrypted files, select **Is your file encrypted?** and provide your private **Decryption Key**, optional public **Signing Key**, and **Key passphrase**.
>
> 
> [tab] SFTP
>
> 1. In the **SFTP connection** list, select your connection (or click **+ Add connection**).
> 2. In the **Folder URL** box, enter the full path beginning with `sftp://[host-name]/`, without a trailing slash (for example, `sftp://files.hostname.com/my_folder`). MoEngage does not support root folders or subfolders, so keep all files in a single folder.
> 3. To import PGP-encrypted files, select **Is your file encrypted?** and provide your private **Decryption Key**, optional public **Signing Key**, and **Key passphrase**.
>
> 
Enter a unique **Import name** to identify this import on the dashboard.
> [accordion] Set up PGP encryption
>
> PGP (Pretty Good Privacy) lets you encrypt sensitive files before importing them. MoEngage supports PGP encryption for S3 and SFTP file imports.
>
> **Prerequisites:**
>
> * **PGP key pair**: A public key (to encrypt the file) and a private key (to decrypt it). Never share the private key.
> * **Signing key pair**: A public key (to sign the file, required for MoEngage SFTP integration) and a private key (used internally to verify the signature).
>
> The following steps use [GnuPG](https://www.gnupg.org/index.html), a free implementation of the PGP standard.
>
> **Step 1. Generate a key pair.** Generate a PGP key pair using a tool such as GnuPG (`gpg --full-generate-key`), selecting RSA and a 1024-bit key size.
>
> > [!NOTE]
> >
> > * MoEngage supports file encryption using RSA keys of up to 1024 bits in length. Larger RSA keys, such as 4096-bit, are not supported and fail during decryption. Generate your key pair with a smaller RSA key size.
> > * Turn off compression during encryption.
>
> **Step 2. Encrypt the file.** Encrypt the file with your public key, then upload it to your S3 or SFTP folder. The `--sign` option signs the file while encrypting it.
>
> ```bash theme={null}
> gpg --encrypt --sign --armor --compress-algo none -r demo@example.com
> ```
>
> **Step 3. Add the keys in the MoEngage UI.** Enter your private key in the **Decryption Key** field and your passphrase in the **Key Passphrase** field during import setup.
>
> **Step 4. Decrypt a file.** Decryption requires your private key and its passphrase. In your PGP software, select the encrypted file and enter your passphrase to produce the unencrypted file. Python users can use the [python-gnupg](https://pypi.org/project/python-gnupg/) package:
>
> ```python theme={null}
> import gnupg, os
> gpg = gnupg.GPG(gnupghome=os.path.expanduser('~'))
> gpg.encoding = 'utf-8'
> import_result = gpg.import_keys(key_data)
> gpg.trust_keys(import_result.fingerprints, "TRUST_ULTIMATE")
> with open(encrypted_file_path, 'rb') as file:
> status = gpg.decrypt_file(file, passphrase="", output="/path/to/decrypted/file")
> print(status.ok)
> ```
>
> **Step 5. Verify the file's signature (optional).** If you signed the file, add the public signing key on the MoEngage dashboard. MoEngage verifies the signature on the file in your S3 or SFTP folder. When verifying programmatically, a matched signature populates `status.signature_id`:
>
> ```python theme={null}
> if status.signature_id: # populated when the signature is verified, otherwise None
> print("signature verified")
> else:
> print("not verified")
> ```
### File Configurations
Select the DateTime format present in your file name (your file name must end with `_.csv`). Ensure at least one matching file exists in the folder, then click **Fetch file(s)**. If the connection and format are correct, MoEngage shows a preview of the top 5 rows.
If MoEngage cannot fetch the file, you may see:
> [tab] Amazon S3
>
> * **Given S3 Access Key is not valid**: Verify your S3 marketplace connection details.
> * **Please check the folder path and try again**: Verify the folder path and that compatible files exist in it.
> * **Found zero data rows in the file**: The file has no rows after the header. MoEngage expects at least 2 rows (1 header + 1 data row).
> [tab] SFTP
>
> * **Given credentials are not correct**: Enter the correct SFTP credentials and fetch again.
> * **Please check the folder path and try again**: Verify the folder path and that compatible files exist in it.
> * **Found zero data rows in the file**: The file has no rows after the header. MoEngage expects at least 2 rows (1 header + 1 data row).
Click **Next** to continue to mapping.
## Step 2: Map Your Columns to MoEngage Attributes
Map each file column to a MoEngage attribute. For every column you see the column name with a sample value, the **Map attribute** selector (pick the data type, and for DateTime columns the format), and a **Skip** action. To create a new attribute, click **+ Create attribute**. You can also click **+ Add Field** to enter a mapping manually.
Mandatory mappings depend on the import type:
* **User imports (Registered)**: map your identifier column to **User ID**. If you have [Unified Identity](/docs/user-guide/data/user-data/unified-identity-identity-resolution) enabled, you will have an option to map the additional identifiers as well.
* **User imports (Anonymous)**: map your identifier column to **Anonymous ID**.
* **Event imports**: map your identifier column to **User ID**, and map your timestamp column to **Event Time**.
> [tab] Amazon S3
>
> For events, map either **Event Time (UTC)** or **Event Time (App Timezone)**. If you choose Event Time (UTC), the event time is converted to the timezone configured in your MoEngage dashboard settings.
> [tab] SFTP
>
> For events, map either **Event Time (UTC)** or **Event Time (App Timezone)**. If you choose Event Time (UTC), the event time is converted to the timezone configured in your MoEngage dashboard settings.
Once a mandatory mapping is marked, you can no longer skip that column.
### Mapping Files
Optionally, auto-map your columns by uploading a mapping file. Click **Upload mapping file** at the top-right of the mapping table and select your file. Mappings are auto-configured; a modal lets you create any attributes referenced in the mapping file that don't yet exist. Columns in the mapping file but not in your file are ignored; columns in your file but missing from the mapping file are left blank for manual mapping.
For a fresh import, MoEngage provides a sample mapping file you can use as a reference. If you duplicate an existing import, its mapping file is pre-attached and available to download. If a mapping file maps a column to an attribute that doesn't exist in MoEngage, the mapping is left blank, create the attribute from the UI first, then map the column to it.
A mapping file contains the mappings between each source column and a MoEngage attribute, along with the data type of the column. The file must be in JSON format. Instead of mapping columns one by one on the dashboard, you can upload a mapping file to automate the mapping.
> [tab] CSV Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "ID", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "First Name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "First Seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "LTV", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "Install Status", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
> [tab] JSON Files
>
> ```json theme={null}
> {
> "mapping": [
> { "column": "customer_id", "moe_attr": "uid", "type": "string", "is_skipped": false },
> { "column": "user.first_name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
> { "column": "user.first_seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
> { "column": "attribution.lifetime_value", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
> { "column": "attribution.device_installed", "moe_attr": "installed", "type": "bool", "is_skipped": false }
> ]
> }
> ```
For each column, provide the following fields:
1. **`column`** *(required)*: The column name from the source file. For Level 2 keys in a JSON file, use dot notation (`key1.key2`).
2. **`moe_attr`** *(required)*: The MoEngage attribute to map the column to. Ensure each column maps to a unique `moe_attr`.
3. **`type`** *(optional)*: The data type of the column. See the supported types below.
4. **`datetime_format`** *(optional)*: The date-time format. Mandatory for DateTime fields only.
5. **`is_skipped`** *(optional)*: A boolean field. Any column marked `true` is skipped during import.
### Standard User Properties for Reference
Map your source columns to MoEngage standard user properties using the keys below. For the exhaustive list, refer to your [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard.
| Key | Attribute Name on Dashboard | Datatype | Description |
| :- | :- | :- | :- |
| `uid` | ID | String | Unique ID that the app has set for a user. |
| `u_n` | Name | String | Full name of the user. |
| `u_fn` | First Name | String | First name of the user. |
| `u_ln` | Last Name | String | Last name of the user. |
| `u_em` | Email (Standard) | String | The email address of the user. For example, `john@example.com`. |
| `u_gd` | Gender | String | Gender of the user. |
| `u_bd` | Birthday | DateTime | Birth date of the user. Use this standard attribute instead of age; data sent as age is tracked as a custom attribute. |
| `u_mb` | Mobile Number (Standard) | String | Mobile number of the user. For example, `918888444411`. |
| `moe_geo_location` | Location | Array of `[lat,lng]` | The location of the user, in the format `{"lat": 12.11, "lon": 123.122}`. |
| `source` | Publisher Name | String | The publisher name of the install. For example, `Google Ads`. |
| `revenue` | LTV | Numeric | Lifetime value of the user. |
| `moe_unsubscribe` | Unsubscribe | Boolean | Email unsubscribe attribute. Emails are not sent to the user when set to `true`. |
| `moe_hard_bounce` | Hard Bounce | Boolean | Email hard bounce attribute. Emails are not sent to the user when set to `true`. |
| `moe_spam` | Spam | Boolean | Email spam attribute. Emails are not sent to the user when set to `true`. |
> [!WARNING]
>
> Track standard string attributes with the correct data type. For example, if **First Name** (`u_fn`) is ingested as a number or an array instead of a string, the sample users on the [Create segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments) page fail to load with a 500 error ("There seems to be an error"). To fix this, pin the attribute's data type to String on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard and re-send the corrected data for the affected users.
### Supported Attribute Types
| **Type** | **Description** | **Value in Mapping File** |
| - | - | - |
| String | Any string value. For example, `ABC`, `ABC XYZ`, `ABC123`. | `"type": "string"` |
| Double | Any decimal value. For example, `3.14159`, `241.23`, `-123.1`. | `"type": "double"` |
| Boolean | For example, `true`, `false`. | `"type": "bool"` |
| Date Time | Any date-time value. For example, `2019/02/22 17:54:14.933`. | `"type": "datetime"` |
> [!NOTE]
>
> MoEngage does not support the `|` (pipe) character in non-array type columns. Ensure your String, Numeric, and Boolean columns do not contain this character.
### Reserved Keywords for User Properties
MoEngage reserves the following keys. Do not use them when you map or track user properties.
* `USER_ATTRIBUTE_UNIQUE_ID`
* `USER_ATTRIBUTE_USER_EMAIL`
* `USER_ATTRIBUTE_USER_MOBILE`
* `USER_ATTRIBUTE_USER_NAME`
* `USER_ATTRIBUTE_USER_GENDER`
* `USER_ATTRIBUTE_USER_FIRST_NAME`
* `USER_ATTRIBUTE_USER_LAST_NAME`
* `USER_ATTRIBUTE_USER_BDAY`
* `USER_ATTRIBUTE_NOTIFICATION_PREF`
* `USER_ATTRIBUTE_OLD_ID`
* `MOE_TIME_FORMAT`
* `MOE_TIME_TIMEZONE`
* `USER_ATTRIBUTE_DND_START_TIME`
* `USER_ATTRIBUTE_DND_END_TIME`
* `MOE_GAID`
* `INSTALL`
* `UPDATE`
* `MOE_ISLAT`
* `status`
* `user_id`
* `source`
### Portfolio Support (Project-Level Routing)
You can route imported events to specific projects in your MoEngage portfolio workspace using column mapping. Map your project identifier column (such as `brand_name` or `app_id`) to the MoEngage attribute `moe_project_name`. Values must match your MoEngage project names exactly (matching is case-sensitive).
* **Successful routing**: If the value matches a project in your portfolio, MoEngage ingests the user or event at that project level.
* **Fallback**: If the mapping is missing, blank, or does not match a project name, MoEngage ingests the data at your global portfolio level.
### Save as a File Segment
Turn on **Save as File Segment** and enter a name to create a segment from the imported users, usable in campaigns.
* **Existing segment**: Users are added in append mode, new users are added, none are removed.
* **New segment**: Choose the update mode: **Replace** (each import fully replaces the segment's users) or **Append** (each import adds users, none removed).
> [!WARNING]
>
> Do not use `/` or Unicode characters in the file segment name, or the import will fail.
### Import Behaviour
For user imports, select **Skip new users during this import** under **Import Behaviour** to bulk-update attributes on users MoEngage already has. MoEngage creates no new users from this import, and a row whose identifier is not already in MoEngage is ignored.
For event imports, select **Skip duplicate rows** to perform de-duplication on the selected column. MoEngage will skip any row with a duplicate value in that column, and only the first occurrence is ingested. If you do not select this option, MoEngage ingests all rows, including duplicates.
### Send Import Notifications
Turn on notifications and select up to **10 email recipients** to be alerted when an import is created, succeeds, or fails. When your mappings are complete, click **Next**.
## Step 3: Select the Import Frequency
Define when MoEngage retrieves your files:
* **One-Time Imports**: Run immediately or schedule for a future date and time.
* **Periodic Imports**: Run hourly, daily, weekly, or monthly, with intervals and advanced configurations.
For each run, MoEngage fetches files matching the configured DateTime format, so ensure your file names are correct. Optionally, set the import to end after a number of occurrences or on a specific date. Click **Done**.
> [!NOTE]
>
> Channel reachability and custom segments for imported users are available within 2 hours of import completion. Plan your campaigns accordingly.
# Duplicate Imports
You can configure only one unique import at a time. An import is a duplicate when **all** of these match an existing active import:
> [tab] Amazon S3
>
> 1. **Import type**: Users or Events.
> 2. **Import sub-type**: Event name, or Registered / Anonymous.
> 3. **S3 folder path**.
> 4. **Bucket name**.
> [tab] SFTP
>
> 1. **Import type**: Users or Events.
> 2. **Import sub-type**: Event name, or Registered / Anonymous.
> 3. **SFTP folder path**, the complete folder path, including hostname.
If any one parameter differs, the import is unique.
# Import Failure Policy
MoEngage retries a failed file automatically, up to 30 attempts, before marking it permanently FAILED. You can configure an email alert on failure during setup. A file-level failure does not stop the schedule, future scheduled runs continue independently.
# Supported Datetime Formats
Use these in the `datetime_format` field of your mapping file, or when configuring DateTime columns during mapping.
| **Datetime Format** | **Examples** |
| - | - |
| `"datetime_format": "YYYY-MM-DD"` | 2022-01-22 |
| `"datetime_format": "YYYY/MM/DD"` | 2022/01/22 |
| `"datetime_format": "DD/MM/YYYY"` | 22/01/2022 |
| `"datetime_format": "DD-MM-YYYY"` | 22-01-2022 |
| `"datetime_format": "DD-MM-YYYY hh:mm:ss"` | 31-12-2022 12:10:33 |
| `"datetime_format": "DD/MM/YYYY hh:mm:ss"` | 31/12/2022 12:10:33 |
| `"datetime_format": "YYYY-MM-DD hh:mm:ss"` | 2019-02-22 17:54:14 |
| `"datetime_format": "YYYY/MM/DD hh:mm:ss"` | 2019/02/22 17:54:14 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ss.s"` | 31-12-2022T12:10:33.882 |
| `"datetime_format": "DD/MM/YYYYThh:mm:ss.s"` | 31/12/2022T12:10:33.882 |
| `"datetime_format": "DD-MM-YYYYThh:mm:ssTZD"` |
|
# Run History
**Run history** on the import details page lists every run of an import, so you can see when each run was scheduled, when it finished, how long it took, and how each file inside it performed. A one-time import has a single row. A periodic import has one row for each scheduled execution. **Run history** shows the last two months of runs.
To open **Run history**, perform the following steps:
1. On the Data imports page, click the kebab menu under **Actions** for the import.
2. Click **View**.


MoEngage sorts **Run history** by scheduled time, with the most recent run first. Each row is one run and shows the following columns:
| Column | Description |
| - | - |
| Scheduled at | When the run was scheduled to execute. |
| Completed at | When the run finished. Shows `--` until the run finishes. Hover over the value to see the start time, the completion time, and the total time the run took. |
| Status | The status of the run. For how MoEngage derives it, refer to [Import Statuses](/docs/user-guide/data/imports/overview-imports#import-statuses). |
| Files processed | The number of files processed in that run, against the number of files in it. |
| Total rows | The number of rows found across the files in the run. |
| Rows processed | The number of rows MoEngage processed across the run. User imports only. |
| Rows failed | The number of rows that failed. User imports only. |
| Events added | The number of events MoEngage added. Event imports only. |
| Events failed | The number of events that failed. Event imports only. |
| Auxiliary data added | The number of auxiliary data records MoEngage added. Auxiliary data imports only. |
| Auxiliary data failed | The number of auxiliary data records that failed. Auxiliary data imports only. |
| Rows skipped | The number of rows MoEngage skipped. Event and auxiliary data imports. |
| Actions | Opens the file breakdown for that run. |
MoEngage populates these statistics only after a run finishes, so a run that is still processing shows no counts. To narrow the list, select a value from **Select status**, or select a range from **Select scheduled date**.
## View the Files in a Run
The file breakdown shows each file in a run separately, so you can find the file that failed or the one that slowed the run down.
To open the breakdown, perform the following steps:
1. On the import details page, find the run you want to inspect.
2. Click **View files**.

The summary at the top of the slideout shows the run's scheduled time, start time, completion time, file count, and status. MoEngage sorts the files below it by completion time, with the most recent first, and shows files still processing above them, sorted by start time. The table lists the following for each file:
| Column | Description |
| - | - |
| File name | The name of the file. |
| Completed at | When the file finished. Hover over the value to see the start time and the total time the file took. |
| Status | Pending, Processing, Successful, Partial Success, or Failed. |
| Rows in file | The number of rows in the file. |
| Rows processed | The number of rows MoEngage processed from the file. User imports only. |
| Rows failed | The number of rows that failed. User imports only. |
| Events added | The number of events MoEngage added from the file. Event imports only. |
| Events failed | The number of events that failed. Event imports only. |
| Auxiliary data added | The number of auxiliary data records MoEngage added from the file. Auxiliary data imports only. |
| Auxiliary data failed | The number of auxiliary data records that failed. Auxiliary data imports only. |
| Rows skipped | The number of rows MoEngage skipped. Event and auxiliary data imports. |
| Actions | Downloads the file. For a failed or partially successful file, you can also download the error report. Downloading the file is unavailable while the PII flag is on for your workspace, but the error report stays available. |
# Manage Your Imports
To monitor your imports, understand import statuses, or trigger a run manually or via API, see [How Imports Work](/docs/user-guide/data/imports/overview-imports#how-imports-work) on the Imports Overview.
# Frequently Asked Questions
> [accordion] My imports have failed. How do I check what went wrong?
>
> Click the ellipsis on the right and click **View** to look up the Import details. Hover over the **Failed** Status to learn the reason.
> [accordion] What if a scheduled import adds the data into a recently archived segment?
>
> In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.
> [accordion] Can an import be stopped while it's running?
>
> Once an import process starts, it can't be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It's best to let the current import finish.
> [accordion] How can I stop future runs of a scheduled import?
>
> Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the **Archive** option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.
> [accordion] What should I do if an import seems stuck or is taking a long time?
>
> If an import appears to be stuck or is taking longer than usual, it's best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it's still processing can cause conflicts and may prevent the original import from completing successfully.
> [accordion] What happens when there is an error in fetching the files from the folder?
>
> MoEngage retries a failed file automatically, up to 30 attempts, before marking it permanently FAILED. You can also configure an email alert on failure by selecting the notification checkbox during setup.
> [accordion] A file failed with 'Applicable rate limit breached'. Will the periodic import reprocess it automatically?
>
> No. When a file exhausts its processing retries and fails with the *Applicable rate limit breached* status, MoEngage cannot replay that file on its own, so the periodic schedule does not reprocess it automatically. This retry limit protects the ingestion pipeline from being overloaded. To reprocess the affected files, rename them and re-upload them to your source folder so that MoEngage treats them as new files. To reduce the chance of hitting rate limits, stagger large batches instead of scheduling many files at once (see [Limits](/docs/user-guide/data/imports/setting-up-a-file-import#limits)).
> [accordion] How does MoEngage pick up new files in a periodic run?
>
> During each scheduled run, MoEngage searches your configured folder path and selects new files based on your file-name prefix and datetime-format configuration. It uniquely identifies files by the combination of folder location and file name, so it processes each file only once.
> [accordion] Will a periodic import pick up an earlier processed file?
>
> No. A file that has already been processed is not processed again while its file name and folder location stay the same. If you place the same file in a different folder, an import configured for that new folder will process it again.
> [accordion] Can a CSV file contain both User and Event data?
>
> No. Set up user imports and event imports as separate tasks. Each source file must contain only user properties or only event records.
> [accordion] What is NDJSON, and why is it required?
>
> NDJSON (Newline-Delimited JSON) means each line in your `.json` file is a complete JSON object separated by a newline. This format lets MoEngage process large JSON datasets line by line for scalable, robust imports.
> [accordion] Are compressed files (for example, .gz, .zip) supported?
>
> No. MoEngage does not support importing compressed files.
> [accordion] If I change the file type of an existing import, what happens to my mappings?
>
> Changing the file type removes the existing preview and re-fetches the available files for the new file type. You must select the file to preview again and reconfigure your mappings based on the new file's structure.
# Data Archival (Retention) Policy
Source: https://moengage.com/docs/user-guide/data/key-concepts/data-archival-retention-policy
Understand MoEngage's data archival policy for removing inactive user profiles, events, and devices to optimize performance, maintain data hygiene, and ensure regulatory compliance.
## Overview
Data archival is the systematic process of removing inactive or dormant user data to ensure that your marketing workspace remains lean, focusing exclusively on users who provide genuine engagement opportunities and business value.
MoEngage implements data archival to balance platform performance with global privacy standards:
* **Performance & Data hygiene:** MoEngage maintains a lean and high-performance environment populated exclusively by reachable and marketable users. This high-fidelity dataset ensures faster segmentation query and provides more accurate analytics, as your insights will reflect genuine user intent rather than being skewed by stagnant, non-functional records.
* **Regulatory Compliance (GDPR, CCPA, and India's DPDP Act):** The policy aligns with the GDPR principles of Storage Limitation and Data Minimization. User data should be kept only as long as there is a legitimate business purpose; once a user is no longer reachable or marketable, archiving their data reduces legal liability and protects user privacy. For how this supports India's Digital Personal Data Protection (DPDP) Act, 2023, see [Data Retention and India's DPDP Act, 2023](#data-retention-and-indias-dpdp-act-2023).
> [!NOTE]
>
> **Archival Frequency**
>
> Every 14 days, MoEngage runs a process to remove inactive and unreachable users, events and devices from MoEngage services. Each entity has a separate archival policy, and upon archival, the data points are deleted permanently.
## Archival Criteria
### User Profiles
MoEngage classifies every user profile as **Registered** or **Anonymous** based on whether the profile has an active identifier. This is the same classification used for [Identity Resolution](/docs/user-guide/data/user-data/unified-identity-identity-resolution) and shown elsewhere on your dashboard — archival doesn't apply a separate rule.
1. **Registered Users:** A profile that has at least one active identifier present.
* In workspaces without Identity Resolution enabled, ID is the only active identifier — a user is Registered if ID is present.
* In workspaces with Identity Resolution enabled (up to five identifiers can be configured, for example ID, Email ID, Mobile Number), a user is Registered if any one of the active identifiers is present.
Because these represent known customers with a higher potential for long-term value, MoEngage archives Registered profiles after a [longer period of inactivity](/docs/user-guide/data/key-concepts/data-archival-retention-policy#archival-rules).
2. **Anonymous Users:** A profile with none of the active identifiers present. To keep your workspace lean and focused on high-intent audiences, MoEngage archives Anonymous profiles after a [shorter period of inactivity](/docs/user-guide/data/key-concepts/data-archival-retention-policy#archival-rules).
* **Activity:** Any interaction with your app or website (any standard or custom event) serves as a signal of intent. Any event or user update is considered as an activity.
* **Campaign Engagement:** The policy aims to retain users who actively interact with your communications. Interactions such as Opens or Clicks serve as engagement signals. MoEngage-generated and internal campaign-processing events (for example, delivery failures or control-group events) don't count as engagement — see the full list below.
The following internal and system-generated events never reset the archival clock, even though they're associated with a campaign:
| Event | Category |
| :- | :- |
| `MOE_NOTIFICATION_SEND_PUSH_FAILED` | Push |
| `MOE_NOTIFICATION_SEND_FAILED_IOS` | Push |
| `MOE_NOTIFICATION_SEND_FAILED_ANDROID` | Push |
| `MOE_NOTIFICATION_SEND_FAILED_WEB` | Push |
| `MOE_EMAIL_DEFERRED` | Email |
| `MOE_EMAIL_DROP` | Email |
| `MOE_EMAIL_SOFT_BOUNCE` | Email |
| `MOE_EMAIL_HARD_BOUNCE` | Email |
| `MOE_EMAIL_ESP_DROPPED` | Email |
| `MOE_EMAIL_SPAM` | Email |
| `MOE_SMS_DELIVERY_FAILED` | SMS |
| `MOE_SMS_SENT_FAILED` | SMS |
| `MOE_WHATSAPP_DELIVERY_FAILED` | WhatsApp |
| `MOE_WHATSAPP_SENDING_FAILED` | WhatsApp |
| `MOE_RCS_DELIVERY_FAILED` | RCS |
| `MOE_RCS_SENT_FAILED` | RCS |
| `MOE_MMS_DELIVERY_FAILED` | MMS |
| `TELEMARKETING_SENT` | Telemarketing |
| `TELEMARKETING_FAILED` | Telemarketing |
| `TELEMARKETING_SUPPRESSED` | Telemarketing |
| `USER_ENTERED_FLOW` | Flows |
| `USER_EXITED_FLOW` | Flows |
| `USER_FLOW_ADVANCEMENT` | Flows |
| `MOE_CAMPAIGN_CONTROL_GROUP` | Control group |
| `MOE_CAMPAIGN_USER_REMOVED_DUE_TO_CONTROL_GROUP` | Control group |
| `MOE_USER_REMOVED_FROM_CONTROL_GROUP` | Control group |
| `MOE_FB_AUDIENCE_SYNC` | Audience sync |
| `MOE_GOOGLE_ADS_AUDIENCE_SYNC` | Audience sync |
| `GAM_SEGMENT_SENT` | Audience sync |
| `WEBHOOK_SENT` | Connected apps and webhooks |
| `Connected App Campaign Sent` | Connected apps and webhooks |
| `Connected App Campaign Failed` | Connected apps and webhooks |
| `MOE_CAMPAIGN_EVENT_STATS` | Campaign stats and reporting |
| `MOE_CAMPAIGN_SEGMENT_STATS` | Campaign stats and reporting |
| `MOE_CAMPAIGN_FLOWS_STATS` | Campaign stats and reporting |
| `MOE_CAMPAIGN_FAILURE_STATS` | Campaign stats and reporting |
| `MOE_CAMPAIGN_CONVERSION_STATS` | Campaign stats and reporting |
| `MOE_CAMPAIGN_META_INFO` | Campaign stats and reporting |
| `MOE_COUPONS_REPORT` | Campaign stats and reporting |
| `n_c_s` | Internal |
### Archival Rules
Here is the summary of the rules that apply for archival:
| Type | User criteria | Archival criteria |
| :- | :- | :- |
| **Registered (Identified) users** | Users with at least one active identifier present (ID, or, in workspaces with Identity Resolution enabled, any configured identifier). | **Activity:**
No custom or standard event, and no user property update, in the last Data Retention Policy (DRP) window (default 365 days)
**Campaign engagement:**
User interacted with no campaigns for the last DRP window (default 365 days)
|
| **Anonymous (Guest) users** | Users with none of the active identifiers present. | **Activity:**
Last seen is > 60 days
MoEngage did not track any custom or standard event for the last 60 days
**Campaign engagement:**
User interacted with no campaigns for the last 60 days
|
> [!NOTE]
>
> **Data Retention Policy (DRP)**
>
> * Registered user profile retention is governed by your workspace's DRP. The default DRP is 365 days.
> * You can opt for a custom DRP value for Registered user profiles. Contact your MoEngage Customer Success Manager (CSM) or the Support team.
> * Anonymous user retention is fixed at 60 days and isn't covered by DRP.
> * If your workspace is on profile-based or hybrid pricing, MoEngage retains Registered user profiles for 10 years.
## Examples
The following examples show how the activity and campaign engagement criteria combine to decide whether a profile is archived:
| # | User type | Activity status | Campaign engagement | Archived? |
| :- | :- | :- | :- | :- |
| 1. | Registered | No events or attribute updates in last 365 days | No campaign interaction in last 365 days | Yes |
| 2. | Registered | No events in last 365 days, but an attribute was updated 10 days ago | No campaign interaction in last 365 days | No — the attribute update resets the clock |
| 3. | Anonymous | No events in last 60 days | No campaign interaction in last 60 days | Yes |
| 4. | Anonymous | Custom events in last 60 days | No campaign interaction in last 60 days | No |
### Events
By default, events remain available for 60 days. This determines how far back you can look to analyse user behaviour, for example, "Users who purchased in the last 2 months".
The event retention period (also referred to as Data Retention Policy (DRP)) is extendable on a request basis. Contact your dedicated MoEngage Customer Success Manager or the Support team. This DRP setting also governs Registered user profile retention (see [User Profiles](#user-profiles)). It has no impact on device retention or Anonymous user profile retention, which continue to follow their own fixed windows.
### Devices
MoEngage archives devices that have been inactive for 60 days. Removing the inactive and unreachable devices ensures that your Push campaigns are processed faster and directed only at active devices.
> [!NOTE]
>
> 1. The archival process runs periodically, so the actual archival period may be slightly higher (+14 days) than the mentioned number of days.
> 2. The archival policy can be customised. For further assistance, contact your MoEngage Customer Success Manager (CSM) or the Support team.
> 3. MoEngage allows ingestion of data beyond the Data Retention Policy (DRP), but the Segmentation service allows you to query the data only based on your DRP. The Data Storage services delete data beyond DRP periodically.
## Data Retention and India's DPDP Act, 2023
India's Digital Personal Data Protection (DPDP) Act, 2023, sets guidelines for how the personal data of individuals in India is collected, processed, and retained. MoEngage provides APIs and controls that help you respond when your end users in India exercise their rights under the Act.
* **Retention:** MoEngage retains personal data only for as long as necessary to fulfill the purpose it was collected for. The archival policy described on this page supports this by automatically removing inactive user profiles, events, and devices from the platform.
* **Erasure requests:** When an end user asks you to delete their data, use the [GDPR/CCPA data request API](/docs/api/gdpr/submit-a-gdpr-ccpa-data-request) to remove all personal data associated with that user from MoEngage.
For MoEngage's complete legal data-retention terms and the rights available to Indian data principals, including the grievance and Data Protection Officer contact, refer to the **Additional Information for Indian Residents** and **Data Retention** sections of the [MoEngage Privacy Policy](https://www.moengage.com/privacy-policy/).
## FAQs
> [accordion] If an archived user comes back to the platform, does MoEngage retain the user consent and subscription status?
>
> No. Once a user is archived, MoEngage removes that user from all MoEngage services. If the user returns, MoEngage treats them as a new user, and none of the earlier attributes are retained, including consent and subscription status.
> [accordion] Does updating a user property reset the archival clock?
>
> Yes. Sending a user property update — through the SDK, a Data API, or a file import — counts as activity, the same as a standard or custom event, and resets the archival clock.
> [accordion] Does MoEngage check reachability (for example, valid email or mobile number) before archiving a user?
>
> No. Archival is based only on inactivity — how long since the user's last event, attribute update, or campaign interaction. MoEngage does not check whether a user's contact details are valid or reachable.
# Data Tracking Policies
Source: https://moengage.com/docs/user-guide/data/key-concepts/data-tracking-policies
MoEngage enforces limits on unique events, attributes, and data types to protect data integrity. Review the complete data tracking policies.
Although MoEngage can ingest any amount of data that is being sent to us, we enforce certain limits on how you are tracking this data to ensure that the changes you make in data integration do not hamper the sanity of your data in MoEngage and for you to have a seamless experience while using this data to create and analyze your campaigns and user trends.
## Limits on Events and Attributes Tracked in MoEngage
The below limits apply when you track data in MoEngage:
| **Type** | **Limit** | **Handling for overage** |
| - | - | - |
| Unique Events | 512 | Events not tracked in the last 60 days will be removed first, and then new events will be blacklisted if the limit is still breached. |
| Unique User Properties | 256 | New User Properties will be rejected if limit breaches |
| Unique Event Properties | 100 per event | Only the first 100 event properties will be ingested. |
These limits don't represent any volume limits for Events / User properties, these only represent the unique number of custom events / attributes that can be tracked, from a fair usage policy standpoint. If you need to exceed the above limits, contact your Customer Success Manager or the MoEngage Support team[.](mailto:support@moengage.com) In case you are already breaching these limits, we will not blacklist existing events and attributes automatically. Still, if you send new events and attributes, these will get blacklisted based on the logic mentioned in the above table. Do reach out to us if you have any issues here.
## Limits on Event & Attribute Names and Values
The following table lists the limit values on events, attribute names.
| Key | Character Limit | Limit Breach Handling |
| - | - | - |
| Event name length | 200 | Store the first 200 characters only. |
| User property name length | 200 | Store the first 200 characters only. |
| User property value length | 512 | Store the first 512 characters only |
| Event property name length | 200 | Store the first 200 characters only. |
| Event property value length | 512 | Store the first 512 characters only. |
## Supported Datatypes
MoEngage will accept the below datatypes for attributes:
| Key | Allowed Data Types | Other Datatypes |
| - | - | - |
| User Property Value | Integer, Float, Double, Long, Boolean, String, Datetime, Array``, Array``, Array``, Array``, Array``, Array``, Object, Array of Objects | Ignore |
| Event Property Value | Integer, Float, Double, Long, Boolean, String, Datetime, Array``, Array``, Array``, Array``, Array``, Array``, Objects, Array of Objects | Ignore |
Additional Information for Data Tracking in MoEngage:
1. For lists, each element can be a maximum of 512 characters and a maximum of 50 elements per list.
2. For sending an attribute of datatype - datetime, please use the ISO 8601 date format (e.g. 2020-05-31T16:33:35Z) while sending data from our Data APIs and use our SDK date functions when sending data from the SDK directly. The SDK does not infer the datatype from the value, so a date sent from the SDK as a plain string is stored as a string even when it is in valid ISO 8601 format. Segmentation then offers the string operators for that attribute rather than the date operators. Please check with your Customer success team in case you are not able to send a certain ISO 8601 supported formats, the most commonly accepted formats are %Y-%m-%dT%H:%M:%S.%fZ; %Y-%m-%dT%H:%M:%SZ. Datetime values must be specified in GMT (UTC). Only GMT timestamps are accepted, any other offset passed are not consumed as dates.
3. If your attribute value is a URL and this exceeds the allowed character limit of 512 characters, we will reject the value completely. This is done to ensure that your image and URL personalization do not break.
4. For Arrays, the Array datatype should be homogenous (all the values in an array should be of the same datatype), and data typecasting is supported at an array level. For more information about typecasting, refer to [Data Typecasting](/docs/user-guide/settings/data-management/overview-data-management#array-typecasting).
# Fair Usage Policy (FUP)
Source: https://moengage.com/docs/user-guide/data/key-concepts/fair-usage-policy-fup
MoEngage's Fair Usage Policy ensures equitable resource access for all customers and protects workspaces from unregulated data ingestion.
## Overview
A Fair Usage Policy (FUP) is a set of guidelines and rules implemented to ensure all customers have equal and non-discriminatory access to MoEngage resources.
It helps in the following ways:
* Secures your workspace from unregulated external data tracking, which might increase your user count and overall integrity of data tracking.
* Ensures the fair allocation of MoEngage resources among all its customers. It ensures that large data ingestion caused by improper integration from a limited number of customers does not negatively impact data tracking for other customers.
MoEngage proactively identifies instances of FUP violations and blocks end-user level data tracking. As a marketer, you can still find these users in your workspace and send campaigns to them.
## How Does the Fair Usage Policy Work?
MoEngage has configured the data request limit above which the FUP is violated by analyzing the recent trends in the data tracked using the SDK, and hence, these FUP limits are rarely breached.
Whenever an end-user breaches the maximum number of events allowed, MoEngage temporarily blocks the data tracking of the user for a specific time limit. The duration of the temporary block depends on the time interval and the number of events received in that interval. However, despite the temporary block, if a user continues to breach the FUP limit two more times consecutively, the data tracking of that user is blocked for 7 days. For more information, refer to [Fair Usage Policy Limits and Actions](/docs/user-guide/data/key-concepts/fair-usage-policy-fup#fair-usage-policy-limits-and-actions).

## Fair Usage Policy Limits and Actions
The following tables showcase the FUP limits and actions taken if the limit is breached for a given end user.
### Non-SDK Sources (File Imports, Partner Integrations, Data APIs)
The limits below are cumulative across all non-SDK sources.
| Time Interval | Maximum Number of Events Allowed in the Specified Time Interval | Action Taken If the Maximum Data Request Limit Is Breached |
| - | - | - |
| 1 minute | 5,000 | Blocks the tracked data of that user for the next 1 hour. |
| 5 minutes | 10,000 | Blocks the tracked data of that user for the next 1 hour. |
| 1 hour | 50,000 | Blocks the tracked data of that user for the next 24 hours. |
| 1 day | 100,000 | Blocks the tracked data of that user for the next 24 hours. |
### SDK
| Time Interval | Maximum Number of Events Allowed in the Specified Time Interval | Action Taken If the Maximum Data Request Limit Is Breached |
| - | - | - |
| 1 minute | 500 | Blocks the tracked data of that user for the next 1 hour. |
| 5 minutes | 1,000 | Blocks the tracked data of that user for the next 1 hour. |
| 1 hour | 5,000 | Blocks the tracked data of that user for the next 24 hours. |
| 1 day | 10,000 | Blocks the tracked data of that user for the next 24 hours. |
> [!WARNING]
>
> For any of the above time intervals, the limit breach can occur a maximum of three consecutive times before MoEngage imposes a 7-day block. If imposed, all data tracking for that specific user is suspended for a 7-day duration.
### Fair Usage Policy on User Profile Activity Info
User profile activity info is powered by a high-speed storage for recent user actions. These events are stored for up to 30 days. To ensure optimal performance, if the number of events for a single user exceeds 12,000 or if the size exceeds 12MB, the older data is automatically purged. However, do note that there is a permanent storage (based on your retention policy) for all events, including those no longer visible in the activity info. These events are safe and accessible on segmentation and analytics.
### Fair Usage Policy on Number of Devices
A user profile can support a maximum of 1,000 devices. On breaching this limit, any subsequent devices, along with all associated user and event data, will not be processed in MoEngage.
### User and Device Data Expiry
A user or device record that receives no activity for 60 days is automatically removed from MoEngage. This applies only to dormant records with no incoming data in that window; events for active users continue to be stored per your account's Data Retention Policy.
## FAQ
> [accordion] Is the maximum number of events allowed within a specified time interval configurable?
>
> No, it is not configurable.
> [accordion] How is an FUP breach calculated if an end user uses two devices to access MoEngage resources?
>
> FUP is evaluated at the user level and not at the device level.
# Portfolio: Data Ingestion and Management
Source: https://moengage.com/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management
Manage data ingestion across projects with MoEngage Portfolio. Learn how user properties, events, and profiles work in a unified workspace.
This article explains data ingestion, management, and viewing within a MoEngage workspace where the [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) feature is enabled. This feature centralizes your data and user profiles, allowing for seamless management of user properties and events across all projects. This article covers:
* [Data ingestion](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#data-ingestion): How to ingest data using Data APIs, SDK, and Data Warehouse while specifying the relevant project.
* [Data management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#data-management): How data, events, and user properties are managed and presented within a Portfolio-enabled workspace, including a breakdown of unique event and user property limits.
* [User profile view](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#user-profile): How user data is displayed at both the portfolio and individual project levels.
* [Derived user properties](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#derived-user-properties-behaviour): How derived user properties (for example, LTV, First Seen) are calculated and displayed at both the project and portfolio levels.
> [!NOTE]
>
> The [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) feature is designed to unify user data from multiple projects into a single profile based on a unique ID field. Because of this, [Identity resolution](/docs/user-guide/data/user-data/unified-identity-identity-resolution) (the process of merging profiles) based on custom attributes is not supported.
# Data Ingestion
You (or your development team) can ingest data into a Portfolio-enabled workspace using:
* [Data APIs](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#data-apis)
* [SDK](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#sdk)
* [Data Warehouse](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management#data-warehouse)
## Data APIs
In MoEngage, data ingestion uses a unique ID to update a user property or event. For portfolio-enabled workspaces, you (or your development team) can use Data APIs (such as the [Track User](https://www.moengage.com/docs/api/user/track-user), [Create Event](https://www.moengage.com/docs/api/event/track-event), and [Bulk Import API](https://www.moengage.com/docs/api/bulk/bulk-import-users-and-events) to pass a *projectID* in the parameters. This ID identifies which project a user or event belongs to. You can find the **Project ID** at **Settings** > **Account** > **Portfolio** in your MoEngage dashboard.
**Use case** A brand has separate apps for "Brand A" (Project 1) and "Brand B" (Project 2). When a user downloads both apps, the Portfolio feature uses Data APIs or SDKs to ingest all their data. The *projectID* attribute identifies which brand the data originates from, ensuring all events and user properties are associated with the correct project while being unified under a single user profile.
> [!NOTE]
>
> While ingesting data using Data APIs, any attribute passed without a projectID is considered a custom portfolio user property.
The following are the sample cURL requests of Data APIs with projectID passed in the API endpoint:
**Track User:**
JSON
```json theme={null}
curl --location 'https://api-0X.moengage.com/v1/customer/{{APP_ID}}?app_id={{APP_ID}}&project_code={{project ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}'\
--data-raw '{
"type": "customer",
"customer_id": "{{customer_id}}",
"attributes": {
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"age": "67",
"email": "2uV4@xyz.com",
"gender": "male",
"mobile": "{{mobile}}",
"geo": "88.90 89.00",
"birthday": "02-12-2001",
"created_time": "1756198118474",
"last_seen": "1756198118474",
"userdata": "insert",
"revenue": 100,
"transaction": "100",
"platforms": [
{ "platform": "iOS",
"active": "true"
}
]
}
}'
```
**Create Event:**
JSON
```json theme={null}
curl --location 'https://api-0X.moengage.com/v1/event/{{appId}}?app_id={{appId}}&project_code={{projectId} \
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data-raw '{
"type": "event",
"customer_id": "123",
"actions" : [
{
"action": "ProductAdded",
"attributes": {
"product": "Accessories",
"color": "Black",
"Brand": "Adidas"
},
"platform": "Android",
"app_version": "1.2.3",
"user_time": "1708939453396",
"current_time" : "1708939453396"
}
]
}'
```
## SDK
Supported SDKs where portfolio changes are available:
* Android ([14.03.04](https://www.moengage.com/docs/developer-guide/android-sdk/sdk-integration/basic-integration/sdk-initialization))
* iOS ([10.07.0](https://www.moengage.com/docs/developer-guide/ios-sdk/sdk-integration/basic/sdk-initialization/config-based-initialization))
## Data Warehouse
The [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) feature enhances your data warehouse integration, giving you the flexibility to manage data correctly within your multi-project portfolio. This allows you to leverage your existing backend data for both brand-specific analysis and holistic customer understanding.
MoEngage handles different data types as follows:
* Event properties are ingested at the project level, allowing you to attribute specific actions to the correct brand.
* User properties are ingested at the portfolio level, and updates are applied to the user's global profile across all your brands.
### Event Properties (Project-Level)
For accurate analysis and segmentation in a portfolio, it is crucial to associate every event with a specific project. To achieve this, you must map a column from your data source to the dedicated MoEngage attribute: `moe_project_name`.

**Example Scenario:**
Let's assume you manage two brands: Project A (a sports app) and Project B (a shopping app). Your data table contains a column named `brand` with values like "Project A" or "Project B" for each event.
During data warehouse setup, you would map your `brand` column to the MoEngage event property `moe_project_name`. This directs MoEngage to automatically assign each event to the correct project based on the value in that column.
> [!WARNING]
>
> The values in your source column (for example, "Project A") must **exactly match** the Project Names configured in your MoEngage portfolio. If there is a mismatch, the event is ingested at the portfolio level and is not associated with any specific project. This data will be unusable in project-specific analysis or segmentation.
### Ingest User Properties (Portfolio-Level)
Conversely, any user properties you import are always applied at the portfolio level. This updates the user's single, global profile and is not tied to a specific project. The process is the same as for non-portfolio accounts, requiring you to map standard columns like `User ID` and `Updated at`.
> [!NOTE]
>
> You cannot use this method to import or update *project-specific* user properties. Only global user properties are supported via data warehouse imports.
For a complete step-by-step guide on the import configuration, please refer to our [Data Warehouse import guides](/docs/user-guide/data/imports/setting-up-a-data-warehouse-import).
# Data Management
A Portfolio-enabled workspace has the following details at **Settings** >**Data** > **Data Management**:
* The **Overview** tab displays the total number of unique events and user properties for the entire portfolio. While you can pass events and user properties between projects, the portfolio-level limits remain fixed by default: 1024 unique events and 1024 unique user properties. Ensure the total sum of unique events and user properties across all projects does not exceed these limits. This simplifies the process of tracking total unique events and attributes across your entire business, ensuring you stay within the fixed limits.
* The **Events** and **User attributes** tabs provide a holistic view of events and user properties across all projects. You can use the **Select project** list to filter the list and view data for specific projects. 
* **For standard and custom events**: MoEngage automatically adds the *moe_project_name* event property to all ingested events, specifying the project they originate from. For instance, a *Purchase* event from *Project1* includes the attribute *moe_project_name* with a value of *Project1*. 
* **For standard user properties**: MoEngage adds the project name as a suffix to both the **Display name** and **Key name** of the user property. For instance, the display and key name for the *custom_attr\_2* user property from *newproject* is *custom_attr_2_newproject*. 
* **For custom user properties**: MoEngage adds the project name as a suffix to the **Key name**, and the **Display name** remains the same as passed by the user without any suffixing. For instance, the key name for the *custom_attr\_2* user property from *newproject* is *custom_attr_2_newproject,* and the display name is *custom_attr_2.*
# User Profile
When Portfolio is enabled, the **User Info** tab in a user profile displays information at both the portfolio and project levels. For example, a user who interacts with both "Brand A" and "Brand B" will have a single profile where you can view their total *LTV Portfolio*, which is the sum of their LTVs from both projects.
In a user profile, you can view the following details at the portfolio level:
* First Name
* Last Name
* Email (Standard)
* Mobile Number (Standard)
* MoEngage ID
* ID
* Lifecycle
* Conversion
* Acquisition
* Reachability

You can view **User Properties** for a specific project by selecting the project from the drop-down menu.

# Derived User Properties Behaviour
> [!NOTE]
>
> If you have custom attributes with the same name across different projects, ensure you rename them in Data Management. This helps avoid confusion and ensures accuracy in personalization and conversions.
The following table lists the derived user properties tracked at the project and portfolio level:
| Derived User Property | Displayed at the Project Level? | Displayed at Portfolio Level? | Calculation Method (if applicable) |
| - | - | - | - |
| LTV | Yes | Yes |
LTV is calculated based on the conversion goal setup. For more information, refer to [Configure Lifetime Value (LTV)](/docs/user-guide/data/user-data/derived-user-attributes#configure-lifetime-value-ltv).
The **LTV Portfolio** displays the sum of all project-level LTVs.
Use the same event (the event property set across projects) for consistent project-level LTV tracking.
|
| First Seen | Yes | Yes | The **First Seen Portfolio** displays the oldest first seen across all projects within the portfolio. |
| Last Seen | Yes | Yes | The **Last Seen Portfolio** displays the recent last seen across all projects within the portfolio. |
| No. of conversions | Yes | Yes | |
| No. of Sessions | Yes | Yes | The number of sessions is tracked through the MoEngage SDK at a project level and is added up at the portfolio level. |
| Reachability Push Android | Yes | Yes | A user is considered reachable via push notifications if they are reachable in at least one project across the portfolio. |
| Reachability Push iOS | Yes | Yes | |
| Reachability Push Web | Yes | Yes | |
| Install status
Uninstall time
Device reinstall
User reinstall
| Yes | No | |
| Location attributes | Yes | No | |
| First name, Last name, birthday | No | Yes | |
| Email (Standard) | No | Yes | |
| Hard Bounce (Email) | No | Yes | |
| Spam (Email) | No | Yes | |
| Unsubscribe (Email) | No | Yes | |
| Mobile number (Standard) | No | Yes | |
| SMS subscription | No | Yes | |
| Whatsapp subscription | No | Yes | |
| Advertising ID (GAID, IDFV) | No | Yes | |
| Subscription Categories (Email) | No | Yes | |
| Consent for ad user data (Google Audience sync) | No | Yes | |
| Consent for ad personalization | No | Yes | |
# FAQs
> [accordion] What happens if the total number of unique user properties and events across all my projects exceeds the 1024 limit?
>
> All the unique user properties and events that exceed this limit are auto-blocked.
> [accordion] Is it possible to merge user profiles using custom user properties in a Portfolio-enabled workspace?
>
> No, it is not possible.
# Support for Object Data Type
Source: https://moengage.com/docs/user-guide/data/key-concepts/support-for-object-data-type
Use the Object data type in MoEngage to store key-value pairs for complex attributes like cart items, enabling richer user segmentation.
> [!NOTE]
>
> To enable this feature for your account, contact your MoEngage CSM (customer success manager) or the [Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard) team.
# Introduction
An *Object* is a versatile data type that holds data in a key-value pair. An object can hold a single or multiple key-value pairs. As a marketer, you may want to segment users depending on a specific item they have added to their cart. There may be enumerable attributes that define the specified item, which can be encapsulated in a single object and can used to identify the item. For example, you want to log a list of users who added the book *Atonement* to their cart. The book can be defined using the following Object:
Code
```json theme={null}
"book":{
"product_name": "Atonement"
"price" : 100,
"sku": "abc123"
}
```
In addition to the existing data type attributes such as string, numeric, and boolean, you can use the Object data type to run deeper queries and create custom user segments for more personalized marketing campaigns.
# Types of Objects
MoEngage supports the following types of objects:
## Simple Object
A simple object consists of an element holding multiple key-value pairs, as shown below:
Code
```json theme={null}
"book":{
"item-id": 123,
"item-name": "Atonement",
"item-cost": 100,
"item-currency": "USD"
}
```
## Nested Object
An object inside another object is a nested object, as shown below:
Code
```json theme={null}
"Stationary":{
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
}
```
## Array of Objects
An array of objects is a collection of elements that individually hold several key-value pairs, as shown below:
Code
```json theme={null}
"product":[
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
```
# Nomenclature Used in the Object Data Type
Consider the following object *Stationary*:
Code
```json theme={null}
"Stationary":{
Level 1 "item-id": 123,
Level 1 "item-type": "books",
Level 1 "item-cost": {
Level 2 "amount": {
Level 3 "cost-price": 100,
Level 3 "discount": 0,
}
Level 2 "currency": "USD"
}
}
```
The terms of the Object data type are described below:
| Terms | Description |
| - | - |
| Object attribute | In the example above, *Stationary* is the object attribute consisting of key-value pairs or sub-attributes. The *Stationary* object will also be considered a root object, which can have objects nested within it. |
| Sub-attributes | Sub-attributes are the key-value pairs inside the object attribute. In the example above: *item-id*, *item-type*, *cost-price*, *discount*, and *currency* are the sub-attributes or the key-value pairs. *item-cost*, and *amount* are the nested objects which have their own sub-attributes or key-value pairs. |
| Level 1 sub-attribute | Level 1 is the first level of sub-attribute nesting. |
| Level 2 sub-attribute | Level 2 is the second level of sub-attribute. |
| Level 3 sub-attribute | Level 3 is the third level of nesting. |
# Key Factors for Object Data Type Ingestion
| Key Factors | Description |
| :- | :- |
| **Max size of Object (bytes)** | The default size is 25 KB. Every object attribute containing key-value pairs should not exceed 25 KB. For example, an object `book`, as shown below, is considered an object attribute in MoEngage with multiple sub-attributes or key-value pairs: `{` `"book":{` `"product_name": "Atonement"` `"price": 100,` `"sku": "abc123"` `}` `}` The overall size of the object `book` should not exceed 25 KB. |
| **Max key-value pairs (sub-attributes)** | 100 sub-attributes supported inside an object attribute. You can archive unused sub-attributes within an object and ingest new sub-attributes through the Data management dashboard. `"book":{` `"product_name": "Atonement"` `"price": 100,` `"sku": "abc123"` `}` The above example has three key-value pairs or sub-attributes. |
| **Max number of array elements** | 100 is the maximum limit supported for the number of array elements in an Array of objects. The example below has three array elements. `"product":[` `{` `"item-id": 123,` `"item-type": "books",` `"item-cost": 100,` `"item-currency": "USD"` `},` `{` `"item-id": 323,` `"item-type": "apparel",` `"item-cost": 90,` `"item-currency": "USD"` `},` `{` `"item-id": 523,` `"item-type": "food",` `"item-cost": 200,` `"item-currency": "USD"` `}` `]` |
| **Max level of nesting** | MoEngage supports a maximum of two levels of nesting, and anything more than that will be stringified. However, MoEngage ingests any level of nested JSON. `"Stationary":{` `Level 1 "item-id": 123,` `Level 1 "item-type": "books",` `Level 1 "item-cost": {` `Level 2 "amount": {` `Level 3 "cost-price": 100,` `Level 3 "discount" : 0,` `}` `Level 2 "Currency": "USD"` `}` `}` In the example above, sub-attributes such as `cost-price` and `discount` are level 3 nested sub-attributes; they are ingested into MoEngage but in a string datatype. |
| **Key names** | Max length is 200 characters. Key names should not have the following special characters: `$`, `.`, `%`, `#`. `"book":{` `"item-id": 123,` `"item-name": "Atonement",` `"item-cost": 100,` `"item-currency": "USD"` `}` `Item-id`, `item-name` are key names which do not exceed 200 character limit. |
| **Key-values** | Max limits (default = 512 characters) follow our recommended limit for primitive data types. `"book":{` `"item-id": 123,` `"item-name": "Atonement",` `"item-cost": 100,` `"item-currency": "USD"` `}` Values corresponding to key names such as `Item-id` and `item-name` are called key values. Here, the key values are `123` and `Atonement`, which do not exceed the 512-character limit. |
| **Not an identifier** | Object attributes should not be marked as primary or secondary IDs in MoEngage. Object attributes comprising sub-attributes cannot be used as a User Identifier in MoEngage to create or update new users. Primitive data type attributes (for example, CustomerID in string datatype) need to be used. |
| **No logical operation** | Object data types do not support logical operations. Perform such operations on `Object.child` (if it is of primitive type). `"book":{` `"item-id": 123,` `"item-name": "Atonement",` `"item-cost": 100,` `"item-currency": "USD"` `}`In the previous example of an object attribute `book`, logical operations can be performed against the sub-attributes inside the `book` object but not on the `book` as a complete object. For example, logical operation that can be considered valid is: `book.item-cost < 150`; A logical operation that is considered invalid is: `book < 150`. |
| **PII or masked or blocked or hide** | The entire object attribute can be marked PII or encrypted. Sub-attributes or individual key-value pairs inside an object cannot be marked as PII, encrypted, blocked, or hidden separately. |
| **Max Object-type Attributes** | By default, MoEngage allows a maximum of ten user properties and five event properties as Object data types. That is, ten user property objects and five event property objects totaling 15 object attributes in a workspace. |
| **Custom attributes only (both User and Event)** | Only custom attributes can be an Object data type. Attempting to send an Object data type on standard attributes will not be accepted. Standard or derived attributes (tracked through SDK) found at **Settings** > **Analytics and Data** > **Data management** are not Object data types. |
| **Null handling** | If the incoming Object type attribute is Null or empty, it is not ingested into MoEngage. If an object consists of an attribute that has no values among other attributes which have value, that object is partially ingested: `"product":[` `{` `"item-id": 123,` `"item-type": "books",` `"item-cost": 100,` `"item-currency": "USD"` `},` `{` `"item-id": null,` `"": 100` `},` `{` `"item-id": 523,` `"item-type": "food",` `"item-cost": 200,` `"item-currency": "USD"` `}` `]` Data ingested into MoEngage is as shown below: `"product":[` `{` `"item-id": 123,` `"item-type": "books",` `"item-cost": 100,` `"item-currency": "USD"` `},` `{` `"item-id": 523,` `"item-type": "food",` `"item-cost": 200,` `"item-currency": "USD"` `}` `]` |
# Ingest Object Data Type
This section describes how you can ingest the Object data type into MoEngage.
## S2S API
Sample cURL request
```json theme={null}
curl --location 'https://api-xx.moengage.com/v1/transition?app_id=O7NIHY0AT1K1FL8DR1J1G' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data-raw '{
"type": "transition",
"elements": [
{
"type": "customer",
"customer_id": "tONX83z_new",
"attributes": {
"name": "xQEC",
"first_name": "",
"last_name": "",
"age": "70",
"email": "Ra4X@xyz. Com",
"gender": "female",
"mobile": "238706106351",
"geo": "88.90 89.00",
"birthday": "02-12-2001",
"created_time": "1716372929998",
"last_seen": "1716372929998",
"source": "FBsuS",
"object_with_nesting_user_attribute_01": {
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_01": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
],
"platforms": [
{
"platform": "ANDROID",
"active": "true"
}
]
}
},
{
"type": "event",
"customer_id": "tONX83z",
"actions": [
{
"action": "object_event_s2s_ios_level1",
"attributes": {
"object_with_nesting_event_attribute_01": {
"item-id": 123,
"item-type": "books",
"item-cost_event_attribute": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_event_attribute_01": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"platform": "",
"app_version": "3019",
"user_time": "1716372929998",
"current_time": "1716372929998"
}
]
}
]
}'
```
## SDK
Sample cURL request
```json theme={null}
curl --location 'endpoint' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--data-raw '{
"viewsInfo": [
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_UNIQUE_ID": "123"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_NAME": "xQEC"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_FIRST_NAME": "JgfOr"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_EMAIL": "Ra4X@xyz. Com"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"USER_ATTRIBUTE_USER_LOCATION": "104.248,122.203"
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "EVENT_ACTION_USER_ATTRIBUTE",
"EVENT_ATTRS": {
"object_with_nesting_user_attribute_001": {
"item-id": 123,
"item-type": "books",
"item-cost_0001": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_002": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
},
{
"EVENT_ACTION": "object_event_reports_ios_level1",
"EVENT_ATTRS": {
"object_with_nesting_user_attribute_003": {
"item-id": 123,
"item-type": "books",
"item-cost": {
"amount": 100,
"currency": "USD"
}
},
"array_of_object_sample_user_attribute_004": [
{
"item-id": 123,
"item-type": "books",
"item-cost": 100,
"item-currency": "USD"
},
{
"item-id": 323,
"item-type": "apparel",
"item-cost": 90,
"item-currency": "USD"
},
{
"item-id": 523,
"item-type": "food",
"item-cost": 200,
"item-currency": "USD"
}
]
},
"EVENT_L_TIME": "22:05:2024:14:02:01",
"EVENT_G_TIME": "1716372930"
}
],
"viewsCount": 3,
"identifiers": {}
}'
```
## Snowflake
The Object data type is supported in Snowflake as well.
### Store Compatible JSON Data in Snowflake
To store valid JSON inside Snowflake, you must change the data type of the column to *VARIANT* type. For more information, refer [here](https://docs.snowflake.com/en/user-guide/tutorials/json-basics-tutorial).
The JSON stored inside Snowflake should be a valid JSON; otherwise, the values will not be written as JSON. Here is an example JSON column:
JavaScript
```json wrap theme={null}
{ "Designation": "SSE", "Palace": "Banglore", "age": 30, "name": "Shasha" }
```
### Import JSON Data via Snowflake
Existing attributes in MoEngage that have been marked as an *Object* type and are available to map to columns in Snowflake:

You can always create new Object attributes from the mapping step as well, as shown below:

> [!NOTE]
>
> MoEngage does not support mapping with nested attributes. Only top-level attributes are available to map.
## Zapier
Zapier now supports creating users and events with object-type attributes. To mark an attribute as an *object* type, you need to define these attributes inside the *Object-type Attributes* list:

Any attribute with an invalid JSON value is dropped. The same flow applies to the *Import User Event Action*.
> [!NOTE]
>
> Any attributes that are intended to be Object type but are defined under the *Custom Attributes* list are sent to MoEngage as strings. Here, the default type casting conversion rules of MoEngage are applied based on the attribute’s pinned data type.
### Exceptions
* Only five objects can be ingested for each workspace by default.
* Elements inside an object or in an array_objects are dropped if nulls or blanks exist.
| Sr. No. | Sample Payload | MoEngage Behavior |
| - | - | - |
| 1 | `attribute0 : {}` | Dropped |
| 2 | `attribute01 : { }` | Dropped |
| 3 | `Attribute61 : [{ "a" : {} }, {"valid" : false}]` | `[{"valid": false}]` is ingested, rest of the elements are dropped |
| 4 | `{"": "value" }` | Dropped |
* A heterogeneous array of objects is not supported. An array of objects should only consist of objects as the array elements.
* Case 1: If there is a mix of objects and primitive elements, primitive elements are dropped.
* Case 2: If there are no objects in the array but the array consists of other primitive elements, MoEngage takes the first element’s datatype as the reference datatype and attempts to typecast the rest of the elements into that datatype. If this attempt is unsuccessful, the elements are dropped.
# Use Object Data Type
This section describes how to use the Object data type.
## Data Management
After ingesting your Object data type attributes in MoEngage, you can manage them in the **Data management** section of the MoEngage dashboard. To edit an Object data type, follow the steps below:
1. Navigate to your MoEngage dashboard and click **Settings** > **Analytics and Data** > **Data management** > **User attributes** or **Events**.
2. Select the user property of the Object data type or search for one using the search bar. 
3. Click the vertical ellipsis on the attribute row and click **Edit**.

4. Modify your Object structure. For example, change the string attribute to boolean, numeric to string, and so on.

5. Click **Save**. A warning is displayed on saving the modifications. 
6. Click **Continue** to confirm.
> [!NOTE]
>
> You can edit the Object attribute once every 24 hours. For the same reason, the edit option will only be activated 24 hours following the current edit.
## Activities Allowed on Object Attributes in Data Management
* You can pin data type as Object or Array of Object for any custom user or event property.
* For any Object or Array of Object data type, the system auto-detects the object's structure and saves it as metadata for segmentation.
* The structure detected must have all children of the Object and their data type up to two levels.
* You can manually define each child node for any Object or Array of Object type attribute.
* If the schema of an Object attribute is defined manually, it cannot be modified for 24 hours (to avoid unwanted issues with any running campaigns/triggers). After the schema is manually defined, any incoming data is validated against it and rejected if it does not conform to the definition.
* For any Object or Array of the Object type attribute, you can paste a sample JSON to generate a defined Object structure.
* You can specify the data type of each child node up to two levels. The data types supported are as follows:
* Numeric
* Boolean
* String
* Date type
* Primitive Array
* JSON (to ingest any level of nested object)
* You can create more than 100 children nodes for any object definition. If an object has more than 100 children nodes, MoEngage accepts only the first 100 children nodes defined earlier.
* If an existing attribute is pinned as an object, the previous values are not type-casted and left as they are.
* New values coming in for the attribute are treated differently for different scenarios as follows:
* If the incoming value is an object under defined limits, it will be accepted.
* If the incoming value is a primitive data type (number, string, bool), it is encapsulated and typecasted as an object.
* You can change the data type of an attribute pinned as an object to “Any” or any of the primitive data types.
* You can change Block/Unblock and Show/Hide sub-attributes of the Object data type for only root-level attributes.
* You can edit the schema of Object data type attributes in the following manner:
* Add new sub-attributes to the object for up to two levels of nesting.
* Delete existing sub-attributes.
## Exceptions
* An attribute can ingest data as an object or as any primitive data type.
* Any attribute that has ingested any data point of the object data type cannot be encrypted.
* Any attribute that has been ingesting data in any primitive data type and marked as PII encrypted attribute cannot ingest object data points going forward.
# User Profile
This section describes the user profile.
## User Info
After you ingest your Object data type attributes in MoEngage, you can view them in the **User Profile** section on your MoEngage dashboard. To view the Object attribute, follow the steps below:
1. Navigate to your MoEngage dashboard and create a Segment with object attributes.
2. On the Create segment page, scroll down to the **Query Results** section and then select a query.
3. Select a sample user to navigate to the User Profile page. Alternatively, use the upper right search bar to search for a user with an ID.
4. You can view all your object-type attributes on the User Profile page under the **Tracked Custom Attributes** section. 
## Activity Info
To view the object attribute associated with an event in activity info, follow the steps below:
1. Navigate to your MoEngage dashboard and create a Segment with Object attributes.
2. On the Create segment page, scroll down to the **Query Results** section and then click a query to expand it.
3. Select a sample user to navigate to the User Profile page. Or search for a user (using user ID) in the user search box on the upper right corner of the Create segment page.
4. From the User Profile page, go to the **Activity Info** tab, where you can view all your events and event properties in the object type section.
# Object Data Type Support in Campaigns and Channels
The table below mentions the delivery type and indicates whether or not the object data type is supported across different campaigns.
| Campaign Type | Push | Email | SMS | WhatsApp | Connector |
| - | - | - | - | - | - |
| One Time | Yes | Yes | Yes | Yes | Yes |
| Periodic | Yes | Yes | Yes | Yes | Yes |
| Event Triggered | Yes | Yes | Yes | Yes | Yes |
| Business Event Triggered | No | No | No | NA\* | NA\* |
| Device Triggered | No | NA\* | NA\* | NA\* | NA\* |
| Location Triggered | Yes | NA\* | NA\* | NA\* | NA\* |
NA\* indicates that the delivery type is not supported for that particular campaign.
The table below mentions the channels and indicates whether the object data type is supported.
| Channels | In-app | Onsite | Cards | Facebook | Google Ads | Web Personalization |
| - | - | - | - | - | - | - |
| Object data type supported or not | Yes | Yes | No | No | No | Yes |
The table below outlines the steps involved in campaign creation and indicates whether the object data type is supported across different campaigns.
| Campaign Creation Steps | Object Data Type Supported? |
| - | - |
| Target Users > Select audience > All users, Filter users by > User property, User behavior | Yes |
| Content > Link personalization, Image personalization, preview | Yes |
| Content > Add new locale > User Property | No |
| Schedule and goals > Conversion goals > New goal > Select an event | No |
The table below outlines the steps involved in Flow creation and indicates whether the object data type is supported across different campaigns.
| Flow creation steps | Object Data Type Supported? |
| - | - |
| When will users enter the flow > On event trigger > IF user has executed > Select an event | Yes |
| When will users enter the flow > On flow exit > When user has exited > Select by name | Yes |
| Who will enter the flow > Audience > All users, Filter users by> User property, User behavior | Yes |
# User Data Export
User data export (the **Export Users** action on a segment) does not support Object data-type attributes. If you export a segment with an Object or array-of-objects attribute selected, that attribute is exported as invalid or incomplete JSON and cannot be reliably parsed, because the export pipeline does not support Object data types. For more information on exporting users from a segment, refer to [Manage Segments](/docs/user-guide/segment/create-segments/manage-segments#actions-on-custom-segments).
# What's Next
Using [Object Data Type in Segmentation](/docs/user-guide/segment/advanced-concepts/object-data-type-in-segmentation).
# Android Advertising ID Tracking
Source: https://moengage.com/docs/user-guide/data/privacy/android-advertising-id-tracking
Comply with Google's advertising ID policy in MoEngage. Learn how to opt in for personalization using Android advertising ID with user consent.
# Overview
As part of the Google User Data policy update in April 2022, the advertising identifier may not be connected to persistent device identifiers (for example, SSAID, MAC address, IMEI, and so on) for any advertising purpose. The advertising identifier may only be connected to personally-identifiable information with the explicit consent from the user.
MoEngage complies with the guidelines mentioned in the Google Play Developer Program Policy and has built industry-standard APIs in the SDKs that enable you to opt-in for personalization using advertising ID only after explicit consent from the user.
The details about the data privacy requirements stated in Google Play Developer Program policies and recommendations on how to comply with them while using MoEngage are described in this article. Using these policies keeps your app in good standing on Google Play and keeps your users protected.
# What Is the Policy?
The [Android Advertising ID (AAID) or Google Advertising Identifier (GAID)](https://support.google.com/googleplay/android-developer/answer/9857753) is a unique, user-resettable ID for advertising, provided by Google Play services. As part of the Google Play services update in April 2022, the advertising identifier can be connected to personally-identifiable information or associated with any persistent device identifier only after taking explicit consent from the user.
> [!NOTE]
>
> The [best practices for working with Android identifiers](https://developer.android.com/training/articles/user-data-ids#best-practices-android-identifiers) mention that you connect the advertising identifier to personally-identifiable information only after taking [explicit consent from the user](https://support.google.com/googleplay/android-developer/answer/11150561).
All Android apps listed on the Google Play store are affected. If you are generating persistent device identifiers and mapping them with AAID and not taking adequate consent from the user in accordance with the [User Data policy](https://support.google.com/googleplay/android-developer/answer/10144311?visit_id=637570411965975172-4240498562\&rd=1) depending on your data requirements and user flows, Google Play Console does not allow you to post new versions of your app from August 2022 end.
# How Does It Affect Your App?
MoEngage SDK uses a Device ID (persistent device identifier) to uniquely identify the user to deliver personalized content and associates this to AAID if allowed by the app.
AAID is one of the device attributes used by MoEngage to improve:
* Accurate identification of reachable devices for sending Push notifications. If the user opts out of AAID tracking, this may lead to an increased number of users reachable using Push notifications.
* Tracking re-installs for users over time. If the user opts out of AAID tracking, this may lead to re-installs being tracked as new installs.
If AAID is passed to MoEngage SDK without proper consent, you may receive this warning from the Google Play team.
#### Email Message
Your app includes SDK `com.moengage:moe-android-sdk` or an SDK that one of your libraries depends on, which collects personal or sensitive data that includes but is not limited to Advertising ID identifiers that may not be linked to other personal and sensitive user data or resettable device identifiers as described in the User Device policy.
This is only a warning and has no impact on your app’s User experience or its Play Store listing till the end of August 2022. We've seen our customers getting different dates; please check the email you've received from Google for the exact date for your app. You can take this time to ensure compliance with the Google Play store guidelines by implementing the solutions recommended below.
# Enable Advertising ID Tracking with MoEngage SDK
## For MoEngage SDK versions 12.2.01 and later
With Android SDK version 12.2.01 released in April 2022, we have added the required APIs and support for enabling tracking of the specified identifiers only after the user’s consent. For more information, refer to [Enabling Advertising ID tracking](https://www.moengage.com/docs/developer-guide/android-sdk/data-tracking/basic/enable-advertising-identifier-tracking).
The Google Play team has reviewed and approved MoEngage SDK version 12.2.01.
For support on other frameworks apart from Android native, we would provide similar methods to enable tracking AAID with our new SDK versions on these frameworks planned to be released by 31st July 2022.
## For MoEngage SDK versions 12.0.00 and earlier
MoEngage SDK versions 12.0.00 and lower track advertising identifiers by default and map them against the persistent identifiers. The mapping is according to the latest User Data Policy.
MoEngage strongly recommends that you update to the latest version for ease of opt-in and opt-out of tracking AAID.
### What if I cannot Update the SDK to the Latest Version Right Now?
If you receive a warning and cannot immediately upgrade your MoEngage SDK and enable opt-in tracking properly, you can opt-out of tracking device identifiers on MoEngage SDK while initializing the SDK. To enable tracking again after taking the consent from the user, you need to re-initialize the SDK with the required configurations. For more information, refer to the [developer documentation](https://www.moengage.com/docs/developer-guide/android-sdk/data-tracking/advanced-or-optional/configuring-opt-outs).
This is not a recommended method as this requires reinitializing MoEngage SDK and any previous initialization configurations is discarded.
Additionally, if you have any other queries regarding Google Play user data policies, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Frequently Asked Questions
> [accordion] How to ask for consent from the user to track AAID?
>
> As mentioned in the [Best practices for working with Android identifiers](https://developer.android.com/training/articles/user-data-ids#best-practices-android-identifiers), you must connect the advertising identifier to personally-identifiable information only after taking [explicit consent from the user](https://support.google.com/googleplay/android-developer/answer/11150561).
> [accordion] Should I disable tracking AAID?
>
> Tracking AAID helps MoEngage maintain accurate data with the use cases listed in this article. If you update the MoEngage SDK and implement Advertising ID tracking in the method recommended above, there is no need to disable it in all cases.
> [accordion] Does this affect any of my data tracking or campaigns?
>
> No impact on how campaigns such as Push notifications, and In-App messages are delivered to users. This may have an impact on some reported data such as Push reachability and tracking re-installs.
# Apple Privacy Manifest Update
Source: https://moengage.com/docs/user-guide/data/privacy/apple-privacy-manifest-update
Prepare your iOS app for Apple's privacy manifest requirements. See how MoEngage SDKs comply with WWDC23 privacy and signature guidelines.
# Overview
At WWDC23, Apple introduced new privacy manifests and signatures for SDKs to help app developers better understand how third-party SDKs use data, secure software dependencies, and provide additional privacy protection for users.
Starting **May 1st 2024**, if your new app or app update submission adds a third-party SDK that is commonly used in apps on the App Store, you must include the privacy manifest for the SDK.
Signatures are also required when you use the SDK as a binary dependency. This functionality is a step forward for all apps, and we encourage all SDKs to adopt it to better support the apps that depend on them. For more information, refer to the [official announcement from Apple](https://developer.apple.com/news/?id=r1henawx).
# How Does MoEngage Comply with this?
This section describes how MoEngage complies with the new privacy manifests and signatures for SDKs.
## Privacy Manifest
The [Privacy Manifest](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_data_use_in_privacy_manifests) is a file that describes the specific privacy practices and data collection activities of an iOS app. It provides essential information to users about how their personal data is collected, used, and shared by the app. This is a requirement by Apple for developers to ensure transparency and allow users to make informed decisions about their privacy. It includes details on the types of data collected (such as personal information, location, browsing history), how the data is used, and whether it is shared with third parties.
Based on the [documentation from Apple](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_data_use_in_privacy_manifests), "Third-party SDKs need to provide their own privacy manifest files that record the types of data they collect. Your app’s privacy manifest file doesn’t need to cover data collected by third-party SDKs that your app links to."
MoEngage iOS SDK decrales the following data.
| NSPrivacyCollected DataType | NSPrivacyCollected DataTypePurposes | Modules with NSPrivacyCollected DataTypeLinked | Modules with NSPrivacyCollected DataTypeTracking |
| - | - | - | - |
| UserID | Analytics, Product personalization, App functionality | MoEngage-iOS-SDK | - |
| Device ID (IDFV) | Analytics, Product personalization, App functionality | MoEngage-iOS-SDK | - |
| Product interaction | Analytics, Product personalization, App functionality | - | MoEngage-iOS-SDK, MoEngageRichNotification, MoEngageInApps, MoEngageCards, MoEngageInbox, MoEngageRealTimeTrigger, MoEngageGeofence |
| Precise location | Analytics, Product personalization, App functionality | - | MoEngageGeofence |
| Coarse location | Analytics, Product personalization, App functionality | - | MoEngageGeofence |
## Code Signing
When you add third-party binary SDKs to your target as XCFrameworks, the behavior of those packages becomes part of the behavior of your product. An attacker who can inject a compromised version of the SDK into your project can change your app’s behavior and cause security and privacy issues for your developers, testers, and people who use your product. To avoid those, we have code-signed all the MoEngage frameworks.
## Which SDK versions support the Apple Privacy Manifest?
To comply with the policy, you must upgrade your iOS app with the latest MoEngage SDK.
MoEngage SDKs core version 9.16.2 and above is compliant with the guidelines from Apple and the following data is declared from the Privacy manifests. For Hybrid frameworks, below are the modules associated with SDKs core version 9.16.2
* MoEngage React Native SDK: 9.0.0
* MoEngage Flutter SDK: 7.0.0
* MoEngage Cordova SDK: 8.6.0
* MoEngage Capacitor SDK: 3.3.0
* MoEngage Unity SDK: 3.2.0
# By When Should I Upgrade My App?
Apple documentation mentions the following:
**Starting March 13:** If you upload a new or updated app to App Store Connect that uses an API requiring approved reasons, we’ll send you an email letting you know if you’re missing reasons in your app’s privacy manifest. This is in addition to the existing notification in App Store Connect.
**Starting May 1:** You’ll need to include approved reasons for the listed APIs used by your app’s code to upload a new or updated app to App Store Connect. If you’re not using an API for an allowed reason, please find an alternative. And if you add a new third-party SDK that’s on the list of commonly used third-party SDKs, these API, privacy manifest, and signature requirements will apply to that SDK. Make sure to use a version of the SDK that includes its privacy manifest and note that signatures are also required when the SDK is added as a binary dependency.
Therefore, we strongly recommend updating the MoEngage iOS SDK with your next app update. Otherwise, your next app update may get rejected.
However, you do not need to rush an app upgrade only to comply with the requirements.
# What will happen to my current app users?
This change only affects App versions published on or after May 1, 2024. Users on App versions published before this will not be affected including new installs and reinstalls.
# CCPA
Source: https://moengage.com/docs/user-guide/data/privacy/ccpa
Understand how MoEngage helps you comply with the California Consumer Privacy Act. Learn about CCPA requirements for data privacy and user rights.
## What Is CCPA?
The California Consumer Privacy Act (CCPA) is California’s privacy law aimed at enhancing consumer privacy rights for residents of California, United States. The law became fully enforceable on July 1st, 2020.
## Who Is Affected by CCPA?
Under the CCPA, businesses that earn \$50,000,000 a year in revenue, sell 100,000 consumers' records each year, or derive 50% of their annual revenue by selling your personal information (PI) must comply. All businesses must comply if they collect or sell Californians' personal information, whether they are located in California, a different state, or even a different country.
## Key Facts of CCPA
The following are the key facts of the CCPA:
### Own Your Personal Information
#### Right to Know What Personal Information Is Being Collected
As a consumer, you have the right to request the business that collects your personal information to disclose to you the categories of personal information that it has collected about you.
#### Right to Know Whether Personal Information Is Sold or Disclosed and to Whom
As a consumer, you have the right to request that the business that sells your personal information or discloses it for a business purpose, to disclose to you:
* The personal information that is sold to third parties and the identity of such third parties
* The personal information that is disclosed for a business purpose to third parties and the identity of such third parties
### Control Your Personal Information
If you do not want a corporation to sell your information, you can stop them by clicking the **do not sell my data** link. The corporation cannot hide this in a privacy policy—they have to display it clearly at the bottom of any page where they collect your information. If you tell them not to sell your info, they cannot discriminate against you. This means they cannot charge you more, deny you access to services, or change the quality of the service you get.
### Secure Your Personal Information
A business that owns, licenses, or maintains personal information about a Californian resident needs to implement and maintain reasonable security procedures and practices appropriate to the nature of the information. The business needs to protect the personal information from unauthorized access, destruction, use, modification, or disclosure.
### Hold Big Corporations Accountable
Under the CCPA, only businesses that earn \$50,000,000 a year in revenue, sell 100,000 consumer records each year, or derive 50% of their annual revenue by selling your personal information must comply. Such businesses must comply if they collect or sell Californians' personal information, whether they are located in California, a different state, or even a different country.
### How Is Personal Information Defined Under the CCPA
The CCPA defines “personal information” as any information that identifies, relates to, describes, is capable of being associated with, or could reasonably be linked, directly or indirectly, with a particular consumer or household.
The CCPA documentation provides specific examples of personal data. The list includes, but is not limited to, the following identifiers:
* Identifiers such as a real name, alias, address, email address, social security number, license number, passport number, or similar identifiers.
* Commercial information including property records, product purchases, and other consumer histories and tendencies.
* Biometric data such as fingerprints and facial recognition data.
* Internet or network activity data, such as IP addresses, browsing history, search history, and interactions with online sites or advertisements.
## MoEngage Compliance with CCPA
### Right to Know What Personal Information Is Being Collected
You can accomplish user data retrieval in several ways:
* The Get User API of MoEngage provides all collected data for the specified users. For more information, refer to [Get User API](https://www.moengage.com/docs/api/user/get-user).
* You can export user data from MoEngage. Navigate to the Segmentation module on the MoEngage dashboard and download the data as required. For more information, refer to [User Data Exports](/docs/user-guide/analyze/analytics/user-data-exports).
* You can also contact your MoEngage Customer Success Manager (CSM) or the Support team for a copy of all data we have for any user.
### Right to Know Whether Personal Information Is Sold or Disclosed and to Whom
We only send the information to the following third-party platforms if you have opted in for MoEngage email or SMS sending:
* Email Connector (Sendgrid or any other as per the client setup)
* SMS Connector or Service Provider (Gupshup or any other as per the client setup)
For more information on this, refer to [privacy policy](https://www.moengage.com/privacy-policy/).
### Right to Say No to the Sale or Disclosure of Personal Information
We do not sell personal information at all. If a user requests to opt-out of data processing, you can do so by following the SDK methods listed in our integration documents:\
[Android](/docs/user-guide/getting-started/integration/default-android-sdk) | [iOS](/docs/user-guide/getting-started/integration/default-ios-sdk) | [Web](/docs/user-guide/getting-started/integration/default-web-sdk)
### Data Deletion
You can delete the data of your users when required. To do this, we have hosted the GDPR/CCPA API that removes all personal data associated with specific users who have requested their data to be erased from MoEngage. For more information, refer to [GDPR/CCPA API](https://www.moengage.com/docs/api/gdpr/submit-a-gdpr-ccpa-data-request).
The API accepts one of the following parameters as input:
* ID (required for logged-in users)
* Email
* Mobile Number
* GAID (required for anonymous users)
* IDFA (required for anonymous users)
Removing a user’s personal data erases their personal data from MoEngage. To maintain the integrity of campaign and application usage analytics, anonymous aggregated data is not modified when an end user is removed (for example, MoEngage does not decrement an app’s MAU numbers or Campaign Stats when an end user is deleted). However, this data is not connected in any way to the profile of the forgotten end user, ensuring that this anonymized and aggregated data cannot be tied back to any individual user.
After the API request is made to remove personal data for specific users, it takes a maximum of 7 days for completing this request. It may, however, take 60 days to remove this data from all our logs and backups. We need to maintain the data for 60 days to justify our processing of erasure requests of personal data related to every user.
## CCPA and GDPR
The General Data Protection Regulation (GDPR) applies to all activities involved in the processing of personal data—including storing, accessing, and transferring data. The CCPA, however, only applies to the collection, sale, and disclosure of personal information for business purposes.
# GDPR
Source: https://moengage.com/docs/user-guide/data/privacy/gdpr
Learn how MoEngage complies with GDPR regulations. Explore user rights like data erasure, portability, and consent management with built-in APIs.
The General Data Protection Regulation (GDPR) framework sets guidelines for the collection and processing of personal data of individuals who live in the European Union (EU). This regulation aims to provide users complete control over their data.
MoEngage complies with the guidelines mentioned in the GDPR and has built industry-standard APIs and SDKs, which enable you to easily respond to the requests raised by individual users.
This article details the rights users have under the GDPR and recommendations on how to comply with each of these rights while using MoEngage.
## Right To Erasure
### What Is It?
The "Right to Erasure" allows data subjects to delete all information that you have about them from your servers and the servers of your data processors such as MoEngage.
### How to Implement It?
To comply with this right, we have hosted the GDPR/CCPA API that removes all personal data associated with specific users who have requested their data to be erased from MoEngage. For more information, refer to [GDPR/CCPA API](https://www.moengage.com/docs/api/gdpr/submit-a-gdpr-ccpa-data-request).
The API accepts one of the following parameters as input:
* ID (required for logged-in users)
* Email
* Mobile Number
* GAID (required for anonymous users)
* IDFA (required for anonymous users)
Removing a user’s personal data erases their personal data from MoEngage. To maintain the integrity of campaign and application usage analytics, anonymous aggregated data is not modified when an end user is removed (for example, MoEngage does not decrement an app’s MAU numbers or Campaign Stats when an end user is deleted). However, this data is not connected in any way to the profile of the forgotten end user, ensuring that this anonymized and aggregated data cannot be tied back to any individual user.
After the API request is made to remove personal data for specific users, it takes a maximum of 7 days for completing this request. It may, however, take 60 days to remove this data from all our logs and backups. We need to maintain the data for 60 days to justify our processing of erasure requests of personal data related to every user.
For more information on the GDPR erase API, refer to [GDPR/CCPA API](https://www.moengage.com/docs/api/gdpr/submit-a-gdpr-ccpa-data-request).
## Right to Access
### What Is It?
The data subject under the GDPR has the right to Confirmation that the users' data being processed, access to their data, and other supplementary information largely correspond to the information that must be provided in a privacy notice (see [GDPR Article 15](https://gdpr-info.eu/art-15-gdpr/)).
### How to Implement It?
You can export user data from MoEngage. Navigate to the Segmentation module on the MoEngage dashboard and download the data as required. For more information, refer to [User Data Exports](/docs/user-guide/analyze/analytics/user-data-exports).
MoEngage also hosts an API that returns all the personal data associated with specific users (who have requested data access from MoEngage). For more information, refer to [Get User API](https://www.moengage.com/docs/api/user/get-user).
## Right to Rectification
### What Is It?
Data subjects, under GDPR, are entitled to have personal data rectified if it is inaccurate or incomplete. If you have disclosed the personal data in question to third parties, you must inform them of the rectification where possible.
### How to Implement It?
MoEngage customers can update the data of specific users in MoEngage by using one of our Data Import APIs. These are enabled for all clients by default and can be used whenever an end-user requests for their information to be updated. For information on MoEngage Data Import API and how to update user data in MoEngage, refer [here](https://www.moengage.com/docs/api/data/data-overview).
## Right to Data Portability
### What Is It?
The right to data portability allows individuals to obtain and reuse their personal data across different services.
### How to Implement It?
Similar to Right to Access, MoEngage customers can easily download data of specific users based on any user identifier. MoEngage dashboard users with Admin and Manager access can download user data directly from the dashboard. For more information, refer to [User Data Exports](/docs/user-guide/analyze/analytics/user-data-exports).
You can also use the Get User API of MoEngage to request data about specific users. For more information, refer to [Get User API](https://www.moengage.com/docs/api/user/get-user).
## Right to Restriction of Processing
### What Is It?
Data subjects have the right to block or suppress the processing of specific subsets of their personal data in the event of inaccurate or improperly obtained data. When processing is restricted, you are permitted to store the personal data, but not further process it. You can retain just enough information about the individual to ensure that the restriction is respected in the future.
### How to Implement It?
To comply with the data tracking opt-out requests of users under the "Right To Restriction of Processing" of GDPR, our SDKs have the methods to opt-out of data tracking.
For information on leveraging the capabilities of our SDKs to restrict data processing, refer to:
[ANDROID](https://www.moengage.com/docs/developer-guide/android-sdk/compliance/compliance) | [iOS](https://www.moengage.com/docs/developer-guide/ios-sdk/compliance/compliance) | [Web](https://www.moengage.com/docs/developer-guide/web-sdk/web-sdk-integration/basic-integration/web-sdk-integration)
After the data processing is stopped from the SDK, it does not track any events except the ones which can be tracked anonymously such as:
* Push (Notification Received Android, Notification Clicked Android, Notification Swiped Android)
* iOS Push (Notification Sent iOS, Notification Clicked iOS)
* Web Push (Notification Received Web, Notification Clicked Web)
* In-App (InApp Shown Android, InApp Clicked Android, InApp Closed Android, App Rated)
* In-App (InApp Shown iOS, InApp Clicked iOS, InApp Closed iOS, App Rated)
* Anonymous lifecycle events (MOE_APP_EXIT, TOKEN_EVENT, App/Site Opened, Viewed Web Page)
* Stats events (NOTIFICATION_OFFLINE_MOE,DT_CAMPAIGN_SCHEDULED, EVENT_ACTION_COPY_COUPON_CODE)
Remember the following points when implementing the data tracking opt-out methods of our SDK:
* Opting out of data tracking does not ensure the erasure of data. To restrict the processing of data and also erase it completely, make the erase API request separately.
* Opting out of data tracking does not ensure that push notifications are not sent. To suppress push notifications on devices/users, refer to [Opt Out of Campaign Messages](/docs/user-guide/data/privacy/gdpr#opt-out-of-campaign-messages)**.**
## Right to Object
### What Is It?
Data Subjectshave the right to object to the processing of their personal data at any time. This effectively allows individuals to stop or prevent you from processing their personal data.
### How to Implement It?
If one of your users invokes their right to object to the processing of personal data, you must restrict the processing of their personal data by following the steps mentioned under the "Right to Restriction of Processing" section of this article.
You must erase the personal data of this user by following the steps mentioned under the "Right to Erasure" section of this article.
## Right to Be Informed
### What Is It?
Data subjectshave the right to be informed about what you do with their personal data.
### How to Implement It?
When a user is signing up to use your app or website and before you actually capture their personal data, you must inform them how you are going to use their personal information. You must ask your users before sending them marketing communication such as push notifications, emails, SMS and also inform how you plan to use their personal data if for something else.
MoEngage uses the personal data of your data subjects responsibly and removes it when no longer necessary. You can refer to our [privacy policy](https://www.moengage.com/privacy-policy/) to know more about how we process the data of your end users.
## Opt Out of Campaign Messages
Under the GDPR, you must take consent from your users before sending them Push notifications, SMS, or any other message. If you want to restrict messages for a few users or devices automatically, we recommend the following options:
### Using Preference Management
You can take the push permission from every user and set it as a user property. After this is done, you can exclude the users who have opted out of push notifications from campaign segmentation. For more information, refer to [Preference Management](/docs/user-guide/campaigns-and-channels/mobile-push/getting-started-with-mobile-push/preference-management-for-push-notifications).
### Using SDK Methods for Blocking Push Notifications and In-Apps
The MoEngage SDKs allow you to restrict push notifications and In-App messaging on specific devices. If a user, while signing up on your app does not provide consent for sending push notifications and/or In-App messages, you can restrict these from the SDK directly. Refer to the following SDK documentation for more information on opting out of Push notifications and in-app or On-site messaging.
> [!NOTE]
>
> Opting out of Push notifications and In-App messaging is not supported anymore from Android SDK version 12 and iOS SDK version 8.
#### Android:
* [Opt-out of Push Notifications](https://www.moengage.com/docs/developer-guide/android-sdk/compliance/compliance)
* [Opt-out of In-App Messaging](https://www.moengage.com/docs/developer-guide/android-sdk/compliance/compliance)
#### iOS:
* [Opt-out of Push Notifications](https://www.moengage.com/docs/developer-guide/ios-sdk/compliance/compliance)
* [Opt-out of In-App Messaging](https://www.moengage.com/docs/developer-guide/ios-sdk/compliance/compliance)
#### Web:
* Opt-out of Push Notifications: By default, Web Push notifications need an explicit opt-in from users. To disable Push notifications for specific browsers, you can leverage the existing browser functionality.
* [Opt-out of On-site Messaging](https://www.moengage.com/docs/developer-guide/web-sdk/onsite-messaging/configure-and-integrate-on-site-messaging)
## Privacy by Design
### Opt Out of Advertising Identifiers
As a part of privacy by design, our SDKs allow you to opt-out of the advertising identifiers if and when required.
For more information on this, refer to our SDK documentation
[Android](/docs/developer-guide/android-sdk/data-tracking/advanced-or-optional/configuring-opt-outs) | [iOS](/docs/developer-guide/ios-sdk/compliance/compliance#idfa-and-idfv-optouts)
### Archival Policies
To protect the privacy of your users, we only save the data of your users until it is absolutely essential. To comply with this, we have certain archival policies in place that allow us to automatically delete data that is no longer necessary.
To know more about our archival policies, refer to [Data Archival Policies](/docs/user-guide/data/key-concepts/data-archival-retention-policy) .
In addition to this, if there are any other queries about GDPR compliance. For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Bring Your Own Key (BYOK) For PII Data Encryption
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/-bring-your-own-key-byok-for-PII-data-encryption
Bring Your Own Key (BYOK) provides direct control over the master encryption key used to protect your Personally Identifiable Information (PII).
# Overview
By default, MoEngage generates and manages the encryption keys used to protect your Personally Identifiable Information (PII). **Bring Your Own Key (BYOK)** provides direct control over the master encryption key. This ensures that no one — including MoEngage — can access your users' PII without involving your key.
> [!NOTE]
>
> **Information**
>
> BYOK is an add-on to [PII Data Encryption](https://www.moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-encryption). It requires manual enablement by the MoEngage team. To get started, contact your Customer Success Manager or [MoEngage Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
MoEngage supports the following variants of BYOK:
| Variant | How it works | Best for |
| :- | :- | :- |
| **Customer-Provided Key** | You generate a 256-bit AES key and share it securely with MoEngage. MoEngage stores it as the master key in MoEngage's own AWS KMS. | Organizations that want key ownership without managing AWS KMS cross-account access. |
| **Cross-Account KMS** | Your master key stays entirely within your own AWS KMS. MoEngage accesses it through a whitelisted IAM role when needed. | Organizations in highly regulated industries (banking, financial services, healthcare) require the key to never leave their own cloud environment. |
Both variants use the same underlying envelope encryption model: your master key protects a short-lived data key, which and turn encrypts the actual PII fields. For most enterprise and regulated customers, **Cross-Account KMS** is the recommended approach because it ensures the master key never leaves your AWS environment.
# How It Works
MoEngage uses envelope encryption, which is the following two-layer model:
* **Data Key:** A temporary AES-256-GCM key that encrypts your actual PII fields (for example, email address or phone number).
* **Master Key:** Your key, used to protect the Data Key. In Cross-Account KMS, this lives in your AWS account. In Customer-Provided Key, MoEngage stores this in MoEngage's AWS KMS.
### Data Ingestion
When user data arrives at MoEngage, the following process occurs:
1. MoEngage retrieves your master key from the appropriate KMS (AWS or MoEngage).
2. The system generates a Data Key and encrypts the PII fields by using AES-256-GCM.
3. MoEngage stores the encrypted PII and the encrypted Data Key together in the database.
4. The system immediately discards the plaintext Data Key; it is never persisted.
The system caches the Data Key in memory for up to **30 minutes** for performance, after which it must fetch it from KMS again.
### Campaign Dispatch
When MoEngage sends a campaign that uses a PII field, the following process occurs:
1. MoEngage retrieves the encrypted PII and the encrypted Data Key from storage.
2. MoEngage calls your master key (via KMS) to decrypt the Data Key.
3. The Data Key decrypts the PII in memory only for the duration of message delivery.
4. The system discards both the decrypted PII and Data Key immediately after sending the message.
> [!WARNING]
>
> **Critical**
>
> MoEngage does not store, log, or have persistent access to your master key or your users' plaintext PII outside of the in-memory campaign execution context.
# Prerequisites
> [!NOTE]
>
> **Prerequisites**
>
> Before you get started, ensure you meet the following requirements:
>
> * Enable [**PII Data Encryption**](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-encryption) for your workspace.
> * Provide written acknowledgment that you cannot disable encryption once enabled and that historical data is not retroactively encrypted.
> * For **Customer-Provided Key**: Prepare a 256-bit AES key encoded as a base64 string (exactly 32 bytes).
> * For **Cross-Account KMS**, ensure you have:
> * An active AWS account with access to AWS Key Management Service (KMS).
> * Permission to create and manage Customer Managed Keys (CMK).
> * A key configured as Symmetric, Encrypt/Decrypt usage, Origin: AWS_KMS, Multi-Region: Disabled, and State: Enabled.
# Setting Up BYOK
To set up BYOK, follow the instructions for your chosen variant below.
> [tab] Option A: Customer-Provided Key
>
> ## Option A: Customer-Provided Key
>
> **Step 1: Generate your key.** To generate a 256-bit AES key encoded as a base64 string, use a tool such as OpenSSL. The key must represent exactly 32 bytes, as shown in the following example:
>
> > [tab] OpenSSL
> >
> > ```bash theme={null}
> > openssl rand -base64 32
> > ```
>
> **Step 2: Share your key securely.** To share your key with MoEngage, follow these steps:
>
> 1. Raise a request with [MoEngage Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).
> 2. MoEngage SecOps will provide a secure upload link (via Tresorit).
> 3. Alternatively, request MoEngage's public key to share an encrypted version of your master key.
>
> **Step 3: MoEngage registration.** MoEngage stores your key in its AWS KMS and registers your workspace. You will be notified once the process is complete.
> [tab] Option B: Cross-Account KMS
>
> ## Option B: Cross-Account KMS
>
> **Step 1: Create a CMK in AWS KMS.** To create your master key, follow these steps:
>
> 1. Sign in to the AWS Management Console and navigate to **Key Management Service (KMS)**.
> 2. Click **Create key**.
> 3. Select the **Symmetric** key type and the **Encrypt and decrypt** key usage.
> 4. Record your **Key ARN** once the wizard is complete.
>
> **Step 2: Whitelist MoEngage's IAM Role.** To allow MoEngage to access your key, add the following statement to your KMS key policy. Replace `` with the value from the table provided below.
>
> > [tab] JSON Policy
> >
> > ```json theme={null}
> > {
> > "Sid": "Allow MoEngage to access the key",
> > "Effect": "Allow",
> > "Principal": {
> > "AWS": ""
> > },
> > "Action": [
> > "kms:Decrypt",
> > "kms:ReEncrypt*",
> > "kms:GenerateDataKey*",
> > "kms:DescribeKey"
> > ],
> > "Resource": ""
> > }
> > ```
>
> Use the ARN corresponding to your specific MoEngage Data Center:
>
> | Data Center | Region | MoEngage IAM Role ARN |
> | :- | :- | :- |
> | DC01 | US East (N. Virginia) | `arn:aws:iam::612427630422:role/prod-us-east-1-c2-us-east-1-eks-worker-role` |
> | DC02 | EU (Frankfurt) | `arn:aws:iam::612427630422:role/prod-eu-central-1-c2-eu-central-1-eks-worker-role` |
> | DC03 | AP South (Mumbai) | `arn:aws:iam::612427630422:role/prod-ap-south-1-c1-ap-south-1-eks-worker-role` |
> | DC04 | US East (Ohio) | `arn:aws:iam::612427630422:role/prod-us-east-2-c2-us-east-2-eks-worker-role` |
> | DC05 | AP Southeast (Singapore) | `arn:aws:iam::163129101105:role/prod-ap-southeast-1-c2-ap-southeast-1-eks-worker-role` |
> | DC06 | AP Southeast (Jakarta) | `arn:aws:iam::163129101105:role/prod-ap-southeast-3-dc06-ap-southeast-3-eks-worker-role` |
>
> **Step 3: Share Your Key ARN.** Raise a request with [MoEngage Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard) and provide your KMS Key ARN to finish registration.
# Enable PII Encryption from the MoEngage UI
To enable encryption for your attributes, perform the following steps:
1. On the sidebar menu in MoEngage, hover over the Settings menu item  . The **Settings Home** menu appears.
2. Click **Data management**. 
3. Click the **User attributes** or **Event** tab. 
4. Locate the attribute, click the **ellipsis (⋯)** icon, and select **Edit attribute**.
5. Turn on the **Encrypt attribute** toggle. This automatically enables the **Mask attribute** toggle on.
6. Click **Save and Continue**.
> [!WARNING]
>
> **Warning**
>
> After encryption is enabled for an attribute, it cannot be disabled. MoEngage only encrypts data ingested after enablement; historical data remains unencrypted.
# Key Rotation
Key rotation is a manual process. To rotate your maste[AWS Management Console](https://aws.amazon.com/console/)r key, raise a request with [MoEngage Support](/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard) and provide your new key or ARN. MoEngage will re-encrypt all stored Data Keys by using the new master key.
# BYOK vs. MoEngage-Managed Keys
The following table compares the features of the available variants:
| Feature | MoEngage-Managed | Customer-Provided | Cross-Account KMS |
| :- | :- | :- | :- |
| **Key storage** | MoEngage AWS KMS | MoEngage AWS KMS | Your AWS KMS |
| **Audit trail** | Internal | Internal | AWS CloudTrail |
| **Revocation** | Not applicable | Not directly | Yes, via policy |
# Limitations
The BYOK feature has the following limitations:
* AWS KMS is the only supported provider; Google Cloud KMS and Azure Key Vault are not currently supported.
* Automated AWS KMS rotation schedules are not yet supported; rotation is a manual process.
* Applies to field-level encryption only; disk-level and database-level encryption are managed separately.
* BYOK is a workspace-wide setting; you cannot mix BYOK and MoEngage-managed keys in one workspace.
# Frequently Asked Questions
> [accordion] Does MoEngage store my master key (Cross-Account KMS)?
>
> No. Your master key never leaves your AWS account.
> [accordion] What happens if I revoke access?
>
> MoEngage will be unable to decrypt PII once the cache expires (30 minutes).
> [accordion] What encryption algorithm is used?
>
> MoEngage uses AES-256-GCM.
# Personal Data or Personally Identifiable Information (PII)
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/personal-data-or-personally-identifiable-information-pii
What counts as PII or personal data? Understand identifiable information types and how organizations should handle sensitive user data in MoEngage.
# What is Personal Data or PII?
**PII** or **Personally Identifiable Information** is any data that relates to an identified or identifiable natural person.
An identifiable natural person is one who can be identified, directly or indirectly, in particular by reference to an identifier such as a name, an identification number, location data, an online identifier, or to one or more factors specific to the physical, physiological, genetic, mental, economic, cultural or social identity of that natural person. Examples of personal data include name, residential address, date of birth, IP address, etc.
Organizations can use PII to identify, contact, or locate a user or person of interest as per the agreed business purpose. Any operation or set of operations that are performed on personal data or on sets of personal data, such as collection, recording, organization, structuring, storage, adaptation or alteration, retrieval, consultation, use, disclosure by transmission, dissemination or otherwise making available, alignment or combination, restriction, erasure or destruction is called as ‘Processing of Personal data’.
The **Data Controller** is the entity that decides the means and ways to process personal data. MoEngage acts as a Data Controller when it processes its employee data as the employer decides the means and purpose of processing.
The **Data Processor** is the entity that processes personal data on behalf of the Data controller. MoEngage acts as a Data Processor when it assists our customers in processing personal data of their end users as a part of providing services for use cases decided by the Data Controller (Our Customers).
While certain personal data fields like zip code, date of birth, gender, and passwords may not independently identify an individual, they become PII when combined with other personal data fields that, collectively, can uniquely identify a living person.
# Safeguarding PII at MoEngage
MoEngage provides three options for safeguarding PII data. These options cater to different business and operational requirements. You can select the most suitable approach for your needs: Data Masking, Data Encryption, and/or tokenization.
## Sending PII to MoEngage
If you choose to send PII to MoEngage, you can utilize the following functionalities to safeguard the data:
* **PII Masking**\
MoEngage allows you to designate specific attributes as PII and mask them to ensure security. Only administrators have access to view and download this data. For more information, see [PII Masking](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
* **PII Data Encryption**\
MoEngage provides the capability to encrypt PII data stored within its systems. Any user or event properties marked as PII can be encrypted. By default, encrypted attributes also have masking enabled. These attributes are not visible or downloadable from the MoEngage dashboard. For more information, see [PII Data Encryption](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-encryption).
## Not Sending PII to MoEngage
If you decide not to send PII to MoEngage, you can leverage the following functionality to enable your workflows:
* **PII Tokenized Sending**To ensure complete user anonymity, MoEngage supports tokenized sending. This approach fetches PII data at runtime, eliminating the need to store it within MoEngage. For more information, see [PII Tokenized Sending](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-tokenized-sending).
# PII Data Centers
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-centers
Store PII within specific regions using MoEngage dedicated data centers. Meet data residency and localization requirements for privacy compliance.
MoEngage is committed to providing you with robust solutions for data privacy and compliance. To support your data residency and localization needs, MoEngage offers Personally Identifiable Information (PII) Data Centers (DCs) where MoEngage doesn't have its primary data center.
## What is a PII Data Center?
A PII DC is a specialized, physically isolated DC designed to store and process Personally Identifiable Information (PII) within a specific geographical region. This ensures that your customers' sensitive data remains within their country's borders, which helps you comply with local data residency and privacy regulations. PII DCs come into play only when there is no main DC already present in your region. For the main DCs list, please refer to this [article](/docs/user-guide/data/key-concepts/data-centers-in-moengage).
PII DCs act as intermediaries between your systems and the main DCs of MoEngage. While the main DCs store and process non-PII data, the designated PII DC securely handles all PII.
## Key Features
| Feature | Description |
| - | - |
| Data Residency | Guarantees that all PII data is stored and processed within the specified country's borders, ensuring compliance with local regulations. |
| Secure PII Handling | Implements robust security measures, including encryption at rest and in transit, to protect all PII data. |
| Seamless Integration | Integrates with the main DCs of MoEngage with minimal disruption, allowing for smooth campaign orchestration and execution. |
| Real-time Processing | Maintains low latency and real-time processing capabilities for timely and efficient customer engagement. |
| Scalability | Designed for easy expansion to other regions, providing a flexible solution for your growing business needs. |
## Data Ingestion
You can send PII data to the PII DC and non-PII data to the MoEngage main DC. The customer number is a must to send PII data, as it is used to find a particular customer's email address or phone number.

## Message Sending
All communications are initiated from the main DC of MoEngage, where segmentation is first performed to identify the users to whom the communication needs to be sent. After a user is identified for communication, the communication message is constructed and will be sent to PII DC, as the main DC will not have an email address, mobile number, or any other PII. The communication message and the customer number are sent to PII DC.
With the customer number, the PII DC can identify the actual email address or mobile number, and along with the communication message, it can now request the providers to send the message.

## Available PII DCs
You can choose the DC that best aligns with your geographical and regulatory requirements from the following options:
| Data Center Code | Provider | Location |
| - | - | - |
| PII DC01 | AWS | UAE |
| PII DC02 | GCP | Qatar |
| PII DC03 | GCP | Saudi Arabia |
## Integration and Configuration
To get started with the PII DCs of MoEngage, you must configure your data ingestion process to point to the correct regional endpoint.
### Data Ingestion Endpoint
The URL for data ingestion into a PII DC is:
Method: **POST**
```json API Endpoint theme={null}
https://pii-dc0X.moengage.com/v1/transition/
```
**Note:**
* Replace X in pii-dc0X with the number of your designated PII DC (for example, 1 for AWS UAE).
* Replace `` with your specific MoEngage Workspace ID.
For more information on working with the Bulk Import API, refer to the [Bulk Import](https://www.moengage.com/docs/api/bulk/bulk-import-users-and-events) API documentation.
## Frequently Asked Questions (FAQs)
This section addresses common questions and potential issues to ensure a smooth integration.
### General and Security
> [accordion] How is my data secure in a PII DC?
>
> MoEngage PII DCs adhere to the same high-security standards as its main DCs, which are ISO certified and SOC2 Type 2 compliant. The PII is encrypted at rest and also in transit for internal communication.
> [accordion] How do I request a PII DC for my account?
>
> MoEngage solution architects will contact you for a PII DC setup while you are onboarded to MoEngage. PII DC is only suitable for you if there isn't already a main DC present in your region.
> [accordion] Is there an additional cost for using a PII DC?
>
> Contact your dedicated MoEngage account manager or sales team for details on pricing and commercial terms for PII DCs.
### Integration and Data Management
> [accordion] Can I send PII via file uploads?
>
> No, MoEngage only accepts PII into the PII DCs through the data APIs.
> [accordion] Is there a limit on the number of PII attributes I can send?
>
> Yes, you can send a maximum of 20 PII attributes to the MoEngage PII DC.
> [accordion] What format should I use for mobile numbers?
>
> Mobile numbers sent through the data APIs should be in the E.164 format.
> [accordion] Is the personalization of content possible with PII DCs?
>
> No, personalization is not supported in the first phase of the PII DC release.
> [accordion] What happens if I accidentally send PII to the standard MoEngage endpoint?
>
> The data will be processed in the main DC of MoEngage, not the PII DC. It is critical to ensure all PII is routed only through the correct PII DC endpoint to meet data residency requirements.
> [accordion] What are the common errors I might encounter during integration?
>
> Common errors include using an incorrect Workspace ID, a malformed API endpoint URL, or authentication issues. An HTTP 4xx error code usually indicates a client-side problem with your request.
> [accordion] What is the RPM for data ingestion?
>
> PII DC supports 1K RPM for data ingestion.
# PII Data Encryption
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-encryption
Encrypt user and event properties marked as PII in MoEngage. Encrypted data is automatically masked and hidden from workspace users on the dashboard.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
MoEngage allows the encryption of user properties and event properties marked as Personally Identifiable Information (PII). Any attribute with data encryption also has masking enabled by default. These attributes do not appear on the MoEngage UI, and other users within your workspace (such as marketers, managers, analysts, and developers) cannot download them.
## Encryption Key Management
When you enable PII encryption, you can choose how your encryption keys are managed:
* **MoEngage-Managed Keys (Default):** MoEngage generates and manages the encryption keys used to protect your data.
* **Bring Your Own Key (BYOK):** Provides direct control over the master encryption key using your own AWS KMS. For more information, refer to [Bring Your Own Key (BYOK) for PII Data Encryption](https://www.moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/-bring-your-own-key-byok-for-PII-data-encryption).
# Enable PII Data Encryption
You can enable data encryption for all user and event properties, except for a list of reserved, non-encryptable attributes. For more information, refer to the [list of reserved attributes for which data encryption is not supported](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-data-encryption#list-of-attributes-not-supported-for-encryption).
> [!NOTE]
>
> * To enable PII encryption, contact your MoEngage Customer Success Manager (CSM) or the Support team.
> * Make sure you mark the attribute as "encrypted" using test values before sending the majority of the data, or the actual data. It is important to note that any data received after the attribute is marked as encrypted will itself be encrypted during storage, while the data received before it will remain unchanged.
> * Attributes marked as encrypted once cannot be decrypted or unmasked.
> * Users with Admin roles can see the attributes in their encrypted form. However, users with other roles cannot view or download them, as these attributes are not displayed on the User Profile, Reporting, Analytics, and Segmentation pages.
> * After encryption is enabled, it may take up to 15 minutes for the new settings to reflect.
> * You can export an encrypted attribute in reports only if you have admin access. The attribute is exported in its encrypted format. Decrypted data cannot be exported from the MoEngage dashboard.
# Encrypt the User Properties
Perform the following steps to encrypt user properties:

1. On the left navigation menu of the MoEngage dashboard, click **Settings** > **Data management**.
2. On the **Data management** page, click the **User attributes** tab.
3. Search for the desired user property and click the ellipsis icon against that attribute.
4. Click **Edit attribute**.
5. On the **Edit attribute details** side drawer, turn on the **Encrypt attribute** toggle. This toggle automatically enables the **Mask attribute** toggle, which means that when you encrypt a user property, MoEngage automatically masks that attribute as well.
6. Click **Save** and **Continue**.
# Encrypt the Event Properties

1. On the left navigation menu of the MoEngage dashboard, click **Settings** > **Data management**.
2. On the **Data management** page, click the **Event properties** tab.
3. Search for the desired event property and click the ellipsis icon against that attribute.
4. Click **Edit attribute**.
5. On the **Edit attribute details** side drawer, turn on the **Encrypt attribute** toggle. Turning on this toggle automatically enables the **Mask attribute** toggle, which means that when you encrypt a user property, MoEngage automatically masks that attribute as well.
6. Click **Save** and **Continue**.
# View Encrypted User and Event Properties
After you encrypt user or event properties, users in your workspace can view them on the following pages, tabs, and dialog boxes of the MoEngage UI, depending on their assigned roles and permissions. If they have the permission to view these attributes, they can see the encrypted values of the attributes. Otherwise, these appear as **Private** and **---** (masked).
## User Search Box
You can view encrypted user or event properties on the Create Segment page. Search for a user in the **Search user by ID, Email, Mobile No, or MoEngage ID** search box.
Accessibility to encrypted attributes depends on your assigned role. If you have the permission to view these attributes, you can see the encrypted values of the attributes. Otherwise, these appear as **Private** or **---** (masked).

## User Profile Page
You can view the encrypted attributes on the **User info** and **Activity info** tabs of the User Profile page.
### User Info Tab
Perform the following steps to view the encrypted attributes on the **User Info** tab:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results**.
2. On the **Sample users** section, select the desired user to view their user profile.
3. On the **User Profile**, click the **User info** tab, and then click **User Properties**.
You can also access the **User info** tab using the **Search user by ID, Email, Mobile No, or MoEngage ID** search box on the **Create Segment** page. Search for the user in the search box and click the name of the desired user, go to the **User info** tab, and then click **User Properties**.\
Accessibility to the encrypted attribute depends on your assigned role. If you have the permission to view these attributes, you can see the encrypted values of the attributes. Otherwise, these appear as **Private**.

### Activity Info Tab
Perform the following steps to view the encrypted attributes on the **Activity Info** tab:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results**.
2. On the **Sample users** section, select the desired user to view their user profile.
3. On the **User Profile**, click the **Activity info** tab.
You can also access the **Activity info** tab using the **Search user by ID, Email, Mobile No, or MoEngage ID** search box on the **Create Segment** page. Search for the user in the search box, click the name of the desired user, and then go to the **Activity info** tab.
Accessibility to encrypted attributes depends on your assigned role. If you have the permission to view these attributes, you can see the encrypted values of the attributes. Otherwise, these appear as **Private**.

## Test Users
You can view the list of test users and their masked PII by navigating to **Test & Debug** > **Test users** from the left navigation menu of the MoEngage UI. Accessibility to encrypted attributes depends on your assigned role. If you have the permission to view these attributes, you can see the encrypted values of the attributes. Otherwise, these appear as **Private** and **---** (masked).

## Value Suggestions
Visibility of encrypted [value suggestions](/docs/user-guide/segment/advanced-concepts/value-suggestions) on the Segmentation and Analytics page depends on your role. For roles lacking encryption access, these suggestions are disabled. However, roles with encryption permissions can see the encrypted values behind the encrypted suggestions.
## Segmentation Filters
### Create Segment
When creating segments, MoEngage supports filtering PII encrypted attributes using only two operators: *exists* and *does not exist*.

### Create Campaign
When creating campaigns, MoEngage supports filtering PII encrypted attributes using only two operators: *exists* and *does not exist*.

# Supported Channels
| Channel Name | Support for Sending (decrypting encrypted Sender ID before sending) | Support for Personalization Preview (in encrypted format) | Support for Personalization (when an encrypted User Properties is used in personalization) |
| - | - | - | - |
| Email | Yes | Yes | Yes |
| Push | Not applicable | Yes | Yes |
| SMS | Yes | Yes | Yes |
| WhatsApp | Yes | Yes | Yes |
| Facebook Audience | Not built | Not applicable | Not applicable |
| Google Ads | Not built | Not applicable | Not applicable |
| Connectors | Not applicable | Not applicable | Yes |
| In-app Messaging | Not applicable | Yes | Yes |
| On-site Messaging | Not applicable | Not applicable | Yes |
| Cards | Not applicable | Not applicable | Yes |
# Non-Dashboard Functionality
PII-encrypted data is available for Open Analytics, S3 Exports, and MoEngage Streams, and data is not decrypted before use/export. These features are not available by default, require manual enablement, and will be enabled on request. You can provide your team access to these features per your security and data needs.
# List of Attributes Not Supported for Encryption
### User Properties
* Reachability Push Android (moe_rsp_android)
* Reachability Push iOS (moe_rsp_ios)
* Reachability Push Web (moe_rsp_web)
* Reachability Push (moe_rsu)
* Spam
* Unsubscribe
* Push Preference Changed iOS
* SMS Subscription Status
* Install Status
* Push Opt In Status (iOS)
* MoEngage ID
* moe_dtzo - User Time Zone offset
* All of Lifecycle category attributes
* All of Uninstall category attributes
### Event Properties
* source
* appVersion
* SDKversion
* Platform
* Parent Campaign Id (moe_c_pid)
* Parent Flow Id (moe_f_pid)
* Parent Flow Name (moe_f_pname)
* Campaign Content Type (moe_campaign_content_type)
* Locale Id (moe_locale_id)
* Locale Name (moe_locale_name)
* Variation Key (moe_variation_id)
* Campaign Tags (moe_campaign_tags)
* BTS (moe_bts_type)
* Control Group (moe_control_group_type)
* Readable Campaign Id (moe_campaign_id)
* Campaign Name (moe_campaign_name)
* Campaign Type (moe_campaign_type)
* Delivery Type (moe_delivery_type)
# FAQs
> [accordion] How is PII Encryption different from PII Masking?
>
> PII masking simply masks the values on the MoEngage dashboard UI and does not encrypt the values during storage.
> [accordion] Can I mask an attribute but not encrypt it?
>
> Yes. For more information, refer to [PII Masking](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
# PII Masking
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking
Mask personally identifiable information in MoEngage to prevent sensitive user data from being displayed or downloaded by workspace team members.
MoEngage protects your end users' Personally Identifiable Information (PII). Admin can mask any user property or event property, regardless of the encryption. Additionally, when Admin encrypts a user property or event property marked as PII, MoEngage automatically masks it for you.
> [!NOTE]
>
> Only admins have the privilege to view unmasked PII data and to export PII attributes on the MoEngage dashboard.
>
> However, if you wish to mask PII data for admins or block PII exports for admins entirely, you will need to contact your MoEngage Customer Success Manager (CSM) or the Support team.
Masking prevents the sensitive data from being directly displayed to other users within your workspace (such as marketers, managers, analysts, and developers) and prevents them from downloading it from the MoEngage UI. This ensures an extra layer of security and privacy for your users' data.
# Mask the User Properties
Perform the following steps to mask user properties:

1. On the left navigation menu of the MoEngage dashboard, click **Settings** > **Data management**.
2. On the **Data management** page, click the **User attributes** tab.
3. Search for the desired user property and click the ellipsis icon against that attribute.
4. Click **Edit attribute**.
5. On the **Edit attribute details** side drawer, turn on the **Mask attribute** toggle to ensure sensitive data is concealed from other users within your workspace.
6. Click **Save**.
# Mask the Event Properties

1. On the left navigation menu of the MoEngage dashboard, click **Settings** > **Data management**.
2. On the **Data management** page, click the **Events** tab.
3. Search for the event and then expand the event to view the event properties under that. Click the ellipsis against that attribute.
4. Click **Edit attribute**.
5. On the **Edit attribute details** side drawer, turn on the **Mask attribute** toggle. Turning on this toggle hides the PII from other users in your workspace.
6. Click **Save** and **Continue**.
# View Masked User and Event Properties
After you mask user or event properties, users in your workspace can view them on the following pages, tabs, and dialog boxes of the MoEngage UI, depending on their assigned roles and permissions.
## User Search Box
You can view masked user or event properties on the Create Segment page. Search for a user in the **Search user by ID, Email, Mobile No, or MoEngage ID** search box.
Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private** on the **Name** column and **---** (masked). 
## Show Users Window
You can view masked user or event properties on the **Showing users after segmentation** page. Perform the following steps to view the **Showing users after segmentation** page:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results.**
2. On the **Sample users** section, click **Show more**.
3. The **Showing users after segmentation** page displays all the users after segmentation.\
Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private** and **---** (masked).

## User Exports Window
You can view masked user or event properties on the **Export users data** dialog box. MoEngage disables masked user properties on the **Export users data** dialog box based on your role. This means if masking is not accessible for your role, you cannot export masked attributes using the **Export users** option on the **Create Segment** page.

## User Profile Page
You can view masked user or event properties on the User Profile page. Perform the following steps to view the masked attributes on the User Profile page:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results**.
2. On the **Sample users** section, select the desired user to view their user profile.\
Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private**.
You can also access the User Profile page using the **Search user by ID, Email, Mobile No, or MoEngage ID** search box on the **Create Segment** page. Search for the user in the search box and click the name of the desired user.

## User Info Tab
Perform the following steps to view the masked attributes on the **User Info** tab:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results**.
2. On the **Sample users** section, select the desired user to view their user profile.
3. On the **User Profile**, click the **User info** tab, and then click **User Properties**.\
Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private**.

## Activity Info Tab
Perform the following steps to view the masked attributes on the **Activity Info** tab:
1. Click **Show count** while creating a segment on the **Create Segment** page, and expand the **Query results**.
2. On the **Sample users** section, select the desired user to view their user profile.
3. On the **User Profile**, click the **Activity info** tab.\
Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private**.

## Value Suggestions
Visibility of masked value suggestions on the Segmentation and Analytics page depends on your role.\
These suggestions are disabled for roles without masking access. However, roles with masking permissions can see the real values behind the masked suggestions.
## Split by or Group by User Property in Analytics Pages
On [Behavior](/docs/user-guide/analyze/analytics/behavior), [Funnel](/docs/user-guide/analyze/analytics/funnels), and [Retention](/docs/user-guide/analyze/analytics/retention) pages of **Analyze**, when you select the attributes for the **Split by** or **Group by user property** functionalities, attribute visibility depends on your role. If masking is not accessible for your role, masked attributes are disabled. If accessible, you can view the actual values of the masked attributes.

## Test Users
You can view the list of test users and their masked PII by navigating to **Test & Debug** > **Test users** from the left navigation menu of the MoEngage UI. Accessibility to masked attributes depends on your assigned role. If you have the permission to view these attributes, you can see the real values of masked attributes. Otherwise, these appear as **Private** and **---** (masked). 
## Personalization Preview
All the masked user properties are shown as ***XXXXXXXXXX***on the personalization preview in the campaign creation pages. The following image displays the preview of masked PII attributes during the SMS campaign creation. For more information, refer to [PII Masking on Personalised Preview](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking-on-personalised-preview).

# Non-Dashboard Functionality
Features outside the MoEngage UI do not support PII masking. Hence, PII masking is not available for [Open Analytics](/docs/user-guide/analyze/custom-analysis/open-analytics), [S3 Exports](/docs/user-guide/data/exports/events/data-warehouse/s3-exports), and [MoEngage Streams](https://www.moengage.com/docs/api/data/moengage-streams).
These features are not available by default, require manual enablement, and are enabled on request. You can provide your team with access to these features as per your security and data needs.
# PII Masking on Personalised Preview
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking-on-personalised-preview
Protect sensitive data in campaign previews with PII masking. Validate personalization content without exposing user information on the MoEngage UI.
# Overview
The *PII masking* feature enables organizations to protect sensitive information by masking personally identifiable information (PII) fields in campaign previews. This ensures that PII data, such as user and event properties, are not exposed on the UI, aligning with privacy standards.
You can use the Personalized Preview feature to validate content and test personalization without compromising customer data privacy. Fields marked as PII within the data management or Content API are masked, typically displayed as “XXXX” on the UI, while non-PII fields remain visible in plain text.
This feature enhances data privacy, prevents unauthorized PII exposure, and supports secure campaign testing.
> [!NOTE]
>
> This feature is applicable to all channels that support personalization preview.
# Use Cases
Following are some of the use cases for the PII masking feature:
* If you want to test personalization in a campaign preview, PII masking hides sensitive information while displaying non-PII fields in plain text. This allows accurate content validation without revealing PII data.
* If you need to fetch data from the Content API for campaign content, any fields marked as PII are automatically masked, preventing unauthorized access in UI previews and maintaining data privacy.
* If certain roles do not have permission to view PII, PII masking enforces privacy by masking PII fields in the personalized preview, ensuring that only authorized roles can access sensitive information.
* If you need to use the Personalized Preview to check rendering of content, PII masking safeguards customer data by masking sensitive information while allowing non-PII details to appear in plain text. This supports effective preview and testing without privacy risks.
# Masked Attributes in Personalization Content
The PII masking feature ensures that user properties, such as mobile number and last name, are visible only to administrators. For all other users, these attributes are displayed as “private.”

With this feature, you can mask PII fields in the user profile as well as in the personalized content.
 With this update, any user or event property marked for masking also appears masked in personalization content. This applies to all channels that support personalization preview, ensuring masked values are consistently protected across the platform.
# Masked Attributes in Content API
When adding a content API, you may receive PII in the response. This feature allows you to mask specific values in the API response to prevent unauthorized access to PII.
To do the same, perform the following steps:
1. On the \*\*Content API \*\*page, under the **Actions** column, click the ellipsis icon and then select **Edit**. For more information on creating personalized campaigns using content APIs, refer to [Content APIs](/docs/user-guide/campaigns-and-channels/getting-started/campaign-content/content-apis).

2. On the \*\*Edit Content API \*\*page, click **Yes** under **Mask PII fields**. 
3. In the Select fields to mask list, select the fields you want to mask. For example, in the following image, we have selected coord. lon, coord.lat, and click **Done**.

4. Upon using this content API for personalizing content, the values of the selected fields in the previous step are masked.

> [!NOTE]
>
> Field values are masked as "xxx." Any operations using these fields also use the "xxx" value, not the original value fetched from the user profile.
# PII Tokenized Sending
Source: https://moengage.com/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-tokenized-sending
Run campaigns without storing PII in MoEngage using tokenized sending. Replace sensitive contact details with anonymous tokens for GDPR compliance.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
PII Tokenized Sending is a patented MoEngage feature that allows you to engage with your customers without storing their Personally Identifiable Information (PII) within the MoEngage platform.
PII data includes:
* **Customer contact details:** Email ID, mobile number.
* **Customer personalization information:** First name, last name.
Tokenization replaces this sensitive data with non-sensitive, anonymous tokens. This feature enables you to segment, personalize, and run campaigns while MoEngage remains fully compliant with data privacy regulations like GDPR.
For more information about MoEngage's data privacy compliance, refer to [GDPR Compliance](/docs/user-guide/data/privacy/gdpr) and [PII Masking](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
# Use Cases
* **Enhance Data Security:** Engage your audience through targeted campaigns without storing sensitive PII, such as email addresses or phone numbers, in MoEngage.
* **Ensure Compliance:** Meet stringent data privacy regulations by anonymizing customer identities in your marketing platform.
* **Maintain Personalization:** Continue to use personalization in your campaigns by fetching data in real-time.
> [!TIP]
>
> **Prerequisites**
>
> Before you configure this feature, ensure you have the following:
>
> * **PII API Endpoint**: An API endpoint on your server that can receive an anonymous ID from MoEngage and return the corresponding PII (email or mobile number).
> * **Anonymous ID**: A unique, anonymized customer identifier maintained in your database that serves as the common key between your system and MoEngage.
# Configuration
You can configure a PII API to retrieve customer email IDs or mobile numbers during campaign dispatch.
> [!NOTE]
>
> * PII Tokenized Sending is supported for the following channels and partners:
> * SMS, MMS, and RCS (All the native and custom SMS connectors or service providers)
> * Email (SendGrid, Amazon SES, and custom SMTP connectors)
> * WhatsApp (All the native and custom WhatsApp connectors)
> * MoEngage uses dynamic IPs for sending messages, if you want to use static IPs refer to [this](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage) doc to know more.
> * When PII Tokenized Sending is enabled, the following are not supported:
> * Opt-out Management (WhatsApp)
> * Subscription Management (SMS, MMS)
> * RCS
> * Message Archival
## 1. Configure PII API
> [tab] Email Settings
>
> To send email campaigns without storing customer email addresses in MoEngage, configure the following settings.
>
> 1. On the MoEngage dashboard, navigate to **Settings > Channels > Email**.
> 2. Select the **Data** tab.
> 3. In the **Customer's email address data** field, select the option **Customer's email addresses are not stored in MoEngage DB (Fetch via API)**.
> 4. After you select this option, the API configuration fields appear. Proceed to the next step to configure the API settings.
> [tab] SMS, MMS & RCS Settings
>
> To send SMS, MMS and RCS campaigns without storing customer mobile numbers in MoEngage, configure the following settings.
>
> 1. Navigate to **Settings** > **Channels** > **SMS, MMS & RCS.**
> 2. Select the **PII tokenization** tab.
> 3. Click **+Add API Configuration**.
> 4. The API configuration fields appear. Proceed to the next step to configure the API settings.
> [tab] WhatsApp Settings
>
> To send WhatsApp campaigns without storing customer mobile numbers in MoEngage, configure the following settings.
>
> 1. On the MoEngage dashboard, navigate to **Settings > Channels > WhatsApp**.
> 2. Select the **Data** tab.
> 3. In the **Customer's mobile numbers data** field, select the option **Customer's mobile numbers are not stored in MoEngage DB (Fetch via API)**.
> 4. After you select this option, the API configuration fields appear. Proceed to the next step to configure the API settings.
## 2. API Settings
You can fetch data for users individually or in batches.
> [tab] Single
>
> By selecting single, you can fetch a response based on each request. This helps you fetch particular responses instead of huge data sets.
>
> Perform the following steps:
>
> * **Method:** Select the GET or POST method.
>
> * **OAuth 2.0 Authentication**: To secure your PII API with OAuth 2.0, enable the **OAuth** toggle. A dropdown menu appears. Select a pre-configured OAuth setting. To learn how to create and manage OAuth settings, refer to [Authorization Configuration with OAuth 2.0](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20).
>
> > [!NOTE]
> >
> > * The OAuth option will be enabled on request. Contact your CSM or the MoEngage Support team to enable it.
> > * Only OAuth configurations with an "Active" status will be available for selection in the dropdown.
> > * If an active OAuth configuration used by your API expires, its status will change to "Failed". When you edit the PII settings, an error message will be displayed, and you will need to select a new, active OAuth configuration.
>
> * **Request URL:** Type or paste the "Request URL" of the API.
> * **Parameters:** Type or paste the relevant "URL parameters", "Headers", and/or "Body" details for the API as key-value pairs. You can personalize the URL parameters and request headers by typing @ in the placeholders while entering the key-value pairs. \\
>
> 
> [tab] Bulk
>
> By selecting bulk, you can fetch a maximum of 500 user properties in a single request, significantly reducing the number of requests made to collect each customer data individually.
>
> 
>
> 1. Enter the batch size of your request.
> 2. **API configuration**
> * **Method:** Only the POST method is supported in bulk.
>
> * **Enable OAuth** : To secure your PII API with OAuth 2.0, enable the OAuth toggle. A dropdown menu appears. Select a pre-configured OAuth setting. To learn how to create and manage OAuth settings, refer to [Authorization Configuration with OAuth 2.0](/docs/user-guide/settings/advanced-settings/authorization-configuration-with-oauth-20).
>
> > [!NOTE]
> >
> > * The OAuth option will be enabled on request. Contact your CSM or the MoEngage Support team to enable it.
> > * Only OAuth configurations with an "Active" status will be available for selection in the dropdown.
> > * If an active OAuth configuration used by your API expires, its status will change to "Failed". When you edit the PII settings, an error message will be displayed, and you will need to select a new, active OAuth configuration.
>
> * **Request URL:** Type or paste the "Request URL" of the API.
>
> * **Parameters:** Type or paste the relevant "URL parameters," "Headers," and/or "Body" details for the API as the key-value pairs.
> > [!NOTE]
> >
> > You cannot personalize the URL path parameters and headers in bulk requests. You can only personalize user properties in the request body with the key-value pairs as follows: Customer hash: `{{UserAttribute['ID']}}` value, which is mandatory in input, and the same key will be returned in the output.
>
> 2. **Sample Request:** Your request will be processed in the backend, as shown below:
> ```json JSON theme={null}
> {
> "abcd": "abcd",
> "CustomerInBulk": [
> {
> "Customer hash": "{{UserAttribute['ID']}}"
> }
> ]
> }
> ```
> 3. Customer hash is a key, and 456 `{{UserAttribute['ID']}}` is the value. You can have different key-value pairs, for example: Customer key and Customer ID.\
> **Sample Response:** You will receive a response from the backend, as shown below:
> ```json JSON theme={null}
> {
> “CustomerInBulk”: {
> {
> Customer hash: “456”,
> First name: “John”,
> Last name: “doe”,
> Email ID: “xyz@abc.com”
> Phone number: “9876543210”
> },
> {
> Customer hash: “567”,
> First name: “Joe”,
> Last name: “Bloggs”,
> Email ID: “ioh@abc.com”
> Phone number: “1234567890”
> }
> },
> }
> ```
> The data will be returned with the same key (user property) you requested.
> > [!NOTE]
> >
> > You can have multiple key sets but can make a personalized request based on user properties from only one key set.
## 3. Test and Save Configuration
After defining your API settings, you must test the configuration to ensure MoEngage can correctly retrieve the data.
1. Enter a valid test value for the anonymous ID you configured (for example, `456`).
2. Click **Test** to trigger the API call.
3. Review the API response to ensure it is successful and returns the correct data.
4. In the **Email/Mobile Number field in API response** list, select the response key that contains the customer's email or mobile number (for example, `Email_ID`).
5. Click **Save** to finalize the configuration. 
# PII-Based Campaign Workflow
The following diagram illustrates the data flow when sending a campaign with PII Tokenized Sending enabled.

1. A campaign is triggered in MoEngage.
2. MoEngage calls your configured PII API, passing the anonymous IDs of the eligible users.
3. Your API retrieves and returns the corresponding email address or mobile number for each anonymous ID.
4. MoEngage sends the campaign content and the fetched PII to your configured Email, SMS, RCS, or WhatsApp service provider.
5. **MoEngage immediately deletes the fetched PII** (email, mobile number, and any other data fetched via Content APIs for that campaign) after sending it to the provider.
6. The service provider delivers the message to the end customer.
7. The service provider sends delivery status data back to MoEngage.
8. MoEngage maps the delivery data back to the campaign using a unique message ID and deletes any PII that may have been returned in the delivery receipt.
9. Campaign analytics are updated on the MoEngage dashboard.
# Anonymization Support
Here are a few other changes implemented to support customer anonymity in the MoEngage platform.
* **Campaign Sending Logs**- If Tokenized Sending has been configured for a specific channel, the campaign logs will stop storing email or mobile number data (depending on the channel for which PII Tokenized Sending is configured) from the next instance of the campaign run (post the configuration change).
* **Campaign Delivery data**- MoEngage tracks delivery data for all the native connectors and maps the delivery data back to a campaign using the message ID field.
> [!NOTE]
>
> Delivery information is not tracked for custom (SMS, MMS, RCS, and Email) connectors.
* **Segmentation** - The 'show count' query lists the user count as part of both Segmentation from the **Segment** > **Create Segment** navigation and Segmentation in campaigns. However, the reachable user count cannot be shown in both cases as MoEngage does not store the mobile number or email address (which is the basis for calculating reachability).
* **Current campaigns (live campaigns)** - If there are any live campaigns for that channel (point channel or flows) when the PII API settings are configured, sending will be done by fetching the Email ID or Mobile number from the very next instance.
* **Personalized Preview** - This feature is automatically disabled for the channel after PII settings are saved. You can request to re-enable it by contacting your Customer Success Manager (CSM).
* **Campaign Testing Failure** **Reason**- When testing a campaign when it is being created (for the channel where PII configuration is set), if the API fails to respond, the API error will be shown in the UI.
* **Campaign Analytics** - The customers for whom the PII API configured above fails to retrieve the customer sending ID (Email ID or mobile number) will not be counted in the *Campaign delivery stats* in the Campaign Info or Analytics section. This is because this funnel accounts for users with a valid Email ID or Mobile number.
* **Content Personalization when customer data is not available in MoEngage** - While the PII API above focuses on retrieving the customer's sending ID (Email ID or Mobile number), MoEngage's Content API feature allows you to fetch any data (PII and/or other) directly from your database in real-time when the campaign is about to be sent to the end customer. For more information, refer to [Personalization using Content APIs](/docs/user-guide/campaigns-and-channels/getting-started/message-personalization/personalize-content-using-content-apis).
# Frequently Asked Questions (FAQ)
> [accordion] Do I need a tokenization server to create an anonymous ID?
>
> No. You only need to ensure a unique, non-PII customer identifier exists in your database that you can map to users in MoEngage.
> [accordion] Can Content API and PII Tokenized Sending work independently?
>
> Yes. The features are independent. You can use Content API for personalization without using PII Tokenized Sending, and vice versa.
> [accordion] What happens to active campaigns if I enable the PII API feature now?
>
> All subsequent messages for active campaigns on that channel will be sent using the PII API. Messages already in the provider's queue before you saved the settings may still be sent using data previously stored in MoEngage.
> [accordion] How does MoEngage handle API retries?
>
> MoEngage retries the API call up to three times, with a two-second interval between retries. Retries are performed only for the specific users for whom the API call failed, not for the entire batch.
> [accordion] Can I encrypt the PII data returned from my API?
>
> Yes. MoEngage supports symmetric key encryption for the API payload. The PII value is decrypted only at the time of sending the campaign.
> [accordion] What error does MoEngage display in campaign analytics if the PII API fails?
>
> The following errors are shown in the error breakdown section:
>
> | Channel | Error Message in UI |
> | - | - |
> | SMS, MMS, RCS, and WhatsApp | Invalid API response (fetching Mobile No.) Invalid/empty customer identifier in the MoEngage workspace. |
> | Email | Invalid API response (fetching Email ID) Invalid/empty customer identifier in the MoEngage workspace. |
>
> 
> [accordion] What happens to draft/scheduled campaigns activated after changing these settings?
>
> The draft campaigns will also use the PII API as soon as they are published or triggered next.
> [accordion] What happens to data retrieved in real-time from my customer's database?
>
> It is shared with your Email / SMS / MMS / RCS/ WhatsApp service provider and deleted afterward.
> [accordion] Is PII retrieved via API stored in logs?
>
> For channels configured to retrieve data through the PII API, MoEngage will cease logging Email IDs and/or mobile numbers. Instead, logs will contain a unique customer identifier (or tokenized identifier) consistent across both MoEngage and your customer database.
> [accordion] Do PII API settings apply to Flows as well?
>
> Yes. For instance, if the email settings are configured to retrieve the Email ID via API instead of utilizing the value stored in MoEngage, both individual email campaigns and email campaigns integrated into flows will commence fetching the customer's email ID through the API, rather than depending on the email attribute within the MoEngage database.
> [accordion] Does MoEngage offer PII masking?
>
> Yes, for more information, refer [here](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
> [accordion] Does MoEngage Inform support PII tokenized sending?
>
> No, currently, we do not support PII tokenized sending in MoEngage Inform.
> [accordion] Does the PII API also have the send and throttle speed as email batching?
>
> The PII API's send and throttle speeds are identical to those of email batching.
# Anonymous to Registered User Merge
Source: https://moengage.com/docs/user-guide/data/user-data/anonymous-to-registered-user-merge
Understand how MoEngage merges anonymous and registered user profiles when users log in across devices, and how identity resolution works.
All users are identified using a unique attribute such as email, mobile number, custom id, etc. These identifiers are generated when users provide information about themselves, such as when they log in with an email ID, mobile number, or username. In addition, users may visit your app or website using multiple devices, and until the user logs in, we will not know if this user is new or existing.
MoEngage classifies users as:
* **Anonymous User** - A user who hasn’t been identified yet by the website or the app. This could be a user who has been using the app/website but hasn’t logged in or a completely new user who hasn’t signed up.
* **Registered User** - A user who has signed up or logged in to your website or app.
# Terms to Know
* **MoEngage ID** - MoEngage creates a unique identifier as soon as a user visits your website or app to recognize a user, which is a non-changeable value.
* **ID** - When a user registers on your app or website (by providing a form of email, phone number, or user id), we recommend you generate a unique identifier for that profile and pass it to MoEngage as an ID. This ID lets you recognize the user across multiple devices and platforms, thus providing a 360° view. This ensures that information about the user is captured correctly even if they uninstall and reinstall the app.
# MoEngage ID and ID - Relationship
* **New User** - When a user opens or visits the app for the first time, neither the brand nor MoEngage has any information about them. MoEngage assigns a MoEngageID to this user and creates an anonymous profile for them. MoEngage records all actions that the user performs.
* **Sign-up** -If the user proceeds to sign up, they become a registered user or an identified user. The app assigns a unique identifier for each user (using SDK IdentifyUser() function). This information is passed to MoEngage, and this user is now considered a registered user in the MoEngage system.
* **Registered user who hasn’t signed in initially** - If the user has an account (has a MoEngage ID and an ID) but signs in after performing a series of events, a new MoEngage ID would have been created for them as they hadn’t signed in initially. Once they sign in, the user profile created with a new MoEngage ID is merged with the existing MoEngage ID.
# User Merge Scenarios
MoEngage enables you to have a single user ID for all your users, even if they are using different devices. The only condition for merging users in MoEngage is that the user has to be signed in on the device. When a user visits your website or app, MoEngage merges the anonymous user profile with the registered user profile once they log in to the system. For more information on enabling user merging, refer to [Query Settings](/docs/user-guide/settings/analytics-and-segmentation/query-settings).
**Scenario 1:** When the user visits your website or app for the first time on a device (Device 1), then they are user called an anonymous user, and a MoEngageID is set as MoEID-1 for that user.\
If the user logs in, this user is an identified user and an ID called U-1 is set for the user. All events on this device, until the user logs out or uninstalls, are attributed to MoEID-1.

**Scenario 2:** If the same user visits the website/app from another device (Device 2), then this user is still an anonymous user since MoEngage does not know the identity of this user, and a new MoEngageID MoEID2 is created for the user. If the user logs in, the website or app notifies MoEngage that the user ID is U-1. Now, the anonymous user is merged with the already existing registered user.

# Try It: User Merge Sandbox
Use the [User Merge Sandbox](https://user-merge-stimulator.lovable.app/identity-resolution-sandbox.html) to simulate how anonymous and registered profiles merge when a user logs in across devices. Create profiles, trigger a login, and review which attributes and events are retained after the merge.
> [!NOTE]
>
> The sandbox is a simulation for learning and validation only. It is not connected to your MoEngage workspace, and actions performed here do not affect your user data.
# Merge Impact on User Properties
> [!NOTE]
>
> Tracking and subsequent merging of an anonymous user to a registered user is possible only through MoEngage SDK integration. Anonymous to registered user merging is not possible through other data sources.
## Default Merge Behavior
By default, when a user merge occurs, MoEngage prioritizes the data already present in the registered user profile over the incoming anonymous user's data. This means the existing registered user's attribute value is retained, and the anonymous user's value is typically discarded.
The merging of an anonymous user profile into a retained user profile initiates the following system actions and attribute modifications:
* The **First Seen** attribute of the retained user profile is set to the oldest **First Seen** value across all the merging profiles, and the **Last Seen** attribute is set to the latest **Last Seen** value across all the merging profiles.
* The values of **LTV**, **No. of Conversion**, and **No. of Sessions** attributes are summed from both the existing and retained profiles, and the result is stored in the retained profile, and the other existing attributes of retained users remain unchanged.
* Attributes exclusive to the anonymous user are transferred to the retained user if the retained user lacks those attributes.
* Push reachability is calculated based on the overall devices.
* If the **Email (Standard)** attribute is copied to the retained user, the associated email suppression attributes (**Hard Bounce**, **Spam**, **Unsubscribed**) are also copied.
## Override Registered Custom User Properties with the Latest Anonymous User Data
> [!NOTE]
>
> * To enable this feature for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
> * This feature applies only to the custom user properties.
To provide flexibility in managing user data, MoEngage allows you to override selected existing custom user properties with the latest data captured from an anonymous user session. This feature is particularly useful in scenarios where the most recent information captured before login is more relevant for personalization and campaign targeting.
**Scenario**: A registered user, who is a frequent traveller, browses for flights to Paris anonymously on a travel application. You want to override the **Last Searched Location** custom attribute.
* **Without override**: If the user's registered profile initially had *New York* as their **Last Searched Location** custom attribute, this value (*New York*) persists during the user merge, despite their recent searches.
* **With override**: When the override feature is enabled, during the user merge, the value from the anonymous profile overrides the **Last Searched Location** attribute in the registered profile. So, the **Last Searched Location** changes from *New York* to *Paris*.
This ensures that the travel application can leverage the user's most recent location interest for targeted offers and personalized content, leading to more relevant and effective campaigns.
# Merge Impact on Events
All the events occurring after the user merge are attributed to the identified/registered user. All events performed before the merge are also migrated and attributed to the identified/registered user.
Each migrated event carries a `migrated_from_user_id` attribute, showing the user ID that was merged into the current (retained) user.

# Derived User Properties
Source: https://moengage.com/docs/user-guide/data/user-data/derived-user-attributes
Explore derived user properties in MoEngage — auto-generated properties like lifecycle stage and LTV used for segmentation and analytics.
MoEngage, by default, generates a few of the user properties. These are called derived user properties. These can be used in segmentation and analytics as filters to segment the users.
> [!NOTE]
>
> If you have [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, there are changes in the behaviour of Derived User Properties. For more information, refer to [Portfolio: Data Ingestion and Management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management).
Know more about the list of derived events and event properties [here](/docs/user-guide/data/event-data/derived-events-and-attributes).
# User Properties
Category-wise list of user properties:
> [!NOTE]
>
> The **Internal** and **External** columns of the tables below refer to the specific methods or origins that can be used to create or update each user property, as defined below:
>
> * Internally: Attributes are created or updated using the MoEngage SDK or are derived directly from internal platform activity.
> * Externally: Attributes can be created or updated using external inputs, including:
> * MoEngage APIs (Track User API, etc.)
> * File imports
> * Partner integrations
> * Other compatible external sources.
## Lifecycle
| Display and Key name | Description | Created/updated internally\* | You can update externally | You can create externally |
| - | - | - | - | - |
| First Seen (cr_t) | First seen time of the user. The time when the user is created in the MoEngage systems. | yes | no | yes |
| LTV (t_rev) | Life time value of the user. This is the total sum of revenue attributes present in the *Conversion goal* event performed by a user. LTV is updated every time the conversion goal event is executed by the user | yes | no | no |
| Last Seen (u_l_a) | The time of the most recent App/Site Open event for the user. | yes | no | yes |
| No. of Conversions (t_trans) | No. of conversion events done by the user, Conversion Goal can be modified on the settings page. | yes | no | no |
| No. of Sessions (u_s_c) | No.of sessions done by the user. This is the number of times a user has performed the App/Site Open event. | yes | no | no |
### Configure Lifetime Value (LTV)
LTV is a crucial metric that represents the total revenue a business expects to generate from a single customer account throughout their relationship with your brand. In MoEngage, you can calculate LTV directly within user profiles by mapping your revenue-generating events.
To configure LTV, perform the following steps:

1. Log in to the MoEngage dashboard and navigate to **Settings** > **General Settings**.
2. On the **General settings** page, navigate to the **Goal mapping** section.
3. In the **Goal mapping** section, select the following values:
* In the **Conversion goal** field, select the specific event that signifies a revenue-generating action from your users (e.g., Product Purchased, Order Placed, Subscription Renewed).
* In the **Revenue attribute** field, select the event property within that event that contains the actual monetary value of the transaction (e.g., price, total_amount, revenue).
* In the **Currency** field, select the currency in which the monetary value is denominated (e.g., USD, EUR, INR). This ensures accurate aggregation and reporting of your LTV.
4. Click **Save**. After saving, MoEngage automatically aggregates the monetary values from the specified event property for each user. This aggregated sum will then be stored as the LTV user property in their respective user profiles.
> [!NOTE]
>
> * It is essential to set up your Goal Mapping in MoEngage before you ingest the relevant revenue data. If you don't, LTV is not calculated for any historical data that was already ingested. This means only data ingested (including any backdated events) after your LTV goal mapping is configured contributes to the LTV attribute update.
> * Currently, the LTV attribute calculated using the above method cannot be directly updated or overwritten using APIs or File Import.
> * If your business requires a more complex or custom LTV calculation that cannot be achieved through the standard Goal Mapping feature, it is suggested to track a custom user property instead.
## Acquisition & Uninstall
| Display and Key Name | Description | Category | Created/updated internally\* | You can update externally | You can create externally |
| - | - | - | - | - | - |
| Campaign Name (campaign_name) | Name of the campaign advertisement through which the user installed the app. | Acquisition | yes | no | yes |
| Publisher Name (publisher_name) | Name of the Publisher through which the user installed the app. | Acquisition | yes | no | yes |
| Install Status (installed) | Current install status of the user. If the user has the app installed on one of their devices or has been active on the web device then the value will be '*True*'. This derived attribute gives the overall install status at a user level. It differs from the device level 'Install' event which is tracked through MoEngage SDKs. | Uninstall | yes | no | no |
| Uninstall Time (uninstall_time) | The time when our system found a user has uninstalled the app. | Uninstall | yes | no | no |
| Device ReInstall | Tracked when a reinstall is detected on a device. | Uninstall | yes | no | no |
| User ReInstall | Tracked when an identified user has reinstalled the app. | Uninstall | yes | no | no |
## Reachability & Localization
| Display and Key name | Description | Category | Created/updated internally\* | You can update externally | You can create externally |
| - | - | - | - | - | - |
| Push Opt In Status (iOS) (Deprecated) | Push permission status of a user on an iOS device. **Note**: This attribute was used to track the subscription status of a user. This attribute is deprecated by March 12, 2024. This data can now be tracked using the *Reachability Push iOS* user property. | Reachability | yes | no | no |
| Web Push Subscription Page URL (web subscription url) | Page URL of the web page on which a user subscribed to web push. Use it to find where the subscriptions are happening on your website or categorize your subscribers to send targeted notifications. | Reachability | yes | no | no |
| Web Push Subscription Status (Deprecated) (moe_sub_w) | Denotes the web push subscription status of a user - True / False. Use it to find your aggregate subscribers and users who unsubscribed after subscribing once. **Note**: This attribute was used to track the subscription status of a user. This attribute is deprecated by March 12, 2024. This data can now be tracked using the *Reachability Push Web* user property. | Reachability | yes | yes | yes |
| Reachability Push Android (moe_rsp_android) | Reachability Push Android is True (200) when the user is reachable on at least one android device. | Android | yes | no | no |
| Reachability Push iOS (moe_rsp_ios) | Reachability Push iOS is True (200) when the user is reachable on at least one iOS device. | iOS | yes | no | no |
| Reachability Push Web (moe_rsp_web) | Reachability Push Web is True (200) when the user is reachable on at least one web device. | Web | yes | no | no |
| Last Known City (moe_ip_city) | This attribute is based on the user's last known probable location, which is derived using reverse IP lookup. | Localization | yes | no | no |
| Last Known Country (moe_ip_country) | Localization | yes | no | no | |
| Last Known Pincode/Zipcode (moe_ip_pin) | Localization | yes | no | no | |
| Last Known State (moe_ip_subdivision) | Localization | yes | no | no | |
| User TimeZone Offset (Mins) (moe_dtzo) | Difference of the user time zone with respect to GMT in minutes. | Localization | yes | no | no |
> [!NOTE]
>
> The Location details, consisting of the last known city, country, pin-code/zipcode, and state acquired through an IP address, are updated at 30-minute intervals during every user session. It's essential to note that the location details may vary if the person is traveling. The accuracy of the location details based on IP addresses falls within the range of 70-80%.
>
> In case you require an accurate and persistent location, we suggest creating a custom attribute and tracking/updating the location details yourself using MoEngage data API, SDKs, File imports or other data sources.
## Device Data & Email Suppression Type
| Display and Key name | Description | Category | Created/updated internally\* | You can update externally | You can create externally |
| - | - | - | - | - | - |
| Hard Bounce (moe_hard_bounce) | Denotes if emails to the user have hard bounced. This value resets to its default state (false) whenever the email ID on the user profile is changed. | Email Suppression Type | no | yes | yes |
| Spam (moe_spam) | Denotes if the user has reported an email as spam. | Email Suppression Type | no | yes | yes |
| Unsubscribe (moe_unsubscribe) | Denotes if the user has unsubscribed from an email. | Email Suppression Type | no | yes | yes |
| Advertising Identifier (advertising_identifier) | Advertising Identifier of the device on which the app is installed. This is only available for iOS & Windows. If a user has multiple devices, the latest logged-in device's value will be the value of this user property. | Device Data | yes | no | yes |
| Browser Details (moe_w_ds) | Browser details of web users include - Platform, Browser, and Manufacturer. | Device Data | yes | no | no |
| Google Advertising ID (moe_gaid) | Advertising Identifier of the device on which the app is installed. This is only available for Android. If a user has multiple devices, the latest logged-in device's GAID will be the value of this user property. | Device Data | yes | no | yes |
| Mobile User (moe_mweb) | Denotes if the user accessed the website on mobile. | Device Data | yes | no | no |
## Tracked Standard Attribute
Tracked Standard Attribute - These attributes are tracked by clients in the standard Keys provided by MoEngage. These standard keys can be found in the [integration docs](/docs/user-guide/getting-started/integration).
| Display and Key name | Description | Created/updated internally\* | You can update externally | You can create externally |
| - | - | - | - | - |
| Birthday (u_bd) | Birth date of the user. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client. | no | yes | yes |
| User Creation Source (moe_cr_from) | Denotes the source through which a user was created. This is a standard attribute where MoEngage derives whether the user was created from SDK or Server to Server sources. | yes | no | no |
| Creation Source (moe_it) | Denotes the source through which a user was created. This is a standard attribute where MoEngage specifically derives whether the user was created from File Imports, Partner integration sources, etc. | yes | no | no |
| Email (Standard) (u_em) | Email address of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client | no | yes | yes |
| Name | Name of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| First Name (u_fn) | First Name of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| Gender (u_gd) | Gender of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| ID (uid) | Unique Id that the app has set for a user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| Last Name (u_ln) | Last Name of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| Locale Country (locale_country_display) | Country of the user derived from the device locale settings, for example, The United States. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | yes | no | no |
| Locale Language (locale_language_display) | Language of the user derived from device locale settings, for example, English. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | yes | no | no |
| Location (geo) | Latitude and Longitude of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | yes | no | no |
| Mobile Number (Standard) (u_mb) | Mobile Number of the user. This is a standard attribute where the name is provided by MoEngage, and the value is provided by the client. | no | yes | yes |
| Name (u_n) | Full Name of the user. This is a standard attribute where the name is provided by MoEngage and the value is provided by the client. | no | yes | yes |
| SMS Subscription Status (moe_sms_subscription) | SMS Subscription Status of the user. This is a standard attribute where the SMS Subscription Status is tracked based on the user's subscription preferences. | no | yes | yes |
| WhatsApp Subscription Status (moe_wa_subscription) | WhatsApp Subscription Status of the user. This is a standard attribute where the WhatsApp Subscription Status is tracked based on the user's subscription preferences. | no | yes | yes |
| Email Unsubscribed Categories (moe_em_unsub_categories) | Unsubscribed email categories of the user | no | yes | yes |
| Best time to send Push (moe_ds_bts_push_hour) | Derived from MoEngage's SherpaAI | yes | no | no |
| Best time to send Email (moe_ds_bts_email_hour) | Derived from MoEngage's SherpaAI | yes | no | no |
| Best time to send SMS (moe_ds_bts_SMS_hour) | Derived from MoEngage's SherpaAI | yes | no | no |
| Most Preferred Channel (moe_ds_mpc_best_channel) | Derived from MoEngage's SherpaAI | yes | no | no |
> [!WARNING]
>
> Mobile Number should be tracked as a string data type in [E.164 format](/docs/user-guide/settings/advanced-settings/e164-phone-number-format) to work well in MoEngage systems.
# Unified Identity (Identity Resolution)
Source: https://moengage.com/docs/user-guide/data/user-data/unified-identity-identity-resolution
Unified Identity links user data from multiple sources into one profile. Learn how MoEngage identity resolution eliminates duplicate users.
> [!TIP]
>
> * Every MoEngage workspace already merges anonymous and registered profiles automatically on login. Refer to [Anonymous to Registered User Merge](/docs/user-guide/data/user-data/anonymous-to-registered-user-merge) for that always-on behavior. Use this article instead if you want to merge profiles on identifiers beyond the default ID such as email, mobile number, or up to five custom attributes, across Data APIs, SDKs, file imports, and integrations like Shopify.
> * The two mechanisms have different rules: this feature is opt-in and irreversible once activated; the anonymous-to-registered merge is always-on. Both transfer all events with no cap.
# Overview
Users interact with your brand across channels such as website, app, offline store, social login. Each channel can generate a separate profile for the same person. The *Identity Resolution* feature of MoEngage merges these profiles into one, using identifier attributes such as `ID`, `Email`, or `Mobile Number` from data ingested via Data APIs, MoEngage SDKs, or CSV files. This gives you one accurate view of each user for segmentation, personalization, and reporting.
**Prerequisites**
To use identity resolution, choose an existing user property as an identifier (like a phone number or email ID) that uniquely identifies the user and activate it as an identifier. Only Admins can access this setting.
# Use Cases
Identity resolution plays a critical role in the following scenarios:
* **Online-to-offline matching**: A user browses your site with their email, then completes a purchase in-store using their phone number. Identity Resolution links both records to the same person.
* **Multiple sign-in methods**: A user registers via email, mobile OTP, and Facebook login, each creating a separate profile. Identity Resolution consolidates them into one as more identifiers are collected.
# Configure Multiple Identifiers
> [!NOTE]
>
> * You can configure up to five identifiers per workspace. `ID` is the default and always active; at least one identifier must remain active at all times.
> * You can opt to configure other user properties, such as email and mobile number, as additional identifiers. For example, if you choose email ID and mobile number as identifiers, MoEngage checks the email ID and mobile number for all users. In cases where multiple users share the same mobile number but have distinct email IDs, the system consolidates those users into a single profile as one of the identifier values matches successfully.
> * When two profiles share the value of any active identifier, MoEngage merges them. If profiles have conflicting data, the **retained profile** wins and the **merged profile** is deleted after its events and attributes transfer over.
Perform the following steps to configure multiple identifiers in the MoEngage dashboard (Only Admins can view and access Identity resolution):
1. On the left navigation menu in the MoEngage dashboard, go to **Settings** > **Data** > **Identity resolution.**
2. On the **Identity resolution** page, click **+Add identifier(s)**. You can add up to five identifiers for identity resolution.
> [!TIP]
>
> **Choosing good identifiers**
>
> A good identifier uniquely identifies one person (not a shared household phone or generic support email), stays consistently available across every data source you plan to use it with (SDK, API, file imports), and won't be reused across different people over time. Picking the wrong identifier is the most common source of unexpected merges or profiles that fail to merge.

1. By default, **ID** is listed as an identifier for merging user profiles using identity resolution. The **Active** tag represents the identifier currently used for identity resolution for merging users in your current workspace.
2. All the identifiers added are listed on this page. Click the ellipsis icon ( ) to perform the following:
* **Pause identity resolution**: This option allows you to pause merging the user based on that identifier. 
* **View/Edit exceptions**: This option allows you to view or edit exceptions of that identifier. In the **View/Edit exception** dialog box, select the exception from the list and click **Save**. 
3. The **Merge settings** option takes you to [Step 2: Review merge rules](/docs/user-guide/data/user-data/unified-identity-identity-resolution#step-2-review-merge-rules).
4. On the **Add identifier(s)** page, you can perform the following steps:
## Step 1: Select Identifiers

1. Select the checkbox next to the **User properties** you want to select as identifiers for identity resolution.
2. You can view the **Description** for each attribute.
3. **Exceptions**: Null and blank values are always excluded from identity-matching process and cannot be edited or removed. You can add further exceptions in string format.
4. You can view the various **Data sources** from which these identifiers are obtained. Identifiers backed by more data sources make for more reliable matching, check the Data sources before selecting.
5. The **Tracked data types** denote the various data types for which the data for that attribute has been tracked in MoEngage so far.
> [!NOTE]
>
> * Only *string* type attributes can be identifiers; other types are converted to string automatically.
> * Identity-matching process uses exact string values.
6. Click **Next**.
> [!TIP]
>
> Case Sensitivity
>
> Identifier matching is case-sensitive and does no normalization. If the same value can arrive in different cases across sources (e.g. an email captured as `John@brand.com` on web and `john@brand.com` via CSV import), those profiles won't merge unless you standardize casing before ingestion.
## Step 2: Review Merge Rules
1. **Profile retention rules:** This rule decides which user profile survives a merge, and are evaluated in order. Perform the following steps to add profile retention rules:
1. In the **Rule 1** list, select a user property. If only one of the two profiles has data for that attribute, that profile is retained. If both profiles have data for it, Rule 1 can't break the tie and Rule 2 runs instead. Rule 1 is optional and is empty by default.
2. In the **Rule 2** list, select a user behavior. This is the tiebreaker rule and defaults to *Latest Last Seen*. Whichever profile matches the behavior is retained.
For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline.
| Scenario | General Rule | Profile 1 (Online) | Profile 2 (Offline) | Outcome |
| - | - | - | - | - |
| **Rule 1 decides** | The profile with data in the selected attribute is considered the retained profile. | Rule 1 = Email ID, name, email, mobile — all populated | ID, name, mobile, no email | Profile 1 is retained: it's the one with data in the Rule 1 attribute (Email). |
| **Rule 1 ties, Rule 2 decides** | When both profiles have data in the selected attribute, Rule 1 fails (ties), and Rule 2 is validated to break the tie. |
Rule 1 = Email
Rule 2 = Latest Last Seen
ID, name, email, mobile, first seen — all populated | ID, name, email, mobile, first seen — all populated | Both profiles have Email, so Rule 1 ties. Rule 2 retains whichever profile has the more recent "last seen" timestamp. |

2. **Attribute rules**: This rule controls how specific custom attributes combine on merge. You can add a maximum of five such rules.\
Perform the following steps to add your own custom user property rules:
1. Click **Add rule**.
2. Select **User properties** and **Merge rules**.
For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline. Each profile has a *Loyality_points* attribute and has data in it, and if you want the *SUM* of both *Loyality_points* when both these profiles are merged, perform the following:
1. Select **_Loyality_points_** in **User property** list.
2. Select *Sum of values* in **Merge rules** list.
So, whenever user profiles are merged, the resulting profile comprises the combined sum of both profiles' loyality points. LTV ships with *Sum of values* pre-configured, no setup needed.

3. The **Verify merge** section shows how users are merged based on the profile retention and attribute rules you configured. Select **I have verified all merge scenarios** checkbox after verifying the merge scenarios. 
4. Click **Next**.
> [!NOTE]
>
> Whenever new data is ingested for an existing user, MoEngage automatically updates the existing user profile and their properties. Profile retention rules applied only during a merge.
## Step 3: Activate Identity Resolution
This step provides the instructions to be considered before and after activating the identity resolution.
> [!WARNING]
>
> Irreversible changes to be considered before activating.
>
> * A user merged cannot be unmerged.
> * For 48 hours post activation, the following actions are not possible on the Identity resolution page:
> * Adding new identifiers
> * Pausing/re-activating identifiers, and editing exceptions
> * Changing Merge settings
> * The [Merge User API](/docs/api/user/merge-users) is disabled when Identity Resolution is enabled.
> * Once you change the Merge setting, it applies only to merges that happen **after** the change, that is, newly merged users.
> * Users merged **before** the change remain merged under the old settings. They are not re-evaluated or reversed.
After activating identity resolution:
* Existing users in the workspace merge over 48 hours
* New incoming users merge with existing users based on profile retention rules
> [!TIP]
>
> Merge Caps:
>
> * Only the **first 50 users** in your workspace with the same identifier value are merged, rest remains un-merged.
> * If a new user is ingested sharing an identifier value already held by 50 merged users, that user is still created, but the identifier value itself is dropped from their profile and won't participate in future merges.
> * Any update sent to a user who remains unmerged past the cap is dropped in the same way.
> * To raise the 50-user cap for your workspace, contact your MoEngage Customer Success Manager (CSM) or the Support team.

Select **By activating identity resolution, I understand the impact of merging the user** check box and click **Activate** to activate identity resolution.
# Data Ingestion Support
MoEngage supports multiple identifiers across every ingestion path: Data APIs, SDKs, file imports, and native integrations like Shopify.
> [tab] Data APIs
>
> * Data APIs (Track User, Create Event, Bulk Import) can create or update users using any active identifier, not just `ID`.
> * You can create a Server-to-Server user with no ID at all, as long as another identifier is present.
>
> ### Request Body
>
> The following is a sample cURL request for a Bulk Import API consisting the User and Event payloads:
>
> * User payload must contain at least one configured identifier in `attributes`.
> * Event payload must include identifiers inside `user_identifiers` as shown in the below example where *moe_mobile* is one of the identifiers in the workspace
>
> ```json JSON wrap theme={null}
> "user_identifiers":{
> "moe_mobile":"{{Mobile_Number}}"
> }
> ```
>
> #### **Sample cURL Request for Bulk Import API:**
>
> **The following Bulk Import API consists of payloads for both users and events.**
>
> cURL
>
> ```json wrap theme={null}
> curl --location 'https://api-xx.moengage.com/v1/transition?app_id=O7NIHY0AT1K1FL8DR1J1' \
> --header 'Content-Type: application/json' \
> --header 'Authorization: Basic {{Authorization_Key}}' \
> --data '{
> "type": "transition",
> "elements": [
> {
> "type": "customer",
> "attributes": {
> "moe_mobile": "{{Mobile_Number}}",
> "first_name": "John"
> }
> },
> {
> "type": "event",
> "user_identifiers": {
> "moe_mobile": "{{Mobile_Number}}"
> },
> "actions": [
> {
> "action": "AddToCart",
> "attributes": {
> "product": "MacBook Air",
> "Brand": "Apple"
> }
> }
> ]
> }
> ]
> }'
>
> ```
>
> ### Pre-Flight Checklist for S2S User Creation
>
> Before sending S2S requests with multiple identifiers, confirm:
>
> * All identifiers you intend to send are configured as active identifiers in Settings > Data > Identity resolution.
> * Requests include the full set of configured identifiers rather than a partial subset wherever possible, to avoid ambiguous matches.
> * Profile retention rules are configured to reflect which data source (online vs. offline, primary system vs. secondary) should win in a conflict.
> * You have a process to handle API error responses for merge conflicts rather than silently retrying.
> * Merges triggered this way are irreversible, test in a staging workspace before rolling out to production.
>
> ### Cross-Profile Identifier Matching
>
> A single ingested payload can carry identifier values that already belong to different existing users. For example, the `id` in the payload may match User A while `moe_mobile` matches User B. In these cases:
>
> * All matching profiles merge into a single profile. There is no identifier priority order and no "first match wins" logic — every existing profile that matches on any active identifier is pulled into the merge.
>
> * The merge is automatic. The request is not rejected, and it is not queued for manual review.
>
> * The retained profile's values are decided by your configured [profile retention rules](/docs/user-guide/data/user-data/unified-identity-identity-resolution#step-2-review-merge-rules). With the default *Latest Last Seen* tiebreaker, the incoming request typically becomes the most recent activity, so its identifier values are retained.
>
> > [!NOTE]
> >
> > **Example**
> >
> > Assume `id`, `email`, and `moe_mobile` are all active identifiers, and the default profile retention rule (*Latest Last Seen*) applies.
> >
> > Existing state:
> >
> > * **User 1:** `id = ID1`, `email = E1`
> > * **User 2:** `id = ID2`, `email = E2`, `moe_mobile = M2`
> >
> > Incoming payload: `id = ID3`, `email = E1`, `moe_mobile = M2`
> >
> > The new payload matches User 1 on `email` and User 2 on `moe_mobile`. Both merge together with the incoming record, producing:
> >
> > * **Merged User:** `id = ID3`, `email = E1`, `moe_mobile = M2`
> >
> > `ID3` and the incoming values win because the new request has the most recent last-seen timestamp. `ID1`, `ID2`, and `E2` are dropped.
>
> Cross-profile identifier matching works the same way across every Data API (Track User, Create Event, Bulk Import) and across all other ingestion paths — SDKs, file imports, and native integrations such as Shopify. The merge is driven by your Identity Resolution configuration, not by which API or source the data arrived on.
>
> > [!WARNING]
> >
> > Because a single request can collapse two or more existing profiles, review your profile retention and attribute merge rules carefully before activating Identity Resolution. Merges cannot be reversed.
>
> ### Partial Identifier Payloads
>
> When a Data API call includes only a subset of the identifiers configured for your workspace — for example, the workspace has `id`, `moe_email`, and `moe_mobile` active, but the request only carries `moe_mobile` — MoEngage treats the call as a straightforward user update, not a merge.
>
> * **Lookup:** MoEngage searches for an existing user using whatever identifiers are present in the request (`moe_mobile` in the example above).
>
> * **Update:** Every attribute in the request payload is written to the matched profile. Identifier values not included in the request are left untouched on the existing profile.
>
> * **No merge:** Because only one profile is resolved, no profile retention or attribute merge rules are evaluated. This differs from [Cross-Profile Identifier Matching](#cross-profile-identifier-matching) above, where multiple existing profiles collapse into one and retention rules decide which values survive.
>
> > [!NOTE]
> >
> > A partial identifier payload does not cause data loss on its own — attributes outside the request are preserved on the existing profile. Data loss only happens when a payload's values overwrite existing values for the same attribute, which is standard update behavior across all ingestion paths.
> [tab] SDK
>
> Supported SDKs:
>
> * Android ([13.6.00](/docs/developer-guide/android-sdk/data-tracking/basic/track-user-attributes))
> * iOS ([9.23.0](https://www.moengage.com/docs/developer-guide/ios-sdk/data-tracking/basic/tracking-user-attributes))
> * WebSDK ([2.52.2](https://www.moengage.com/docs/developer-guide/web-sdk/data-tracking/web-sdk-user-attributes-tracking))
> * [GTM](/docs/developer-guide/web-sdk/other-supported-web-sdk-integration/google-tag-manager-gtm-templates#track-custom-user-attributes)
> * [AMP](/docs/developer-guide/web-sdk/other-supported-web-sdk-integration/configure-and-integrate-amp-event-analytics#tracking-user-attributes)
> * ReactNative
> * Flutter
> * Capacitor
>
> *identifyUser()* function is introduced in the new SDK versions that are compatible with Identity resolution. This function is a direct replacement of the *SetUniqueID* function and allows you to track users with multiple identifier attributes. Make sure to configure these identifiers in MoEngage before *IdentifyUser* function is implemented.
>
> The following are examples of SDK sample codes where email and id are set as identifiers in a given workspace.
>
> ### Sample Codes
>
> ```text Native Android theme={null}
> MoEAnalyticsHelper.identifyUser(context, "android-native-uid")
> MoEAnalyticsHelper.identifyUser(
> context,
> mapOf(
> "email" to "android@moengage.com",
> "id" to "android"
> )
> )
> ```
>
> ```text iOS theme={null}
> MoEngageSDKAnalytics.sharedInstance.identifyUser(identity: "ios-native-uid")
> MoEngageSDKAnalytics.sharedInstance.identifyUser(identities: [
> "email": "ios@moengage.com",
> "id": "ios"
> ])
>
> ```
>
> ```text WebSDK theme={null}
> Moengage.identifyUser({
> uid: 'uid1',
> u_em: 'email1@someEmail.com'
> })
> ```
>
> ```text ReactNative theme={null}
> ReactMoE.identifyUser("react-native-uid");
> ReactMoE.identifyUser({
> "id": "react-native",
> "email": "react-native@moengage.com"
> })
>
> ```
>
> ```text Flutter theme={null}
> final MoEngageFlutter _moengagePlugin = MoEngageFlutter(WORKSPACE_ID);
> _moengagePlugin.identifyUser("flutter-uid");
> _moengagePlugin.identifyUser({
> "email": "flutter@moengage.com",
> "id": "flutter"
> })
> ```
>
> > [!NOTE]
> >
> > Updates are made to SDK functions to improve user identification and session management.
> >
> > * **Forced Logout**: The MoEngage SDK no longer automatically logs out the previous user when a new user is detected on the device. Logout should now be explicitly called for workspaces enabled with Identity resolution to avoid data corruption.
> > * **SetUniqueID**: *IdentifyUser* function supports multiple identifiers, which replaces the need of using *SetUniqueID* function for user identification. Note that *SetUniqueID* is marked for removal in the future releases of SDK versions - it is important to use *identifyUser* instead especially if you are using Identity resolution in your workspace.
> > * **SetAlias**: For workspaces with the Identity resolution feature enabled, MoEngage SDK stores the previous identifier values. When *IdentifyUser* function is used to track the new identifier values, MoEngage SDK detects the change in identifier value and reports accordingly.
>
> **Retrieving Linked Profiles Programmatically**
> Use the asynchronous getter `getUserIdentities()` to check, client-side, which identifiers are bound to the current local session. It queries local SDK storage and returns a JSON dictionary of all currently bound identifier keys and values.
>
> > [!TIP]
> >
> > Run `getUserIdentities()` before an explicit user logout to confirm which identifiers are linked, and avoid breaking active device identity links.
> [tab] File Imports
>
> You can view the multiple identifiers configured for your workspace in the following sections:
>
> ### User Imports in Segment
>
> * If you have configured multiple identifiers for a given workspace, you can see them in the **Map identifiers** section in Step 2 while creating new user imports, otherwise you can only see `ID`. 
>
> * For Anonymous user import, if an identifier user property is selected as an anonymous ID, the users from the import may merge with the existing users having the same identifier value. For example, if you have configured an email ID as an identifier and, while mapping identifiers, you choose an email ID as the anonymous ID, there is a chance that users from the import may merge with other users having the same email ID. 
>
> > [!NOTE]
> >
> > * The uploaded CSV must have at least one column matching a configured identifier.
> > * After activating new identifiers, update existing periodic imports to map them correctly.
>
> ### Data Imports in Data
>
> If you have configured multiple identifiers for a given workspace:
>
> * While creating a new user data import, you can view them in the **Map identifiers** section, otherwise you can only see `ID`.
> * While creating a new event data import, you can view them in **Step 2: Import configuration and action** under the **Map identifiers** section, otherwise you can only see `ID` and `Event time`. 
> * While creating new auxiliary data imports, you can view them in **Step 2: Import configuration and action** by turning on the **Update user profile attributes** (optional) toggle of the **Map identifiers** section, otherwise you can only see `ID.`. 
>
> ### File Import & Segment CSV Processing Rules
>
> CSV uploads fully respect your active Identity Resolution configuration with the following behavior:
>
> * **Multi-key ingestion**: if a row contains values for more than one active identifier (e.g. both email and mobile), MoEngage checks both against existing records. If a single row bridges two distinct profiles, a background merge triggers immediately.
> [tab] Shopify
>
> ## Set Up Identifiers
>
> > [!TIP]
> >
> > **Prerequisite**
> >
> > Contact your CSM to enable Identity Resolution for your workspace.
>
> You can configure a maximum of five identifiers to merge users in MoEngage. Based on your business requirements, specify the identifiers.
>
> ## Handle Existing Duplicate Users
>
> MoEngage executes a one-time script to merge the existing users in the workspace based on the identifers you have activated as well as the merge settings selected in your workspace.
>
> When Identifiers are activated, a support ticket is raised where the feature enablement is tracked. The feature is enabled from the backend to activate the identifiers and start merging existing users based on the set identifiers. A report is generated once the feature is enabled, which will indicate every user merge action that is executed. This can be provided by the support team upon request.
>
> This section describes how you can use MoEngage Identity Resolution in Shopify.
>
> > [!TIP]
> >
> > **Prerequisite**
> >
> > Ensure that Shopify is integrated with MoEngage and that the Email-id or mobile number is configured as the identifier for profile merge.
> >
> > 
>
> ### Scenario 1: Email-id as the Identifier
>
> A user uses their email ID to register themselves on Shopify or purchase a product through your application.
>
> When the user clicks **Check Out**:
>
> * A cart token for that order is generated which regularly updates every time you make a new purchase.
> * The user is no longer treated as anonymous after they provide their email ID and other details during product purchase.
>
> In this scenario, consider three instances when a user browses your application with different email IDs as described below:
>
> #### Instance 1:
>
> Anonymous user U1 adds items to the cart, provides an email ID as [*Demo@gmail.com*](mailto:Demo@gmail.com), and converts to a registered user. A cart token (C1) is generated.
>
> 
>
> #### Instance 2:
>
> Anonymous user U2 adds items to the cart, provides an email ID as [*Demo2@gmail.com*](mailto:Demo2@gmail.com)*,* and converts to a registered user. A cart token (C2) is generated.
>
> #### Instance 3:
>
> Anonymous user U3 adds items to the cart, provides an email ID as [*Demo@gmail.com*](mailto:Demo@gmail.com) and merges their profile with U1. A cart token (C3) is updated.
>
> Because you have configured email ID as the identifier, MoEngage identifies that User 1 and User 3 share the same Email-id and merge their profiles.
>
> You can find all user events in the MoEngage dashboard at **Segment > User Profile > Activity Info**.
>
> 
>
> ### Scenario 2: Mobile number as the Identifier
>
> A user registered with your website with their email ID and provided their mobile number during the order transaction. The next time the user visits your offline store and provides the same mobile number during product purchase.
>
> * User1 registers online using a mobile number (M1) on Shopify and does some activity on the website.
> * User2 visits an offline store and provides a mobile number (M1) during product purchase. Offline data is then uploaded to MoEngage using CSV imports. In such cases, MoEngage identifies that User 1 and User 2 share the same mobile number and merge their profiles.
# Simulate Merge Scenarios
Merges performed by identity resolution are irreversible. Before you activate identifiers in your workspace, use the [Identity Resolution Sandbox](https://user-merge-stimulator.lovable.app/identity-resolution-sandbox.html) to validate your specific scenarios. For example, you can test cross-profile identifier matching, the outcomes of profile retention rules, and how attribute values are retained or dropped.
> [!NOTE]
>
> The sandbox is a simulation for learning and validation only. It is not connected to your MoEngage workspace, and actions performed here do not affect your user data.
# Impact of Merging Users
Merging affects data, segments, campaigns, and triggers internal system events. Review each before activating.
> [tab] On Data
>
> * User property info: the retained profile's attributes win; any attribute missing from the retained profile is filled in from the merged profile.
> * Devices: all devices from both profiles carry over to the retained profile, no device data is lost.
> * Events: Events from the merged profile transfer to the retained profile, including for transitive multi-ID merges (a user merging into a profile that has itself already been merged).
> [tab] On Segments
>
> * Active segments: When users are merged, the total number of users in active segments may decrease as duplicate profiles collapse into one.
> * Custom segments: Whenever the custom segment is updated, the user count may change.
> [tab] On Campaigns
>
> * User merging may impact the overall reachability number. When merged, the contact details of the merged user will be lost, and hence, a campaign’s overall reachability may be reduced. This also impacts the overall campaign stats.
> * Only Data APIs (Track User, Create Event, Bulk Import API) support multiple identifiers. Other APIs in MoEngage may still require ID.
> [tab] On System Events
>
> ### System-Generated Merge Events
>
> When automated Identity Resolution consolidates duplicate profiles, MoEngage fires internal system events depending on the scenario.
>
> * `MOE_USER_MERGE_EVENT`: fires globally whenever a standard profile merge starts.
> * `MOE_USER_MERGED`: fires on the primary (retained) profile once data fields combine successfully.
> * `MULTI_ID_USER_MERGED`: fires only when a multi-identifier configuration resolves and collapses multiple records
>
> In short, a regular single-identifier merge fires `MOE_USER_MERGE_EVENT` and `MOE_USER_MERGED`. A multi-ID merge fires all three, including `MULTI_ID_USER_MERGED`.
>
> > [!NOTE]
> >
> > Hidden by Default
> >
> > `MULTI_ID_USER_MERGED` visibility is OFF by default, so it won't appear in Segment or Flow event dropdowns. To expose it, go to **Settings** > **Data Management** > **User Events** and toggle its visibility ON.
> [tab] On Reachability
>
> | | | |
> | - | - | - |
> | **Channel** | **Reachability Attribute** | **Merge Outcome** |
> | Email | Hard bounce | If multiple users getting merged have the same email ID but conflicting hard bounce values, the outcome is hard Bounce = true. If users getting merged have different email IDs, the retained user’s email preferences remains post-merge. |
> | | Spam | If multiple users getting merged have the same email ID but with conflicting Spam statuses, the outcome is Spam = true. If multiple users getting merged have different email IDs, the retained user’s Spam status is retained. |
> | | Unsubscribe | If multiple users getting merged have the same email ID but with conflicting Spam statuses, the outcome is Unsubscribe = true. If multiple users are getting merged and have different email values, the retained user’s Unsubscribe status is retained. |
> | | Subscription Categories | Subscription categories of retained users are retained. |
> | Push | Reachability push status code (iOS, Android, Web) | When users are merged, all devices are added to the retained user. Final Reachability is derived based on all devices present with the retained user. |
> | SMS | Subscription status | Retained user’s mobile number preferences is retained. |
> | WhatsApp | Subscription status | Retained user’s mobile number preferences is retained. |
# FAQs
> [accordion] Some user properties and events seem to be lost during merge. Is it possible?
>
> Yes.
>
> * Example 1: If two users merge on a shared identifier but have a different attribute value, the merged profile only retains the value based on the retention rules. Hence, one of the attribute values is lost.
>
> * Example 2: If two users merge on a shared mobile number but have different emails, the merged profile's email is lost — only the retained profile's email survives.
>
> You should set the profile retention rules deliberately to control this. Merges cannot be reversed.
> [accordion] The user count and MTU numbers have suddenly reduced after activating identity resolution. Why?
>
> One of the profiles is deleted when two profiles merge into one. This reduces your key metrics, such as Total users, MTU, MAU, and more.
>
> Note that every unmerged duplicate profile counts separately toward your Monthly Tracked Users (MTU) — a key input to your MoEngage bill. Merging duplicates into one profile reduces your MTU count, so cleaning up existing duplicates can also lower cost in addition to improving data accuracy.
# Unset User Properties
Source: https://moengage.com/docs/user-guide/data/user-data/unset-user-attributes
Remove a value from a standard or custom user property entirely, restoring it to a null or non-existent state for accurate segmentation and data hygiene.
## Overview
> [!NOTE]
>
> **Early Access**
>
> This is an Early Access feature. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
The Unset User Property feature lets you remove a value from a specific user property, effectively restoring it to a "null" or "non-existent" state. Prior to this feature, if you wanted to clear the value of a user property, you might have set a value to 0, N/A, or an empty string. However, MoEngage still considers these "values". Unsetting ensures the user property value is removed entirely, enabling more accurate segmentation and data hygiene.
> [!NOTE]
>
> **Information**
>
> * This feature applies only to standard and custom user properties, not for derived user properties and ID (customer_id).
> * This feature is not supported for event or device attributes.
> * The unset attribute functionality is supported only through data APIs, specifically the Track User API and the Bulk Import API (only for user properties, not for event or device attributes).
> * The unset attribute functionality is not supported through SDKs, Warehouse Imports, and File based Imports.
> * You can unset PII encrypted and masked user properties.
## Use Cases
**Enhanced segmentation accuracy:** Enable precise targeting by removing obsolete status flags (for example, expired Loyalty Tier) from user profiles. This ensures that users correctly qualify for 'Does Not Exist' segments, eliminating data noise caused by residual empty or null values.
**Precise data removal:** Unlike setting a value to 0 or null (which keeps the attribute key present on the profile), unsetting the attribute removes the attribute value. This allows you to precisely delete individual attributes (such as PII or outdated contact details) to maintain data hygiene without impacting the broader user profile.
**Data compliance and GDPR:** Satisfy partial data deletion requests (for example, removing a phone number or specific PII due to a user request or GDPR compliance) by erasing specific user properties while preserving the remainder of the user's profile and historical data.
## Supported Data Types
You can unset attributes of the following data types:
* String (Text)
* Numeric (Integers, Decimals)
* DateTime
* Boolean (True/False)
* All Array types
By default, when an array is to be unset, all the attribute elements inside the array are unset. If you want to partially remove a specific element from an array, you should use the removeValueFromArrayField functionality. For more information, refer to `User Property as Array` cURL in the [Track User](/docs/api/user/track-user) API.
## Unsetting the User Properties
To unset attributes, pass them in the `unset_attributes` key of your JSON payload for the supported Data APIs. Add the name of each attribute you want to unset as a string in the array. Each name must exactly match the attribute name in your workspace.
### Sample cURL
Below is a sample JSON payload for the [Track User API](/docs/api/user/track-user). For the [Bulk Import API](/docs/api/bulk/bulk-import-users-and-events), the logic remains the same to unset an attribute, but applies only to the Customer payload (`type: customer`):
```bash theme={null}
curl --location --request POST 'https://api-0X.moengage.com/v1/customer/{{appId}}?app_id={{appId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Base64_ENCODED_APPKEY_APIKEY' \
--data '{
"type": "customer",
"customer_id": "Customer01",
"attributes": {
},
"unset_attributes": ["custom_userattribute_1"]
}'
```
> [!NOTE]
>
> **Information**
>
> * Requests to unset attributes that are Blocked in the Data Management dashboard are ignored.
> * Requests to unset Hidden attributes in the Data Management dashboard are processed successfully.
> * If an attribute is defined in both the `attributes` and `unset_attributes` object within the same API payload, the Unset operation takes precedence. The attribute value is removed.
> * The unset operation can only be performed on attributes that are already registered or present within the workspace. If an attribute name in `unset_attributes` is not found, MoEngage skips it without returning an error.
# User Install Status
Source: https://moengage.com/docs/user-guide/data/user-data/user-install-status
Track whether your app is installed, uninstalled, or reinstalled per user. Learn how MoEngage monitors install status through SDK and push.
Install status indicates whether an application is installed or not for a particular user, providing base-level install information at a user level.
# Track Install Status
MoEngage tracks the install status in multiple ways:
* By setting up [Install/Uninstall/Reinstall tracking](/docs/user-guide/getting-started/integration-validation/installuninstallreinstall-integration-validation) through SDK integration
* By observing when silent push messages, sent to users' devices, return a signal from Firebase Cloud Messaging (FCM) or Apple Push Notification Service (APNs) indicating whether the app is installed or not. Note that a silent push notification is not supported in Apple devices any longer. You can [activate this tracking](/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking) from the dashboard settings page.
* By setting up [Firebase integration](https://www.moengage.com/docs/developer-guide/components-for-sdk/tracking/real-time-uninstall-tracking) in MoEngage SDK for real-time uninstall tracking.
If MoEngage detects that a user has installed the app, the install status is marked as true; otherwise, it is marked as false. For users with multiple devices, the install status will be true, if the user has at least one installed device.
# View Install Status in MoEngage Dashboard
Follow the below steps to view the install status of a particular user in the MoEngage dashboard:
1. Log in to the MoEngage dashboard and navigate to **Segments** > **Create Segments**.
2. Under **Query results**, expand the desired query.
3. Under **Sample users** of the query, click the required user for which you want to view the install status. You can also search for the user directly using the search bar in Create segment UI.

4. In the following **User Profile** page that appears, under the **Uninstall** section you can view the Install Status.

# Factors Causing Inaccuracies in Install Status
There are certain factors that can cause inaccuracies in the install status tracking:
* **Inaccurate feedback details** - The silent push messages are typically tracked by feedback services of notification providers such as APNS and FCM. These feedback services usually notify applications when push messages cannot be delivered, also known as push bounce, which indicates that the customer has uninstalled your application. It’s nearly impossible to know exactly when a user uninstalls because feedback is only generated when apps attempt to deliver push messages.
* **Depreciation of silent push notifications for IOS 10**- The deprecation of silent push notifications in iOS 10 poses challenges for tracking uninstalls at the user level. Silent push notifications were previously used to detect when a user had uninstalled an app, as the feedback would indicate delivery failure. However, with their deprecation, it has become increasingly difficult to precisely track uninstalls.
* **User logout before uninstalling**- When a user logs out before uninstalling an app, it can lead to inaccurate uninstall tracking. This occurs because the app remains installed on the device even though the user may no longer actively use it. Uninstall tracking typically relies on feedback from push notification services that inform the app when messages cannot be delivered due to an app being uninstalled. However, if the user logs out without uninstalling, the app continues to receive push notifications, making it difficult to differentiate between an actual uninstall and a logged-out session.
* **Device archival**- Uninstall tracking can be inaccurate when the device is archived because the install status of a user is retained for up to 60 days even after archiving. When a device is archived, it means that it is no longer actively used or connected to the user's account. However, the uninstall tracking mechanism may not recognise the archived status and may continue to retain the user's install status as TRUE. This leads to inaccurate uninstall tracking as the user may have actually uninstalled the app but is still considered as having an active installation.
It's important to consider these limitations when analyzing the install status and interpreting user engagement and retention metrics accurately.
# User Profile
Source: https://moengage.com/docs/user-guide/data/user-data/user-profile
Get a 360-degree view of each user in MoEngage — attributes, activity history, subscription status, and more. Learn how user profiles work.

**User Profile**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3387991-user-profile)
User Profile gives a 360° view of a user's data stored in MoEngage, such as their first name, email address, subscription status, or the pages they visited on your website.
> [!NOTE]
>
> This documentation covers both the new and old UI of the User Profile. The new UI of the User Profile will be released in phases and if you wish to get it enabled earlier for your workspace, contact the MoEngage Support team.
A User Profile will be created and updated when a user opens your app or website that has the MoEngage SDK or when you upload user information through the UI or via API.
> [!NOTE]
>
> * Although MoEngage can ingest any amount of data, it follows a fair usage policy for data [tracking](/docs/user-guide/data/key-concepts/data-tracking-policies) and [archiving](/docs/user-guide/data/key-concepts/data-archival-retention-policy) to avoid misuse.
> * If you have [Portfolio](/docs/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, the User Profile will have associated changes. For more information, refer to [Portfolio: Data Ingestion and Management](/docs/user-guide/data/key-concepts/portfolio-data-ingestion-and-management).
**Prerequisites**
For managing user accounts, you must have the **User Profile Management** permission. This permission allows you to delete a user or edit their permissions. By default, this permission is automatically granted to the **Admin** and **Manager** roles. For more information, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
# Access User Profile
You can access the **User Profile** in the following ways:
1. **Access using the Search Users option**: From the left navigation on your MoEngage dashboard, click **Segment** > **Search Users.**
2. On the **Search Users** page, search for the users by ID, Email, Mobile Number, Name, or MoEngage ID using the search bar.

3. **Access user profiles based on user properties:** From the left navigation on your MoEngage dashboard, click **Segment > + New segment.** Search for the users by ID, Email, Mobile Number, or MoEngage ID from the field provided in the right corner of the window. This search provides the list of users, matching the search text with the provided fields. Clicking on any of the rows will open the user profile.
> [tab] New UI
>
> .gif?s=628b3bbf626b0bd93c0f09b7871add64)
> [tab] Old UI
>
> 
4. **Access user profiles based on criteria:** From the left navigation on your MoEngage dashboard, click **Segment** > **+ New segment.** Segment users based on the desired criteria. You can check your recent queries in the **Query Result** section. Click the user profile icon from the sample data to see the user details stored in MoEngage.
> [tab] New UI
>
> -1.gif?s=a4696a70d6a267f1bdb54f3c8fb81be7)
> [tab] Old UI
>
> -2.gif?s=d3b57daa02db481052b6e8ca3fc34a06)
> [!NOTE]
>
> * Any query in the user profile is performed using the server time, and the query result displays the event time.
> * Event time is displayed in the User Profile and not the server time. For more information, refer to [Event Time and Server Time](/docs/user-guide/data/event-data/event-time-and-received-time).
# User Profile
The User Profile contains the following sections:
* [Basic Details](/docs/user-guide/data/user-data/user-profile#basic-details)
* [User Info (This section is labeled as **User Properties** in the new UI.)](/docs/user-guide/data/user-data/user-profile#user-info/user-properties)
* [Activity Info (This section is labeled as **Event Activity** in the new UI.)](/docs/user-guide/data/user-data/user-profile#activity-info/event-activity)
## Basic Details
This section displays fundamental user information, including:
* First Name
* Last Name
* Email ID
* Mobile Number
* Custom Identifiers: These are the custom user identifiers you configured in the Identity Resolution dashboard. This detail is only visible when you use the new UI.
* MoEngage ID
* Client ID
> [tab] New UI
>
> .png?fit=max\&auto=format\&n=ZKLzlUPwWt6PWeT4\&q=85\&s=eb59370562e79be21b1a4c3ff7754624)
> [tab] Old UI
>
> 
## User Info/User Properties
This section presents information about the user, such as Lifecycle, Conversion, Acquisition, Location details, and Reachability.
> [tab] New UI
>
> 
> [tab] Old UI
>
> 
### Lifecycle
This section provides a high-level summary of the user's recent activity. It shows:
* **Last Active**: The date the user was last active on the platform.
* **No of sessions**: No.of sessions done by the user. This is the number of times a user has performed the App/Site Open event.
### Conversion
This section details the user's conversion metrics, which indicate their value and engagement with the platform. It shows:
* **No of conversions**: No. of conversion events done by the user.
* **Life Time value**: Life time value of the user. This is the total sum of revenue attributes present in the *Conversion goal* event performed by a user. LTV is updated every time the conversion goal event is executed by the user. For more information, refer to [Configure Lifetime Value (LTV)](/docs/user-guide/data/user-data/derived-user-attributes#configure-lifetime-value-ltv).
### Acquisition
This section provides information about how the user was first acquired. It shows:
* **First Seen**: The date the user was first seen or registered on the MoEngage platform.
* **Publisher / Campaign**: Name of the Publisher/Campaign through which the user installed the app.
### Location
This section displays the geographical location of the user. It shows:
* **City / State**: The user's city and state.
* **Country**: The user's country.
### Reachability
Reachability shows whether the user can be reached/connected through various channels like push, email, and SMS. The green tick mark on the Push card shows at least one platform or device on which this user is reachable. The red exclamation mark represents the user is not reachable on the respective platform or channel. For more information, refer to [User Reachability](/docs/user-guide/segment/reachability/user-reachability). Testing Reachability Use **Test Push, Test Email,** and **Test SMS** buttons to quickly send the test notification to the user. Test Push and Test Email send a preconfigured Push and Email, respectively. Test SMS requires the user to fill in the text message, as laws in a few countries (i.e. India) require whitelisted text to send the SMS.
### Subscription Statuses
> [!NOTE]
>
> The **Subscription Statuses** section is only available in the new UI.
This section allows you to view and manually edit the subscription status for Email and SMS channels.

* **Edit subscription status**: Click the edit icon to change the subscription status. Currently, manual overrides are supported only for Email and SMS. WhatsApp and Push remain read-only.
* **Email subscription status**: The email subscription status includes **Subscribed** and **Unsubscribed**. If your workspace has [Double-optin ](/docs/user-guide/campaigns-and-channels/email/getting-started-with-email/opt-in-management)configured, the subscription status includes **Optin pending**, **Double-opted in**, and **Opted out**.\
**Note**: For users using SendGrid as the email connector, updating the status in MoEngage automatically triggers a downstream update to SendGrid to keep statuses in sync. This change also generates internal tracking events and an entry in the Audit Logs. The events generated include:
* *Email Resubscribed*
* *Email Opt-in Status Updated*
* *Email Unsubscribed*
* **SMS subscription status**: Updating SMS status directly modifies the corresponding subscription attribute value.
### User Properties
This section shows all user properties with respect to the user.

You can access these from the **User Properties** drop-down during user segmentation, where they are organized into categories. A ‘mo’ symbol next to a property indicates that it is derived from or generated by MoEngage.
* To search for users using a specific value, hover over the property and click **COPY**.
* To export the entire list to a CSV file click **Download** in the right corner.
* To view the complete list of properties and their related information, refer [here](/docs/user-guide/data/event-data/derived-events-and-attributes).
> [!NOTE]
>
> PII (Personally Identifiable Information) marked properties are shown as **Private** in the User Profile. To learn more, see [PII Masking](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
> [!NOTE]
>
> **Date attributes can display a day out on the User Profile**
>
> The User Profile converts a date attribute from UTC to your workspace timezone only when the stored value matches the trailing format it expects. A value that ends in `.xxxZ` is converted, while one that ends in `.xxZ` is not, so it appears in raw UTC and can read as a day out.
>
> This affects how the value is displayed on the User Profile only. Segmentation counts and campaign targeting are not affected, because both evaluate the attribute in your workspace timezone. When a date on the User Profile looks a day out, check the segment count for the same attribute to confirm the underlying value is correct.
## Activity Info/Event Activity
The **Event activity** (or Activity Info) section displays a timeline of actions a user has performed, with their associated attributes. This data covers user activity based on your plan and data center configuration, and the event list is sorted in a Latest First order by default. If you want to look at user activity beyond 30 days, refer [here](/docs/user-guide/data/user-data/user-profile#user-activity-beyond-30-days).
> [tab] New UI
>
> 
> [tab] Old UI
>
> 
> [!NOTE]
>
> Device attributes (Device Density DPI, Device Height, Device Manufacturer, Device Model, Device Screen, Dimension, Device Width, Network Type, OS Version) and Source attributes (utm_source, utm_medium, utm_campaign, utm_id, utm_content, utm_term) are not available as Events in the user profile.
**Filters** User activity can be filtered on various parameters to analyze desired events and sections of the user profile. The filters are:
* Date Range Filters
* Platform Filters
* Event or Campaign Filters You can use different combinations of filters to fetch the required details of the user based on their activity.
> [tab] New UI
>
> 
> [tab] Old UI
>
> 
**Event Filters**
> [!NOTE]
>
> The **Event Filter** is labelled as **Filter Events** in the new UI.
User activity can be filtered for up to 5 events. Any event and respective attributes present in the account can be used to filter the customer activity. This is similar to filtering user activity present in segmentation. **Campaign Filters** Campaign filters allow you to filter the Campaign activities of the user. These filters allow you to fetch all campaigns or individual campaigns based on the campaign events performed by the user. The activity page includes additional features, which are listed below:
> [tab] New UI
>
> 
> [tab] Old UI
>
> 
* The activity timeline can be sorted by the LATEST FIRST order or the Oldest First Order. Your preference is saved on your device.
* You can EXPAND and COLLAPSE the event list for a detailed attribute view. Your preference will be saved on your device and can be changed as needed.
* The timeline on the left side of the window allows you to compare the time difference between any two consecutive events.
* Event Source, Event Platform, and Event category are displayed below each event.
* You can perform quick navigation by the Go to top and Goto bottom buttons.
* Easily copy any attribute value using the COPY button by hovering over the attribute.
* You can open the campaign details page directly from the user campaign activity
* Dotted lines between two events represent the date change
* View Interstitial Events between any filtered events
* Download the filtered event and event property by clicking on the **Download** button available in the top right corner of the **User Activity** > **Events** section.
### User Activity beyond 30 days
Activity Info (Event Activity) can also show events and event properties of a user for the entire duration of your account's data retention. Please follow the steps below to access the events of a user beyond 30 days:
1. Navigate to the **Filter Events (Event Filter)** section at the top of the **Activity Info (Event Activity)** page.
2. Select a date range of up to 7 days beyond the last 30 days. You can select the date range up to the maximum data retention period of your account. 
3. Select the events and attributes that you want to view for the user. You can select up to 10 events and 5 attributes per event. 
4. Click **Apply,** and you should be able to see the chosen events and event properties within the given date range for the user.
## Actions
If you are using the new UI, you can use the **Actions** button to perform the following:
* **Delete User:** You can permanently delete a user profile. Upon clicking delete, a warning is shown. Note that it may take up to 24 hours for the deletion to reflect across the system and the user profile will still be available until permanently deleted. This action is recorded in the [Audit Logs](/docs/user-guide/settings/account/audit-logs/audit-logs).
# Warehouse Schema
Source: https://moengage.com/docs/user-guide/data/warehouse-schemas
Map your warehouse tables to MoEngage as user and event schemas, so their columns become user properties and event properties your marketers can filter on.
Your data warehouse holds tables, and each table holds columns. A warehouse schema tells MoEngage what those tables and columns represent, so it can query them on your behalf.
The mapping happens at two levels:
* A **table** becomes either a **user schema** or an **event schema**.
* The **columns** in that table become **user properties** or **event properties**, depending on which kind of schema the table belongs to.
Once mapped, those properties and attributes appear in the segment builder dropdowns, and your marketers can build warehouse segments without writing SQL.
You set up warehouse schemas once. Your marketers then use the result to build audiences. For more information, refer to [Create a Warehouse Segment Using Filters](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters).
> [!NOTE]
>
> **Prerequisites**
>
> * A connected data warehouse. The connection steps and the read permissions MoEngage needs differ by warehouse. For more information, refer to [Connect Your Data Warehouse](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse).
> * The Admin or Developer role, which both include warehouse schema access by default. Other roles need it granted through a custom role.
> [!NOTE]
>
> Warehouse schemas support **BigQuery** and **Databricks**.
# How a Warehouse Schema Works
MoEngage does not copy your warehouse data. It reads your schema definitions, builds a SQL query from the filters selected in the segment builder, and runs that query against your warehouse when a segment is evaluated.
Each schema maps one table or view in your warehouse. There are two kinds:
| Schema | The table behind it | Its columns become | How many |
| - | - | - | - |
| **User schema** | Your user master table, holding the full set of unique users | User properties | One per connection |
| **Event schema** | An event table, with one row per event occurrence and many rows per user | Event properties | Many |
Create the user schema first. An event schema is joined to the user schema on the user ID column, so there is nothing to join against until the user schema exists.
## How Users Are Matched
Every schema is anchored on a user ID column, and the same column has to work on both sides of the join: it identifies a user in your warehouse, and its values have to match the customer ID on users in MoEngage.
Only users that match are segmentable. If a query returns 100 user IDs from your warehouse and 50 of them exist in MoEngage, the segment contains those 50. The other 50 are skipped, because MoEngage has no user to target.
Mapping a schema never creates users. To bring new users into MoEngage, use [Imports](/docs/user-guide/data/imports/overview/overview-imports).
# Set the Event Look-Back Window
Before you map your first table, set **Max event look-back**. This is how far back in days MoEngage reads event data from this warehouse. It defaults to **60 days** and is mandatory.
The setting applies to every schema on that connection, so you set it once rather than per schema. It bounds event tables only, because a user master table is not time-based. You can change it later from the same field.
> [!TIP]
>
> A longer look-back window scans more data on every query, which costs more and takes longer. Set it to the oldest event your marketers actually segment on rather than the longest window available.
> [!WARNING]
>
> Deleting a connection puts every schema and segment that depends on it into a **Broken** state, and flags any campaigns using those segments. Check dependencies before you delete a connection.
# Create a User Schema
The user schema points at your user master table, the single table that holds every user ID you want to segment on. Each connection has exactly one user schema, and you must create it before any event schema.
To create a user schema, perform the following steps:
1. On the sidebar menu in MoEngage, click **Settings**. The Settings page appears.
2. Under **Data**, click **Warehouse Schema**. The Warehouse schema page appears.

3. Select your connection from the dropdown beside the page title.
4. In **Max event look-back**, enter the number of days of event history MoEngage should read from this warehouse. The default is 60 days. For more information, refer to [Set the Event Look-Back Window](/docs/user-guide/data/warehouse-schemas#set-the-event-look-back-window).
5. Click **Create user schema**. The **Create user schema** page appears.

The process includes two steps, **Source and format** and **Mapping**.
## Step 1: Source and Format
First, point MoEngage at the table you want to read, and confirm it holds the data you expect.

1. **User schema name:** Enter a name for the schema. Use something recognisable, because this name identifies the schema on the Warehouse schema page and in error messages when a segment fails.
2. **Connection:** This is pre-filled with the connection you opened the page for. Only one user schema is permitted per connection, so this cannot be changed here.
3. **Schema/Dataset:** Select the schema or dataset that holds your user master table. On BigQuery, this is your dataset. The list is populated from the connection.
4. **Table:** Select your user master table. The list is populated from the schema or dataset you selected.
All the user IDs you want to segment on must be in this single table. MoEngage cannot combine user IDs from two tables, so pick the table that holds the complete set.
5. **Columns for preview:** Select the columns you want to see in the preview.
Select only the columns you need to recognise the table. Every preview runs a live query against your warehouse, so previewing columns you do not need costs you time and money. **Select all** is capped at the first 5,000 columns and is not recommended.
6. Click **Preview**. MoEngage queries your warehouse and displays up to the top 100 rows for the columns you selected.
Check the values before continuing. A preview that returns unexpected data usually means the wrong table was selected, which is far cheaper to fix now than after the mapping is done.
7. Click **Next**. The **Mapping** step appears.
## Step 2: Mapping
Next, tell MoEngage what each column means. Only the columns you map here appear in the segment builder.

1. **User identifier:** Select the column that holds your user ID. MoEngage matches the values in this column against the customer ID on existing MoEngage users, which is how a warehouse row becomes a targetable user.
Only one column can serve as the user identifier. Composite identifiers made of two or more columns are not supported.
> [!WARNING]
>
> Users whose identifier is null, empty, or not found in MoEngage are skipped. Warehouse segments target users MoEngage already knows. Creating a schema does not import new users.
2. Under **Map user attributes**, configure each column you want to use in segmentation. The heading shows how many columns the table has. For each column, do the following:
* **Display name:** Required. Enter the name your marketers see in the segment builder. It defaults to the raw column name, which is rarely what a marketer would search for. Rename `usr_ltv_amt` to `Lifetime Value`, `dob_dt` to `Date of Birth`, and `cust_city_nm` to `City`.
* **Description:** Optionally explain what the column holds. The description appears alongside the attribute in the segment builder, which reduces the number of questions that come back to your team.
* **Warehouse data type:** The column's native data type as reported by your warehouse. This is read-only.
* **MoEngage data type:** The type MoEngage normalises it to. This is read-only, and it determines which operators are available for the attribute in the segment builder. For the full mapping, refer to [Data Types](/docs/user-guide/data/warehouse-schemas#data-types).
* **Click to skip:** Select this checkbox to exclude the column. Skipped columns are not read and do not appear in the segment builder.
To exclude every column at once, select **Click to skip all** in the header row. To find a specific column in a wide table, use **Search by column name**.
The user identifier cannot be skipped. It is mapped separately above and shows **Marked as user identifier** in place of its checkbox.
3. To review the columns you excluded, select **Show skipped columns**. Skipped columns are hidden from the list by default.
4. To map a large table without working through it column by column, click **Upload mapping file** and supply the mapping as a JSON file. For the file format, refer to [Map Columns With a File](/docs/user-guide/data/warehouse-schemas#map-columns-with-a-file).
5. Click **Create schema**. MoEngage runs a validation query against your warehouse to confirm the user identifier column is non-null and unique.
On success, MoEngage confirms that the user schema was created and that you can now use warehouse segments to build custom segments.
> [!NOTE]
>
> Columns whose data type MoEngage does not support show `--` as the MoEngage data type and are skipped automatically. You cannot map them. For the list of supported types, refer to [Data Types](/docs/user-guide/data/warehouse-schemas#data-types).
# Create an Event Schema
An event schema points at a table of behavioral data, with one row per event occurrence and many rows per user. You can create as many event schemas as you have event tables.
To create an event schema, perform the following steps:
1. On the sidebar menu in MoEngage, click **Settings**. The Settings page appears.
2. Under **Data**, click **Warehouse Schema**. The Warehouse schema page appears.
3. Click **+ Event schema** at the top right. If this is your first event schema for the connection, you can also click **Create an event schema** in the middle of the page. The **Create event schema** page appears.

> [!NOTE]
>
> These options appear only after a user schema exists for the connection. Event schemas are joined to the user schema, so there is nothing to join against until it is created.
The process includes two steps, **Source and format** and **Mapping**.
## Step 1: Source and Format
First, point MoEngage at the event table and name the event your marketers will see.

1. **Event schema name:** Enter a name for the schema. This identifies the schema on the Warehouse schema page and in error messages when a segment fails.
2. **Connection:** This is pre-filled with the connection you opened the page for.
3. **Schema/Dataset:** Select the schema or dataset that holds your event table.
4. **Table:** Select the event table.
Tables already used in another schema appear greyed out and cannot be selected. A table can belong to one schema only, whether that is a user schema or an event schema.
5. **Columns for preview:** Select the columns you want to see in the preview. Use **Clear all** to reset the selection.
Select only the columns you need to recognise the table. Every preview runs a live query against your warehouse, so previewing columns you do not need costs you time and money. **Select all** is capped at the first 5,000 columns and is not recommended.
6. Click **Preview**. MoEngage displays the rows returned, up to a maximum of 100.
7. Under **Map event**, give the table the event name it should be mapped to in MoEngage:
* **Table name:** The source table. This is read-only.
* **Event display name:** Required. Enter the name your marketers see when they select this event in the segment builder. It defaults to the table name, which is rarely what a marketer would look for. `bq_event_order_placed_staging` means nothing to them, whereas `Order Placed` does.
* **Event description:** Optionally explain what the event records. The description appears alongside the event in the segment builder.
> [!NOTE]
>
> One table maps to one event. You cannot map several events from a single table, so select a table whose rows all represent the same event.
8. Click **Next**. The **Mapping** step appears.
## Step 2: Mapping
Next, tell MoEngage which column identifies the user, which column holds the event time, and what the remaining columns mean.
1. **User identifier:** Select the column in this table that uniquely identifies each user. This is what MoEngage uses to match rows in your warehouse to users in MoEngage, so the values must correspond to the user identifier in your user schema.
2. **Event time:** Select the column that records when the event happened. This must be a column that maps to the MoEngage Date-Time type, such as a `TIMESTAMP` column.
> [!WARNING]
>
> Event date-times must be stored in UTC. MoEngage converts them to your app timezone when a segment runs. A column stored in local time produces events that appear at the wrong time and fall into the wrong date ranges.
3. **Partitioned identifier column:** Optional. If your event table is partitioned, select the column it is partitioned on. MoEngage uses it to limit each query to the partitions it needs instead of scanning the whole table, which cuts the cost and time of every segment built on this event.
This is often the same column as the event time. A column serving both roles is labelled accordingly in the attribute table below.
4. Under **Map event attributes**, configure each remaining column. The heading shows how many columns the table has. For each column, do the following:
* **Display name:** Required. Enter the name your marketers see in the segment builder.
* **Description:** Optionally explain what the column holds.
* **Warehouse data type:** The column's native data type as reported by your warehouse. This is read-only.
* **MoEngage data type:** The type MoEngage normalises it to, which determines the operators available in the segment builder. This is read-only. For the full mapping, refer to [Data Types](/docs/user-guide/data/warehouse-schemas#data-types).
* **Click to skip:** Select this checkbox to exclude the column.
The user identifier and event time cannot be skipped. They are mapped separately above and show **Marked as user identifier** and **Marked as event time** in place of their checkboxes.
5. To map a large table without working through it column by column, click **Upload mapping file** and supply the mapping as a JSON file. For the file format, refer to [Map Columns With a File](/docs/user-guide/data/warehouse-schemas#map-columns-with-a-file).
6. Under **Test Join**, click **Test join**. MoEngage joins this table to your user master table on the user ID column and returns sample rows.
**Test join** stays disabled until you map the user identifier, because there is nothing to join on until then.
If the join returns nothing, MoEngage shows **No rows returned** and you cannot create the schema until it passes.
> [!NOTE]
>
> The usual cause is mapping the wrong column as the user identifier. Event tables often carry more than one ID: an order or purchase ID that identifies the row, and a user ID that identifies the person. Only the user ID matches your user master table.
The join runs against your warehouse, so it can take a few seconds depending on the size of your data.
7. Click **Create schema**, then click **Create** to confirm. The button stays disabled until the user identifier and event time are mapped and the test join passes.

# Map Columns With a File
Mapping a wide table one row at a time is slow. On the **Mapping** step of either wizard, click **Upload mapping file** and supply a JSON file instead. This works the same way for user schemas and event schemas.
The file holds a `mapping` array with one object per column:
```json theme={null}
{
"mapping": [
{
"column_name": "ID",
"display_name": "Customer ID",
"description": "The unique identifier assigned by the user to represent a customer",
"is_skipped": true
},
{
"column_name": "FIRST_NAME",
"display_name": "First Name",
"description": "Given name as captured at signup",
"is_skipped": false
},
{
"column_name": "LAST_NAME",
"display_name": "Last Name"
}
]
}
```
| Field | Required | Description |
| - | - | - |
| `column_name` | Yes | The warehouse column to map. Must match the column name in your warehouse exactly, including case. |
| `display_name` | No | The name your marketers see in the segment builder. |
| `description` | No | Explains what the column holds. Appears alongside the property or attribute in the segment builder. |
| `is_skipped` | No | Set to `true` to exclude the column from the schema. |
Two rules govern what happens to values you do not supply:
* **Omit a field** to leave its current value untouched. In the `LAST_NAME` example above, the description keeps whatever it had.
* **Set a field to `null` or `""`** to clear it. Use this to remove a display name or description you no longer want.
Values in the file override whatever is already mapped in the table. Columns the file does not mention are left alone, so you can upload a file covering a handful of columns without disturbing the rest.
To upload the file, perform the following steps:
1. On the **Mapping** step, click **Upload mapping file**. The **Upload mapping file** dialog appears.

2. To start from a template rather than writing the file yourself, click **Sample file**. MoEngage downloads a JSON file you can edit.

3. Drag your file onto the dialog, or click **upload from computer** and select it. The file must be JSON and smaller than 25 MB.
4. Click **Upload**.

# Keep Schemas in Sync
MoEngage reads your warehouse metadata on a schedule rather than live. The metadata covers databases, tables, and columns. Exploring a large warehouse on every page load is slow and runs up query costs on your side, so the metadata is cached.
**Metadata refreshes automatically every 6 hours.** A table or column you create now appears in MoEngage within that window. To pick it up sooner, use **Force refresh**, which re-reads the metadata in the background.
New columns are never mapped for you. Until you map a column or mark it as skipped, it does not appear in the segment builder. Use the **Show unmapped columns** filter on the mapping screen to see only the columns still waiting on a decision.
# Manage Your Schemas
The Warehouse schema page lists the schemas for one connection at a time. Select the connection from the dropdown beside the page title.

The page has two sections:
* The **user schema** for that connection, showing the schema name, source, user identifier, who last updated it, and when.
* **Event schemas**, showing the schema name, event display name, source table, who last updated it, and when. Use the search box to find a schema by event or schema name, or sort by schema name.
**Max event look-back** and **+ Event schema** are at the top right of the page.
To act on a schema, click the ellipsis icon on its row and select **View**, **Edit**, or **Delete**.

## View a Schema
**View** opens a read-only panel showing the schema name, source, event display name and description, who last updated it, and when.
Below that, **User properties mapped** or **Event attributes mapped** lists everything in the schema with its display name, description, and MoEngage data type. Use it to check what your marketers see without opening the edit flow. Entries without a description show `--`.

## Edit a Schema
**Edit** reopens the two-step wizard with **Update schema** in place of Create schema. What you can change depends on the field:
| Field | Editable |
| - | - |
| Schema name | Yes |
| Event display name and description | Yes |
| Attribute display names and descriptions | Yes |
| Skipped columns | Yes |
| Columns for preview | Yes |
| Connection, Schema/Dataset, Table | No |
| User identifier | No |
| Event time | No |
The structural fields are locked because changing them would rewrite the queries behind every segment built on the schema. If you need a different table or a different user identifier, delete the schema and create it again.
## Delete a Schema
Delete a schema from the ellipsis menu on its row.
Deleting the user schema removes everything for that connection, including every event schema built on it, because events are matched to users through the user schema. To confirm, type `DELETE` in capitals.
> [!CAUTION]
>
> Deleting a schema breaks everything built on it. Segments that depend on it start failing, and campaigns using those segments break with them.
If you need a different structure, plan on recreating the schema rather than editing your way there.
# Keep Segments Working When Your Warehouse Changes
A segment built on a warehouse schema depends on the underlying table staying as it was mapped. If you rename a column, drop a table, or change a data type, the query MoEngage generates for the segment can no longer run. The same happens if the connection is deleted.
> [!TIP]
>
> If your warehouse schema changes, check the warehouse segments built on it. MoEngage does not send an alert for these changes, so a quick check helps make sure your campaigns reach the right audience.
To check whether a segment still works, open it and run it. If the segment does not return a count, update the mapping in **Settings** > **Data** > **Warehouse Schema**, then run the segment again.
Before you change tables or columns in your warehouse, let the people who manage your MoEngage segments know so they can review the affected segments.
# Limits
| Limit | Value |
| - | - |
| Schemas per connection | 250, including the user schema, leaving 249 for events |
| User schemas per connection | 1 |
| Columns selectable for preview | 5,000 |
| Preview rows returned | 100 |
| Property or attribute name length | 200 characters |
| Property or attribute description length | 512 characters |
Schema limits are configurable. To raise them, contact [MoEngage Support](https://help.moengage.com/hc/en-us/requests/new).
# Permissions and Audit Logs
The **Admin** and **Developer** roles include warehouse schema access by default. To give another role access, or to take it away from one that has it, use [custom roles](/docs/user-guide/settings/account/team-management/access-roles).
Creating, updating, and deleting user and event schemas is recorded in audit logs. Changes to the warehouse connection itself are outside this scope.
# Data Types
Warehouses use far more data types than MoEngage needs. Each column is normalized to a MoEngage data type, and that type determines which operators are available for the attribute in the segment builder.
The mapping screen shows both types side by side, so you can check them before you publish.
| Warehouse data type | MoEngage data type |
| - | - |
| `STRING` | String |
| `INTEGER`, `FLOAT`, `NUMERIC`, `BIGNUMERIC` | Numeric |
| `BOOLEAN` | Boolean |
| `TIMESTAMP` | Date-Time |
| `ARRAY` | Array String |
| `ARRAY`, `ARRAY` | Array Double |
Warehouse types shown above are BigQuery names. Equivalent types on other warehouses normalize the same way. `VARCHAR`, `CHAR`, and `TEXT` columns all become a MoEngage String.
## Unsupported Data Types
Columns of these types cannot be mapped. They show `--` as the MoEngage data type and are skipped automatically.
| Warehouse data type | Why |
| - | - |
| `DATE`, `TIME` | Not available as attributes. Use a timestamp column instead, which maps to Date-Time. |
| `ARRAY`, `ARRAY` | Date and time arrays are not supported. |
| `GEOGRAPHY` | Location and geospatial types are not supported. |
| `RECORD`, `ARRAY`, `JSON` | Nested and object types are not supported. |
If a column you need is unsupported, cast it to a supported type in a view in your warehouse and map the view instead.
# Aggregation Operations
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/aggregation-operations
Use aggregation operations like sum, average, and count in MoEngage segmentation to build deeper queries and target high-value customer groups.
Let’s say you successfully ran a campaign offering a 10% discount last month. Now to pamper your high-value, highly loyal customers, you wish to run a campaign offering a larger discount, but only to the customers who responded to your last campaign. For example, you wish to target only those customers whose spending in the last month increased by 20%, compared to the month before. How do you segment this set of customers?
Growth teams require deep segmentation capabilities to effectively target their users. Aggregation enables businesses to add depth to their segmentation queries by leveraging aggregation operators. Here are a few of the use cases that you can execute using aggregation operators -
1. Filter users who have spent more than \$1000 in the last 30 days
2. Filter the user who has purchased the fruit category for more than \$200
3. Filter the user who increased/decreased their spending by 10% for the fashion category.
4. Filter the user who average spent per order increased by 15% with respect to last week.
Aggregation facilitates growth teams to aggregate an [event property](/docs/user-guide/data/event-data/derived-events-and-attributes) by using operations such as sum, average, min, max, and median. The aggregation operator on an event property combined with the [numeric filters](/docs/user-guide/segment/advanced-concepts/filters-in-segmentation) helps users write sophisticated queries and extract deeper customer segments.
# Aggregation Operators
| Aggregation Operator | Description |
| - | - |
| Sum | Sum of the selected attribute value across filtered events in the selected time range for a user. |
| Average | Average of the selected attribute value across filtered events in the selected time range for a user. |
| Minimum | Minimum of the selected attribute value across filtered events in the selected time range for a user. |
| Maximum | Maximum of the selected attribute value across filtered events in the selected time range for a user. |
| Median | Median of the selected attribute value across filtered events in the selected time range for a user. |
| Change | Absolute change in the aggregated attribute value across filtered events between the selected time ranges for a user. The primary period is the time period associated with the event selected. The base period is the time period associated with the aggregation operator. Change = Aggregated value of Primary Period - Aggregated value of Base Period. |
| Percentage Change | Relative change in the aggregated attribute value across filtered events between the selected time ranges for a user. Percentage Change = (Aggregated value of Primary Period - Aggregated value of Base Period)\*100/ Aggregated value of Base Period. |
> [!NOTE]
>
> * Aggregation can be applied over a period of 30 days/4 weeks/ 720 hours/1 month as applicable. These limits can be modified, please connect with your CSMs for the same.
> * Both Change and Percentage Change can be negative.
> * Previous Period: The previous period is the same length of time immediately before the primary time range. This is the Base Period of the aggregation. Assume now is 5:15 PM 18 May 2022. If the primary period for the 'last 3 days' is: 15 May 2022 - 18 May 2022, then the base period is 12 May 2022 - 14 May 2022.
> * Date Range: Date range available to aggregate the attribute value across filtered events for a user. The chosen date range is the Base Period of the aggregation.
# Using Aggregation Operators
Use the **+ Aggregation** button to add the aggregation functionality.
## Aggregation with Sum
Segment users who have placed an order at least 2 times in the last 2 weeks with a total purchase amount greater than 1000 dollars.

## Change with respect to Date Range
Segment users who have purchased at least 1 once in the last 3 days and the total amount spent increased by at least 1000 dollars with respect to 24 Sep 2022 - 30 Sep 2022.

## Percentage Change with respect to Previous Period
Segment users who have purchased at least 3 times in the 30 days and the average amount spent increased by at least 25% compared to the month before.

# Things to Note
1. Aggregation is available only on numerical attributes as sum, min, max, average, and median are numerical functions.
2. Aggregation is available only in the User Behavior Section of Segmentation.
3. Event retention and Aggregation:
* The previous period in aggregation cannot exceed the event retention period.
* Dates available under ‘Date range’ will not exceed the event retention period and the aggregation window.
4. The median is the approximate 50th percentile of the selected attribute value.
5. When filtered events are available for a user in the primary period but not the base period, this user is not counted in both Change and Percentage Change. For example, when there is no purchase event for a user in the base period, but it is present in the primary period, this user is not calculated for change and percentage change aggregation.
6. Change and Percentage change are not available for the date filters: Before, After, In the last N hours/weeks/months\*\*,\*\* last week, this week, last month, and this month.
# Filters in Segmentation
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/filters-in-segmentation
Understand how event, attribute, and user property filters work across the MoEngage dashboard, including supported data types and filter operators.
Across various pages on the MoEngage dashboard, events, event properties, and user properties filters can be used to get to the desired analysis or segment users. To get the right analysis and the right set of users, it's very important to know the filters.
This article explains how these filters work and if there are any different behaviors or filters on different pages.
# Data Types
On the MoEngage dashboard, there are seven primary data types:
* **String**: A string is a sequence of characters. Strings are typically used to represent words and text. Character in a string can be a letter of some alphabet, a digit, a punctuation mark, a blank space, etc.
* **Boolean**: The Boolean data type can have values as **true** and **false**.
* **Numeric** : A number is a sequence of digits . Numeric data types are typically used to represent amount, quantity , and price.
* **Geo Location**: Geo-location represents the location on the map using latitude and longitude.
* **Date Time**: Date time data types represent the date and time for an event or action.
* **Array:** A collection of data elements. MoEngage supports two types: **String Arrays** and **Numeric Arrays**, with a maximum limit of 254 elements per array as selectable values while filtering.
* **Object**: The Object data type provides a structured way to identify and query multiple related attributes contained within a single object. These attributes can be of any primitive data type, such as string, numeric, or date, and can be nested up to two levels. For more information, refer to [Object Data Type in Segmentation](/docs/user-guide/segment/advanced-concepts/object-data-type-in-segmentation).
## Terms to know
| **Term** | **Description** |
| - | - |
| Key | The key is a record in the database. |
| Key is set | The field which holds the value of an attribute. |
| Key not set | The field is not present to hold the value of the attribute. |
| Stored Value | User Behavior or User Property value that is stored in the MoEngage Application. For example, App/Site Opened, Last Seen, Email Clicked. For more information, refer to Derived Events & Attributes. |
| Filter Value | The value you choose to filter is based on the selected stored value. For example, you can choose the filter at least and type or select the duration or number of times the App/Site is opened. |
# String Filters
| Operator | Explanation |
| - | - |
| is | The stored value matches one of the filter values. |
| exists | The stored value is present. This includes all values, including Empty String and N/A. Filter users or events where the stored value exists (Key is set). |
| contains | The stored value contains one of the filter values. |
| contains spaces | The stored value contains spaces. The spaces can be at the start, in between, or at the end of the value. This includes all values, including Empty String and N/A. Filter users or events where the stored value contains spaces. **Note:** The contains spaces filter will be highly relevant in the case of unique identifier (UID) attributes like ID, Mobile number, Email ID, MoEngage ID, etc. It is also highly relevant for String and Array of string data types. Other data types do not have relevant use cases and might not yield expected results. |
| starts with | The stored value starts with one of the filter values. |
| ends with | The stored value ends with one of the filter values. |
| is not | The stored value is not a match to any of the filter values. The Filter is applied to all the attribute's values, including those that are not available (The Key is not set). |
| does not exist | The stored value is not present. The filter is applied to all the attribute values, including those that are not available (The Key is not set). |
| does not contain | The stored values are not a partial match to (do not contain) any of the filter values. The filter is applied to all the values in the stored attribute, including those that are unavailable (The Key is not set). |
| does not start with | The stored value does not start with any of the filter values. (Key not set) The filter is applied to all the attribute values, including those that are not available (The Key is not set). |
| does not end with | The stored value does not end with any of the filter values. The filter is applied to all the attribute values, including those that are not available (The Key is not set). |
| is empty | The stored value is "" (The Key is set and the value is null). |
| is not empty | The stored value is not "" (the stored value is not null), whether the Key is set or not. |
# Boolean Filters
| **Operator** | **Explanation** |
| - | - |
| is | The stored value is an exact match with the filter value. |
| is not | The stored value does not match the filter value. The stored value includes the attributes where the value does not exist (Key is not set). |
| exists | The stored value is present. This includes all values, including Empty Boolean and N/A. |
| does not exist | The stored value is not present (The Key is not set). |
# Numeric Filters
For the table below - N, N1, and N2 are numeric, and N2 > N1.
| **Operator** | **Explanation** |
| - | - |
| is equal to | The stored value is a match with one of the filter values. |
| is not equal to | The stored value does not match any of the filter values. The filter is applied to all the attribute values, including those that are not available (The Key is not set). |
| is between | The stored value is a match between the first filter value and the second filter value. N1 \<= Stored value AND Stored value \< N2. N1 & N2 are the first and second filter values, respectively. |
| is not between | The stored value is not matched between the first and second filter values. N1 > stored value OR stored value >= N2. N1 & N2 are the first and second filter values, respectively. |
| is less than | The stored value is less than the filter value. Stored value \< Filter value |
| is greater than | The stored value is greater than the filter value. Stored value > Filter value |
| exists | The stored value is present. This includes all values, including Empty Numeric and N/A. Filter users or events where the stored value exists (Key is set). |
| does not exist | The stored value is not present. The filter is applied to all the attribute values, including those that are not available (The Key is not set). |
# Event Occurrence Filters
Consider the following assumptions:
* Number of times user executes or does not execute the event: n
* Event in consideration: Viewed Product
* Today's Date - Dec 14th 2023.
* Event Retention Period for Segmentation - 30 days ( Nov 14th 2023)
| **Operator** | **Explanation** |
| - | - |
| exactly | The user has the event exactly for the specified number of times. Example: **Has Executed Viewed Product exactly 2 times** This filter would fetch users who have viewed a product exactly twice in the specified date range added in the filter criteria. |
| at least | The user has executed the event at least n times (>= n) Example: **Has Executed Viewed Product at least 1 times** This filter would fetch users who have viewed a product at least once in the specified date range added in the filter criteria. |
| at most | The user has executed the event at most n times (\<= n). Example: **Has Executed Viewed Product at most 4 times** This filter would fetch users who have viewed a product at most four times (\<=4) in the specified date range added in the filter criteria. |
| for the first time | The user has executed the event for the first time within the specified date range. Example: **Has Executed Viewed Product for the first time in the last 4 days** This filter would fetch users who have viewed a product for the first time in the last 4 days(till 10th Dec 2023) and have not viewed a product before that (has not executed viewed product before 10th Dec 2023 (period in consideration here - 14th Nov 2023 to 10th Dec 2023). **Note:** This operator will run as per the events data retention applicable to your Workspace. Behavior analysis evaluates this operator only within the selected date range, so its count can be higher. For more information, refer to [First-Time Event Filters](/docs/user-guide/analyze/analytics-how-to/different-count-in-analytics-and-segmentation#first-time-event-filters). |
| for the last time | The user has executed the event for the last time within the specified date range. Example: **Has Executed Viewed Product for the last time** This filter would fetch users who have viewed a product for the last time in the specified date range added in the filter criteria. **Note:** This operator will run as per the events data retention applicable to your Workspace. |
# Location-Triggered Filters
| **Operator** | **Explanation** |
| - | - |
| Point with Radius | The stored geolocation value is within the circle defined by the point and the radius. |
# Date Time Filters
To understand filter operators in date-time data types, we need to first understand a few functions -
* now = current timestamp up to milliseconds
* start_of_day(timestamp) = 00:00:00 of the selected day/date
* end_of_day(timestamp) = 23:59:59 of the selected day/date
* n days = n \* 24 hours
* For the table below - n, n1, and n2 are numeric and n2 > n1.
### For example
* Let's assume now is 7:30:05 PM, 5 Jan 2001 then
* now - 3 days = now - (3\* 24) hours = 7:30:05 PM, 2 Jan 2001
* now + 3 days = now + (3\* 24) hours = 7:30:05 PM, 8 Jan 2001
* start of the day (now) = 12:00:00 AM, 5 Jan 2001
* end of the day (now) = 11:59:59 PM, 5 Jan 2001
* Let's assume the date is 1 Jan 2001
* start of day (date) = 12:00:00 AM, 1 Jan 2001
* start of day (date + 1 day) = 12:00:00 AM, 2 Jan 2001
* start of day (date - 1 day) = 12:00:00 AM, 31 Dec 2000
* end of day (date) = 11:59:59 PM, 1 Jan 2001
* end of day (date + 1 day) = 11:59:59 PM, 2 Jan 2001
* end of day (date - 1 day) = 11:59:59 PM, 31 Dec 2000
> [!NOTE]
>
> All date-time filters work in the App time Zone, specified in Settings.\
> (Settings -> App -> General -> General Settings -> Account Settings -> TimeZone )
| **Operator** | **Filter Value Type** | **Explanation** |
| - | - | - |
| in the last | n days | Stored value is From = Start of day(Now - N days), To = Now. N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N = 3. From = 12:00:00 AM, 4 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| | n hours | Stored value is From = Start of the hour (Now - N hours), To = Now N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N = 3. From = 8:00:00 AM, 7 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| | n weeks | Stored value is From = Start of the week (Monday of (Now - N weeks)), To = Now N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N = 2. From = 12:00:00 AM, 22 Aug 2022 (Monday) To = 11:30:30 AM, 7 Sep 2022. |
| | n months | Stored value is From = Start of the month (Now - N months), To = Now N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N = 2. From = 12:00:00 AM, 1 Jul 2022. To = 11:30:30 AM, 7 Sep 2022. |
| on | date | Stored value is From = Start of day (Date chosen), To = End of day (Date chosen) Example: If Now = 11:30:30 AM, 7 Sep 2022 & Date chosen is today. From = 12:00:00 AM, 7 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| | days ago | Stored value is From = Start of day (Now - N days), To = End of day (Now - N days) N is the filter value Example: If Now = 11:30:30 AM, 7 Sep 2022 & N=3. From = 12:00:00 AM, 4 Sep 2022. To = 11:59:59 PM, 4 Sep 2022. |
| | days from now | Stored value is From = Start of day(Now + N days), To = End of day(Now + N days). N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022, & N=3. From = 12:00:00 AM, 10 Sep 2022. To = 11:59:59 PM, 10 Sep 2022. |
| in between | date | Stored value is From = Start of day(Date 1), To = End of day(Date 2). Date 1 & Date 2 are the start and end dates respectively. Example: If selected Date1 = 7 Sep 2022, & Date2 = 15 Sep 2022. From = 12:00:00 AM, 7 Sep 2022. To = 11:59:59 PM, 15 Sep 2022. |
| | days ago | Stored value is From = Start of day (Now - N2 days), To = End of day (Now - N1 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 11:30:30 AM, 7 Sep 2022, N1 = 3, & N2 = 5. From = 12:00:00 AM, 2 Sep 2022. To = 11:59:59 PM, 4 Sep 2022. |
| | days from now | Stored value is From = Start of day(Now + N1 days), To = End of day(Now + N2 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 11:30:30 AM, 7 Sep 2022, N1 = 3, & N2 = 5. From = 12:00:00 AM, 10 Sep 2022. To = 11:59:59 PM, 12 Sep 2022. |
| before | date | Stored value is To = End of day (Date chosen - 1 day) Example: If Now = 11:30:30 AM, 7 Sep 2022 & Date chosen is today. To = 11:59:59 PM, 6 Sep 2022. |
| | days ago | Stored value is To = End of day(Now - (N+1) days) N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N = 3. To = 11:59:59 PM, 3 Sep 2022. |
| after | date | Stored value is From = Start of day (Date chosen + 1 day), Example: If Now = 11:30:30 AM, 7 Sep 2022 & Date chosen is today. From = 12:00:00 AM, 8 Sep 2022. |
| | days from now | Stored value is From = Start of day(now + (N+1) days) N is the filter value. Example: If selected Date = 7 Sep 2022, & N = 3. From = 12:00:00 AM, 11 Sep 2022. |
| in the next | days | Stored value is From = Now, To = End of day(now + N days). N is the filter value. Example: If Now = 11:30:30 AM, 7 Sep 2022 & N =3. From = 11:30:30 AM, 7 Sep 2022. To = 11:59:59 PM, 10 Sep 2022. |
| today | | Stored value is From = Start of day(Today), To = Now Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 7 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| yesterday | | Stored value is From = Start of day(Now - 1 day), To = End of day(Now - 1 day) Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 6 Sep 2022. To = 11:59:59 PM, 6 Sep 2022. |
| this week | | Stored value is From = Start of week (Monday of the current week), To = Now Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 5 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| last week | | Stored value is From = Start of week (Now - 7 days), To = End of week (Now - 7 days) Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 29 Aug 2022. (Monday) To = 11:59:59 PM, 3 Sep 2022. |
| this month | | Stored value is From = Start of Month (1st of current month), To = End of Month (Now) Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 1 Sep 2022. To = 11:30:30 AM, 7 Sep 2022. |
| last month | | Stored value is From = Start of Month (Now - 1 month), To = End of Month (Now - 1 month) Example: If Now = 11:30:30 AM, 7 Sep 2022. From = 12:00:00 AM, 1 Aug 2022. To = 11:59:59 PM, 31 Aug 2022. |
| exists | | The stored value is present. This includes all values including Empty Date Time and N/A. Filter users or events where the stored value exists (Key is set). |
| does not exist | | The stored value is not present. The filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
## Special Date Filters
Special date filter filters for a specific hour, weekday, month, date of the month, and date of the year. This is useful for filtering out birthdays across years, and bill dates across months.
Special date filters are available in the drop-down next to the date attributes in the User property and the User behavior section.


| **Operator** | **Text on Dashboard** | **Explanation** |
| - | - | - |
| Date | Date | Filter the stored dates. |
| Hour of the day | Daily where the hour/s | Filter the stored dates based on their hour. Use this option to filter dates having specific hour/s e.g. 12 AM - 1 AM. Use this filter to segment all users whose movie time or yoga class time falls between 8 AM - 9 AM. |
| Day of the week | Weekly where the day/s | Filter the stored dates based on their weekday. Use this option to filter dates of specific weekdays e.g. Monday. Use this filter to segment all users who ordered food or booked a cab on Friday. |
| Day of the month | Monthly where the day/s | Filter the stored dates based on their day. Use this option to filter dates of a specific day of any month e.g. 5th. Use this filter to segment users whose monthly bill payment date or subscription renewal date is the 15th. |
| Month of the year | Yearly where the month/s | Filter the stored dates based on their month. Use this option for actions performed on a specific month of any year e.g. January. Use this filter to segment all users whose birthday or yearly subscription expiry is in March. |
| Date Month | Yearly where the date/s | Filter the stored values based on their date month combination. Use this option to filter dates having a specific date month combination e.g. 01 Feb. This can be used to filter birthdays and anniversaries e.g. segment users whose birthday or billing day is 15 Sep. |
Special date filters are available only for user and event properties where the data type is 'date'. Special date filters are not available in the Affinity Segmentation and Analytics filter.
## Hour of the day - Daily where the hours
For hours of the day, let’s understand these filters' definitions better with examples.
| **Operator** | **Filter Value** | **Explanation** | |
| - | - | - | - |
| in the following | -- | Hour value of the stored date matches with one of the filter values. | |
| on | hour | Stored value is From = Start of the hour(Hour), To = End of the hour(Hour). Hour is the filter hour. Example: If selected Hour = 12 AM. From = 12:00:00 AM, To = 12:59:59 AM. (Irrespective of the date) | |
| | hours ago | Stored value is From = Start of the hour(Now - N hours), To = End of the hour(Now - N hours). N is the filter value. Example: If Now = 11:30:30 AM & N =3. From = 8:00:00 AM, To = 8:59:59 AM. (Irrespective of the date) | |
| | hours from now | Stored value is From = Start of hour(Now + N hours), To = End of hour(Now + N hours). N is the filter value. Example: If Now = 11:30:30 AM & N =3. From = 02:00:00 PM, To = 02:59:59 PM. (Irrespective of the date) | |
| In between | hour | Stored value is From = Start of the hour(Hour 1), To = End of the hour(Hour 2). Hour 1 & Hour 2 are the start and end hours respectively. Example: If selected Hour1 = 01 AM, & Hour2 = 05 PM. From = 01:00:00 AM, To = 05:59:59 PM. (Irrespective of the date) | |
| | hours ago | Stored value is From = Start of the hour(Now - N2 hours), To = End of the hour(Now - N1 hours). N1 & N2 are the first and second filter values respectively. Example: If Now = 11:30:30 AM, N1 = 3, & N2 = 5. From = 06:00:00 AM, To = 8:59:59 AM. (Irrespective of the date) | |
| | hours from now | Stored value is From = Start of hour(Now + N1 hours), To = End of hour(Now + N2 hours). N1 & N2 are the first and second filter values respectively. Example: If Now = 11:30:30 AM, N1 = 3, & N2 = 5. From = 02:00:00 PM, To = 04:59:59 PM. (Irrespective of the date) | |
| in the last | n hours | Stored value is From = Start of the hour(Now - N hours), To = End of the hour(Now) N is the filter value. Example: If Now = 11:30:30 AM & N =3. From = 8:00:00 AM, To = 11:59:59 AM. (Irrespective of the date) | |
| in the next | n hours | Stored value is From = Start of hour(Now), To = End of hour(Now + N hours) N is the filter value. Example: If Now = 11:30:30 AM & N =3. From = 11:00:00 AM, To = 02:59:59 PM. (Irrespective of the date) | |
## Day of the week - Weekly where the day
For the day of the week, let’s understand these filter definitions better with examples.
| **Operator** | **Filter Value** | **Explanation** | |
| - | - | - | - |
| is today | -- | Stored value is From = Start of weekday(Now), To = End of weekday(Now) Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday. From = Monday 12:00:00 AM, To = Monday 11:59:59 PM. (Irrespective of the date) | |
| in the following | -- | The weekday value of the stored date matches with one of the filter weekdays. | |
| on | day | Stored value is From = Start of weekday(Day), To = End of weekday(Day) Day is filter weekday. Example: If Day = Wednesday. From = Wednesday 12:00:00 AM, To = Wednesday 11:59:59 PM. (Irrespective of the date) | |
| | days ago | Stored value is From = Start of weekday(Now - N days), To = End of weekday(Now - N days). N is the filter value. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday & N = 3 From = Friday 12:00:00 AM, To = Friday 11:59:59 PM. (Irrespective of the date) | |
| | days from now | Stored value is From = Start of weekday(Now + N days), To = End of weekday(Now + N days) N is the filter value. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday & N = 3 From = Thursday 12:00:00 AM, To = Thursday 11:59:59 PM. (Irrespective of the date) | |
| In between | day | Stored value is From = Start of weekday(Day 1), To = End of weekday(Day 2) Day 1 & Day 2 are the start and end weekdays respectively. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday. Day 1 = Tuesday & Day 2 = Tuesday. From = Tuesday 12:00:00 AM, To = Thursday 11:59:59 PM. (Irrespective of the date) | |
| | days ago | Stored value is From = Start of weekday(Now - N2 days), To = End of weekday(Now - N1 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday. N1 = 2 & N2 = 4. From = Thursday 12:00:00 AM To = Saturday 11:59:59 PM (Irrespective of the date) | |
| | days from now | Stored value is From = Start of weekday(Now + N1 days), To = End of weekday(Now + N2 days) N1 & N2 are the first and second filter values respectively. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday. N1 = 2 & N2 = 4. From = Wednesday 12:00:00 AM, To = Friday 11:59:59 PM. (Irrespective of the date) | |
| in the last | N days | Stored value is From = Start of day(Now - N days), To = End of day(Now) N is the filter value. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday & N = 3. From = Friday 12:00:00 AM, To = Monday 11:59:59 PM. (Irrespective of the date) | |
| in the next | N days | Stored value is From = Start of the day (Now), To = End of day(Now + N days) N is the filter value. Example: If Now = 04:30:30 PM, 1 Jan 2001, Monday & N = 3. From = Monday 12:00:00 AM, To = Thursday 11:59:59 PM. (Irrespective of the date) | |
## Day of the month - Monthly where the day
For the day of the week, let’s understand these filter definitions better with examples.\
Here Date(DD) numerical date value e.g. 11, 23, 05.
| **Operator** | **Filter Value** | **Explanation** | |
| - | - | - | - |
| is today | -- | Stored value is From = Start of day(Now), To = End of day(Now) Example: If Now = 4:30 PM, 11 Jan 2001. From = 11th 12:00:00 AM To = 11th 11:59:59 PM (Irrespective of the month & year) | |
| in the following | -- | Date(DD) value of the stored date matches with one of the filter dates. | |
| on | day | Stored value is From = Start of day(Date), To = End of day(Date) Date(DD) is the filter date. Example: If selected Date = 7th. From = 7th 12:00:00 AM, To = 7th 11:59:59 PM. (Irrespective of the month & year) | |
| | days ago | Stored value is From = Start of day(Now - N days), To = End of day(Now - N days). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 8th 12:00:00 AM, To = 8th 11:59:59 PM. (Irrespective of the month & year) | |
| | days from now | Stored value is From = Start of day(Now + N days), To = End of day(Now + N days) N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 14th 12:00:00 AM, To = 14th 11:59:59 PM. (Irrespective of the month & year) | |
| In between | day | Stored value is From = Start of day(Date1), To = End of day(Date2) Date1(DD) & Date 2(DD) are the start and end dates respectively. Example: If Date1 = 14th & Date2 = 23rd. From = 14th 12:00:00 AM, To = 23rd 11:59:59 PM. (Irrespective of the month & year) | |
| | days ago | Stored value is From = Start of day(Now - N2 days), To = End of day(Now - N1 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 4:30 PM, 11 Jan 2001, N1 = 11 & N2=19. From = 23rd 12:00:00 AM, To = 31th 11:59:59 PM. (Irrespective of the month & year) | |
| | days from now | Stored value is From = Start of day(Now + N1 days), To = End of day(Now + N2 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 4:30 PM, 11 Jan 2001, N1 = 11 & N2=19. From = 22nd 12:00:00 AM, To = 30th 11:59:59 PM. (Irrespective of the month & year) | |
| in the last | N days | Stored value is From = Start of day(Now - N days), To = End of day(Now). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 8th 12:00:00 AM, To = 11th 11:59:59 PM. (Irrespective of the month & year) | |
| in the next | N days | Stored value is From = Start of the day (Now), To = End of day(Now + N days). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 11th 12:00:00 AM, To = 14th 11:59:59 PM. (Irrespective of the month & year) | |
## Month of the year - Yearly where the month
Let’s understand these filters' definitions better with examples for the month of the year.
| **Operator** | **Filter Value** | **Explanation** |
| - | - | - |
| is this month | -- | Stored value is From = Start of month(Now), To = End of month(Now) Example: If Now = 4:30 PM, 11 Jan 2001. From = 1st Jan 12:00:00 AM To = 31st Jan 11:59:59 PM (Irrespective of the year) |
| in the following | -- | The month value of the stored date matches one of the filter months. |
| on | month | Stored value is From = Start of month(Month), To = End of month(Month) Month is the filter month. Example: If selected Month = May. From = 1st May 12:00:00 AM To = 31st May 11:59:59 PM (Irrespective of the year) |
| | months ago | Stored value is From = Start of month(Now - N months), To = End of month(Now - N months) N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 1st Oct 12:00:00 AM, To = 30th Oct 11:59:59 PM. (Irrespective of the year) |
| | months from now | Stored value is From = Start of month(Now + N months), To = End of month(Now + N months). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 1st Apr 12:00:00 AM, To = 30th Apr 11:59:59 PM. (Irrespective of the year) |
| In between | month | Stored value is From = Start of month(Month 1), To = End of month(Month 2). Month1 & Month2 are the start and end months respectively. Example: If Month1 = March, Month2= October. From = 1st Mar 12:00:00 AM, To = 30th Oct 11:59:59 PM. (Irrespective of the year) |
| | month ago | Stored value is From = Start of month(Now - N2 months), To = End of month(Now - N1 months). N1 & N2 are the first and second filter values respectively. Example: If Now = 4:30 PM, 11 Jan 2001, N1 = 4 & N2 = 7. From = 1st Jun 12:00:00 AM, To = 30th Sep 11:59:59 PM. (Irrespective of the year) |
| | month from now | Stored value is From = Start of month(Now + N1 months), To = End of month(Now + N2 months). N1 & N2 are the first and second filter values respectively. Example: If Now = 4:30 PM, 11 Jan 2001, N1 = 4 & N2 = 7. From = 1st May 12:00:00 AM, To = 31th Aug 11:59:59 PM. (Irrespective of the year) |
| in the last | n months | Stored value is From = Start of month(Now - N months), To = End of month(Now). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 1st Oct 12:00:00 AM, To = 31th Jan 11:59:59 PM. (Irrespective of the year) |
| in the next | n months | Stored value is From = Start of month(Now), To = End of month(Now + N months). N is the filter value. Example: If Now = 4:30 PM, 11 Jan 2001 & N = 3. From = 1st Jan 12:00:00 AM, To = 30th Apr 11:59:59 PM. (Irrespective of the year) |
## Date-Month of the year - Yearly where the date
Let’s understand these filters' definitions better with examples for the date month of the year.
| **Operator** | **Filter Value** | **Explanation** | |
| - | - | - | - |
| is today | -- | Stored value is From = Start of day(Now), To = End of day(Now) Example: If Now = 4:30 PM, 11 Jan 2001. From = 11th Jan 12:00:00 AM, To = 11th Jan 11:59:59 PM. (Irrespective of the year) | |
| on | date month | Stored value is From = Start of day(Date-Month), To = End of day(Date-Month). Example: If Date-Month = 04 May. From = 4th May 12:00:00 AM, To = 4th May 11:59:59 PM. (Irrespective of the year) | |
| | days ago | Stored value is From = Start of day(Now - N days), To = End of day(Now - N days) N is the filter value. Example: If Now = 11 Jan 2001, 4:29 PM & N = 3. From = 8th Jan 12:00:00 AM, To = 8th Jan 11:59:59 PM. (Irrespective of the year) | |
| | days from now | Stored value is From = Start of day(Now + N days), To = End of day(Now + N days). N is the filter value. Example: If Now = 11 Jan 2001, 4:29 PM & N = 3. From = 14 Jan 12:00:00 AM, To = 14 Jan 11:59:59 PM. (Irrespective of the year) | |
| In between | day | Stored value is From = Start of day(Date-Month1), To = End of day(Date-Month2) Date-Month1 & Date-Month2 are the starts and end days respectively. Example: If Date-Month1 = 03 March, & Date-Month1 = 10 October. From = 3rd Mar 12:00:00 AM, To = 10th Oct 11:59:59 PM. (Irrespective of the year) | |
| | days ago | Stored value is From = Start of day(Now - N2 days), To = End of day(Now - N1 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 11 Jan 2001, 4:29 PM. N 1 = 4 & N2 = 7. From = 4th Jan 12:00:00 AM, To = 7th Jan 11:59:59 PM. (Irrespective of the year) | |
| | days from now | Stored value is From = Start of days(Now + N1 days), To = End of days(Now + N2 days). N1 & N2 are the first and second filter values respectively. Example: If Now = 11 Jan 2001, 4:29 PM. N 1 = 4 & N2 = 7. From = 15th Jan 12:00:00 AM, To = 18th Jan 11:59:59 PM. (Irrespective of the year) | |
| in the last | N days | Stored value is From = Start of days(Now - N days), To = End of days(Now). N is the filter value. Example: If Now = 11 Jan 2001, 4:29 PM & N = 3. From = 8th Jan 12:00:00 AM, To = 11th Jan 11:59:59 PM. (Irrespective of the year) | |
| in the next | N days | Stored value is From = Start of days(Now), To = End of days(Now + N days). N is the filter value. Example: If Now = 11 Jan 2001, 4:29 PM & N = 3. From = 11th Jan 12:00:00 AM, To = 14th Jan 11:59:59 PM. (Irrespective of the year) | |
# Array Filters
Two types of array filters are available.
Array filters are not supported for:
1. Entire Analytics Suite
2. Preference management, Conversion goals, and Personalization attributes
## Array of Strings
Description for array filters for string -
| Filter Name | **Explanation** |
| - | - |
| (any of) is | Any of the stored values is an exact match for at least one of the filter values. |
| (all of) is | All of the stored values of the array match all the filter values. |
| (any of) is empty | At least one of the stored values of the array is an empty string. |
| (all of) is empty | All of the stored values of the array are empty strings. |
| is not | All stored values of the array do not match any of the filter values. The filter is applied to all the values of the attribute, including the values that are not available (The Key is not set). |
| is not empty | The stored value is not empty. String instance has a length greater than 0. The Filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
| exists | The stored value is present. This includes all values including Empty Array and N/A. Filter users or events where the stored value exists (Key is set). |
| contains | All of the stored values of the array contain all the filter values. |
| does not exist | The stored value is not present. The filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
| (any of) contains | One of the stored values of the array contains the filter value. |
| (all of) contains | All of the stored value contains filter value |
| does not contain | All of the stored value does not contain filter value. The filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
| (any of) starts with | Any of the stored values start with the filter value. |
| (all of) starts with | All of the stored value starts with the filter value. |
| does not start with | All of the stored does not start with the filter value. The filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
| (any of) ends with | Any of the stored values end with the filter value. |
| (all of) ends with | All of the stored value ends with the filter value. |
| does not end with | All of the stored does not end with the filter value. The filter is applied to all the values of the attribute including the values that are not available (The Key is not set). |
## Array of Numbers
Description for array filters for numeric values -
| Filter Name | **Explanation** |
| - | - |
| (any of) is equal to | Any of the stored values is an exact match for at least one of the filter values. |
| (all of) is equal to | Stored values are an exact match for all the filter values. |
| is not equal to | Any of the stored values is not a match to any of the filter values. The filter is applied to all the values of the attribute, including the values that are not available (The Key is not set). |
| (any of) is between | One of the stored values of the array is a match between the first filter value and the second filter value. N1 \<= at least one of the stored values of the array AND the same value is \< N2. N1 & N2 are the first and second filter values respectively. |
| (all of) is between | All of the stored value of the array is a match between the first filter value and the second filter value. N1 \<= all stored values of the array AND all stored values of the array \< N2. N1 & N2 are the first and second filter values, respectively. |
| is not between | None of the stored values of the array matches between the first filter value and the second filter value. N1 > all stored values of the array OR all stored values of the array >= N2. N1 & N2 are the first and second filter values, respectively. |
| (any of) is less than | One of the stored values of the array is lesser than the filter value. |
| (all of) is less than | All of the stored values of the array are lesser than the filter value. |
| (any of) is greater than | One of the stored values of the array is greater than the filter value. |
| (all of) is greater than | All of the stored values of the array are greater than the filter value. |
| exists | The stored value is present. This includes all values, including Empty Array and N/A. Filter users or events where the stored value exists (Key is set). |
| contains | The stored value contains one of the filter values. |
| does not exist | The stored value is not present in the filter value (Key not set). |
# Attribute Comparison
You can now compare a user property to another *user attribute* or a *constant value*.\
The following table lists the filters and data types supporting attribute comparison:
| Data Type | Filters supporting attribute comparison |
| - | - |
| String | is, is not |
| Boolean | is, is not |
| Date | On, before, after, in the next, in the last **Note**: MoEngage only matches the date and not the exact time stamp for date data types. |
| Number | is equal to, is not equal to, is greater than, is less than |
| Array of Strings | (any of) is, (all of) is, is not, (any of) contains, (all of) contains, does not contain, (any of) starts with, (all of) starts with, does not start with, (any of) ends with, (all of) ends with, does not end with |
| Array of Numbers | (any of) is equal to, (all of) is equal to, is not equal to, (any of) is less than, (all of) is less than, (any of) is greater than, (all of) is greater than |
## Attribute to Attribute Comparison
You can now compare a user property of a specific data type with another user property of the same data type.
**Example 1**: Consider a marketer looking to identify users who haven't used their app since installing it. Comparing the **First Seen** and **Last Seen** user properties of users can help the marketer identify the users who haven't been active on the app since installation.

**Example 2**: Consider a bank entity looking to identify customers with outstanding loans. For every customer, **outstanding_loan_amount** and **loan_amount_paid_till_date** are user properties that represent the total loan amount disbursed and the total loan amount paid by the customer to date. To identify the segment of users with an outstanding loan, the bank can compare these user properties, as in the following example.

## Attribute to Constant Value Comparison
You can now compare a user property to a predefined constant value.
**Example 1**: Consider an E-commerce business looking to identify users who have spent more than \$1000 on their platform while upgrading the app. The user property *total_amount_for_upgrade* represents the total amount each user has spent to upgrade the platform to date. To segment users into 'high spenders', the E-commerce business can compare this user property with a constant value of 1000 as shown below:

# Limitations
The following features currently do not support the new segmentation filters (first/last seen, contains spaces, is empty/not empty, and user property comparison):
* Conversion Goal
* Business Event
* Event Triggered & Dynamic Condition
* Flows
Though the new filters are not available in the above features, custom segments employing the new filters can still be created from the **Create segment** page and used in the features described above. In the upcoming phases, we will plan to support new filters for all the features in the dashboard.
# Frequently Asked Questions (FAQs)
> [accordion] What is the difference between "Is Empty" and "Does Not Exist"?
>
> The difference is between a **missing field** and a **blank value**.
>
> * **Does Not Exist**: The attribute key was never created or tracked for the user (for example, a "Loyalty_ID" field is completely missing from User A's profile).
> * **Is Empty**: The attribute key exists on the profile, but the value stored is an empty string (for example, User B has a "Loyalty_ID" field, but it contains no text: "").
> [accordion] What's the best way to find accurate users who have a specific attribute with an actual, non-empty value?
>
> To ensure you target users with genuine data, you should always combine the **Exists** and **Is Not Empty** operators using AND logic. This prevents the system from accidentally including users who simply don't have the attribute at all.
>
> * **Example:** To find users with a valid phone number, use: (Phone Number EXISTS) AND (Phone Number IS NOT EMPTY)
> * **Why this works:** Exists confirms the field is on the profile, and Is Not Empty ensures that the field isn't just a blank string.
# Object Data Type in Segmentation
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/object-data-type-in-segmentation
Segment users using object data types in MoEngage, with support for nested attributes and structured queries on complex user and event properties.
# Overview
> [!NOTE]
>
> This is an Early Access feature. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Segmentation provides a structured and organized approach to identifying and querying attributes within an object. This enables effective analysis and decision-making based on the characteristics of the object. For more information, refer to [Support for Object Data Type](/docs/user-guide/data/key-concepts/support-for-object-data-type).
* On the **Create segment** page of the MoEngage dashboard, the user segmentation capability of an object data type is displayed under the **User property** and **User** **behaviour** tabs of **Select audience** section.
* Segmentation supports up to two levels of nesting for an array of objects. Above level two nesting, the attributes are shown in a stringified format.

* In case of an *array of object data* type attributes, segmentation will provide the **With** operator and the **And** operator for advanced querying.
# Create Segmentation Queries with Objects
The attributes of an object can be of any primitive data type. This section provides few examples of writing segmentation queries for user property and event property scenarios using the following data types:
## Query String Attributes
### User Property
If you want to segment users who have pet dogs, you can use the string data type *Animal.pets* and the operator *is* to fetch users who have a dog as their pet.

### Event Property
If you want to segment users who have *Adopted a pet* at least once in the last 3 days with attributes such as Membership (String data) as *Gold* and users having a pet as *Cat* (Object data).
Description:\
Here, Membership is an event property with a string data type and *Pets.species* is another event property with a string Object data type. The **And** operator ensures that the users fetched from the database have fulfilled both conditions.

## Query Empty String Values Using Segmentation
If you want to segment users who have an empty string value for a specific attribute. The stored value is "" (The key is set, but the value is null).
Description:\
Here, *ListOfPets* is an object with *Name* as a user property inside it. Thus in the query, the *ListOfPets.Name* attribute is used with the *is empty* filter.

## Query Numeric Attributes
### User Property
If you want to segment users who have pets younger than 6 years.
Description:\
Here, *Pets.age* is the user property with a numeric data type and *less than* is the relational operator to filter users with pets aged less than 6.

### Event Property
If you want to segment users who have purchased a t-shirt that costs \$500.
Description:\
Here, the **User behaviour** drop-down displays the Object attribute *product.price* and the value as \$500. The segmentation query has the following event properties:
* *Product.Colour* as the attribute with string data type
* *Product.Price* as the Object attribute with numeric data type
* *Product.Currency* as the Object attribute with string data type

Example Code
```json wrap theme={null}
[
{ product: “t-shirt”, price: “$500”, colour: “red”, currency: “USD” },
{ product: “trouser”, price: “$800”, colour: “white”, currency: “EUR” },
{ product: “t-shirt”, price: “$300”, colour: “blue”, currency: “EUR” }
]
```
## Query Date Time Attributes
### Event Property:
If you want to segment users who have purchased a red t-shirt whose price is \$500 and whose purchase date is before 30 May 2024,
Description:\
Here, the segmentation query has the following Object event properties:
* *Colour* is an event property with string data type Red.
* *Product.Price* is an event property with string data type.
* *Product.Purchase-date* is an event property Object of date data type

Example Code
```json wrap theme={null}
[
{ product: “t-shirt”, price: “$500”, colour: “blue”, purchase-date: “23-12-2023” },
{ product: “trouser”, price: “$800”, colour: “white”, purchase-date: “23-12-2023” },
{ product: “t-shirt”, price: “$300”, colour: “red”, purchase-date: “23-12-2023” }
]
```
## Query Array Attributes
### Event Property
If you want to segment users whose dogs were vaccinated at least 1 time in the last 60 days, breed as *Lab*, age under 5 years, and *bone* as their favourite treat.

Example Code
```json wrap theme={null}
Pets object array:
[
{ species : “Dog”, vaccinated: “Yes”, Age : 2, treats : [‘bone’, ‘candy’, ‘pedigree’] },
{ species : “Cat”, vaccinated: “Yes”, Age : 2, treats : [ ‘candy’, fish] },
{ species : “Dog”, vaccinated: “No”, Age : 4, treats : [‘bone’, ‘pedigree’] }
]
```
## Query Nested Objects
### Event Property
If you want to segment users who have purchased a book whose price is 300 USD.

Example Code
```json wrap theme={null}
[
{
"item-id" : 123,
"item-type" : "books",
"item-cost" : { "amount" : 100, "currency" : "USD" }
},
{
"item-id" : 456,
"item-type" : "fruits",
"item-cost" : { "amount" : 200, "currency" : "USD" }
},
{
"item-id" : 678,
"item-type" : "books",
"item-cost" : { "amount" : 140, "currency" : "USD" }
}
]
```
The **Query Results** section in the **Create segment** page displays the history of all queries executed on the dashboard. For each query, you can find the details such as **Query Time**, **Description**, **Source**, **User Count**, and **Reachable Users**.
# Functionality of the “With” Operator
You can use both “With” and AND/OR operators to create queries using the Object data type. The AND/OR operator applies the attribute filters across the objects, whereas the With operator applies the attribute filters within an object.

## Using the With Operator
Consider the following pet object data type as an example of using the With operator to achieve some uses cases below.
Pets Object
```json wrap theme={null}
[
{ Breed: “Lab”, Age: “3”, Treat: “Bone” },
{ Breed: “Lab”, Age: “5”, Treat: “Fish” },
{ Breed: “Bulldog”, Age: “3”, Treat: “Pedigree” }
]
```
### Example 1
If you want to segment users whose dogs were vaccinated 3 times in the last 60 days, whose dogs should be of the breed *Lab*, with their dogs' age less than 5 years old, and with the dog's favourite treat being *Bone*, using the **With** operator:
To achieve this use case, break down the query as listed below:
* Find the users whose pets are dogs of breed *Lab*
* Amongst the Lab breed, find those dogs whose age is \< 5 years
* Amongst the Lab breed of \< 5 years, find those dogs whose favourite treat is *Bone*

Here, the **with** operator will first search for a parent attribute (in the example above - it is pets.age) and then apply the filter to its child attributes (in this case - pets.treat).
This query will return the user mentioned above because in the array of objects, there is a Lab whose age is \< 5 with their favourite treat as Bone.
### Example 2
If you want to segment users whose dogs were vaccinated 3 times in the last 60 days, whose dogs are of the breed *Lab*, with their dog age less than 5 years old, with whose dog’s favourite treat is *Fish*.

This query **will not return** any user mentioned above because though there is a Lab with age \< 5 years, their favourite treat is not Fish. Simultaneously, there is a Lab breed whose favourite treat is Fish, but its age is not less than 5. Thus, this user will not be returned during segmentation.
## Using the And Operator
Consider the following pets object data type as an example of using the And operator to achieve some of the use cases below
Pets Object
```json wrap theme={null}
[
{ Breed: “Lab”, Age: “3”, Treat: “Bone” },
{ Breed: “Lab”, Age: “5”, Treat: “Fish” },
{ Breed: “Bulldog”, Age: “3”, Treat: “Pedigree” }
]
```
### Example 1
If you want to segment users whose dogs were vaccinated three times in the last 60 days, whose pets are dogs of breed *Lab* AND users with pets whose age is > 3 years AND users whose pets have their favourite treat as *Fish*.
This query will return those users who:
* Have pets that got vaccinated 3 times in the last 60 days
* Have pets that are dogs of breed *Lab*
* Have any pets whose age > 3 years
* Have any pets with their favourite treat as *Fish*
Thus, the given user will be returned during segmentation because somewhere in the entire array of objects, there is a Lab-breed pet, and some pets are older> than 3 years. Also, some pets have Fish as their favorite treat. Thus, all three conditions are satisfied independently, as required in the case of the AND condition.
## Using the OR Operator
Consider the following pets object data type as an example of using the OR operator to achieve some of the use cases below
Pets Object
```json wrap theme={null}
[
{ Breed: “Lab”, Age: “3”, Treat: “Bone” },
{ Breed: “Lab”, Age: “5”, Treat: “Fish” },
{ Breed: “Bulldog”, Age: “3”, Treat: “Pedigree” }
]
```
### Example 1
If you want to segment users whose dogs got vaccinated three times in the last 60 days, whose pets are dogs of breed *Lab* OR users with pets whose pets have age is > 3 years OR users whose pets have their favorite treat as *Duck*.

This query will return the user mentioned above because it fulfils the definition of the **OR** operator (which says that at least one of all the conditions must be fulfilled). In this case, only favorite treat condition = *Duck* is not fulfilled, but the other two conditions are fulfilled, which will return the user above during segmentation.
> [!NOTE]
>
> Using the **With** operator, the user will see the attributes with the same nesting level as in the previous field. Other nesting level attributes will not be displayed to maintain consistency. You can use the **And** operator to achieve this use case.
>
> 
# Query Across Nested Array of Objects
> [!NOTE]
>
> This is an Early Access feature. To get it enabled for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
For data structures where an array of objects is nested within another array of objects (up to two levels), you can perform advanced segmentation by creating queries that span across both levels. This allows you to find users based on a combination of attributes from the parent (level 1) array and the nested (level 2) array within the same object element.
When you select an attribute from a nested (level 2) array, the segmentation UI provides two "With" operators.
* The first "With" operator, which is indented, lets you add more conditions for attributes at the same nested level (level 2).
* The second "With" operator lets you add conditions for attributes at the parent level (level 1).
### Example
Consider a user property "nations," which is an array of objects. Each nation object contains details like name and population, as well as a nested array of objects called "cities." Each city object in turn contains its own attributes.
Nations Object Example
```json wrap theme={null}
{
"nations": [
{
"name": "India",
"capital": "New Delhi",
"population": 1.4,
"date": "2025-06-04T00:00:00Z",
"bool_attr": true,
"array_strr": ["one", "two", "three"],
"array_number": [1, 2, 3],
"last_level": { "key1": "value1", "key2": 123 },
"cities": [
{
"name1": "Mumbai",
"population1": 20,
"landmarks1": ["Gateway of India1", "Chhatrapati Shivaji Maharaj Terminus"],
"date1": "2025-06-04T00:00:00Z",
"bool_attr1": true,
"array_strr1": ["one", "two", "three"],
"array_number1": [1, 2, 3],
"last_level1": { "key1": "value1", "key2": 123 }
},
{
"name1": "Bengaluru Urban",
"population1": 8,
"landmarks1": ["Vidhana Soudha", "Lal Bagh"],
"date1": "2025-06-04T00:00:00Z",
"bool_attr1": true,
"array_strr1": ["one", "two", "three"],
"array_number1": [1, 2, 3],
"last_level1": { "key1": "value1", "key2": 123 }
}
]
},
{
"name": "India",
"date": "2025-06-04T00:00:00Z",
"bool_attr": false,
"capital": "New Delhi",
"population": 1.4,
"array_strr": ["one", "two", "three"],
"array_number": [1, 2, 3],
"cities": [
{
"name1": "Bengaluru Rural",
"population1": 7,
"landmarks1": ["Vidhana Soudha", "Lal Bagh"],
"date1": "2025-06-04T00:00:00Z",
"bool_attr1": true,
"array_strr1": ["one", "two", "three"],
"array_number1": [1, 2, 3],
"last_level1": { "key1": "value1", "key2": 123 }
}
]
},
{
"name": "Japan",
"date": "2025-06-04T00:00:00Z",
"bool_attr": true,
"capital": "Tokyo",
"population": 125,
"array_strr": ["one", "two", "three"],
"array_number": [1, 2, 3],
"cities": [
{
"name1": "Tokyo",
"population1": 37,
"landmarks1": ["Tokyo Skytree", "Shibuya Crossing"],
"date1": "2025-06-04T00:00:00Z",
"bool_attr1": true,
"array_strr1": ["one", "two", "three"],
"array_number1": [1, 2, 3],
"last_level1": { "key1": "value1", "key2": 123 }
},
{
"name1": "Kyoto",
"population1": 1.5,
"landmarks1": ["Kinkaku-ji", "Fushimi Inari-taisha"],
"date1": "2025-06-04T00:00:00Z",
"bool_attr1": true,
"array_strr1": ["one", "two", "three"],
"array_number1": [1, 2, 3],
"last_level1": { "key1": "value1", "key2": 123 }
}
]
}
]
}
```
Now, let's create a segment of users for whom a nation has a population of over 1 billion, and within that same "nation" object, there is a city with a population greater than 10 million.
1. On the **Create Segment** page, click the **User property** tab.
2. Start by filtering for the attribute: `nations.population` is greater than 1
3. An indented "With" operator appears. You could use this to add another condition on a city attribute, such as `nations.cities.name1`.
4. A second "With" operator appears below the first. Use this to add the condition for the level 1 attribute: `nations.cities.population1` is greater than 10.

This query uses the "With" operator to ensure both conditions are met within the same "nations" element. It will find users associated with the "India" object because its population is over 1 billion (represented as 1.4), and it contains a city ("Mumbai") with a population over 10 million (represented as 20). The "Japan" object would be excluded because its national population is less than 1 billion.
# Considerations for Object Data Type
While object data types offer powerful segmentation capabilities, it's important for you to be aware of their current scope within MoEngage. Understanding them will help you plan your data ingestion strategies and know what can be achieved with object-based segmentation.
* **File uploads**: The object data type is currently not supported in the *File segment* upload feature.
* **User exports**: User export through CSV does not support object user properties. When exporting user data, object attributes will not be included in the CSV.
* **Aggregation support**: Aggregation of an array of objects is not supported. However, aggregation of individual objects and nested objects (that are not arrays) is supported.
* **Attribute comparison**: Object-to-object attribute comparison is not supported in user property comparison. However, object-to-primitive attribute comparison (for example, comparing a value within an object to a simple string or number) is still supported.
* **Features without object data support**: The following MoEngage features currently do not fully support object data types:
* Custom segment filter based public API
* Segment payload generator
* App marketplace (Custom destination for Sync segment)
* Real-time segmentation
* User affinity (when defined directly on object attributes)
For scenarios requiring object data in these unsupported features, consider transforming your data into simpler, primitive types before ingestion.
# FAQs
> [accordion] What happens if I send different data types, like an object and a string, for the same attribute?
>
> If multiple data types are ingested for the *same* attribute, MoEngage automatically prioritizes and chooses the *first* data type it encounters for querying. It is not possible to query the second data type value for that attribute.
>
> **Workaround:** To query both an object and an array of object values for similar data, we recommend using two separate attributes in your data ingestion. Configure each as an object in data management, and pass the object values into one attribute and the array of object values into the other. This ensures both can be queried independently.
> [accordion] Are value suggestions available for object data type attributes when creating a segment?
>
> Yes, Value Suggestions are now supported for object data type attributes. When creating a segment, you can search for specific values within an object. Value suggestions for object data follow the same rules for generation as primitive data types. For more information, refer [here](/docs/user-guide/segment/advanced-concepts/value-suggestions).
# Real-Time Segment Evaluation
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/real-time-segment-evaluation
Trigger campaigns the moment users qualify for a segment with real-time segment evaluation, instead of waiting for periodic segment refresh cycles.
# Overview
Real-time segment evaluation (RTSE) allows you to engage your audience based on their demographics, behavior, and interests the moment they perform a key action. It enhances your ability to send timely, relevant campaigns and provide recommendations based on user behavior as it happens.
This contrasts with periodic segments, which refresh on a set schedule. While periodic segments are powerful for broad audience analysis, RTSE is designed for immediate, action-based marketing.
# How Real-Time Segment Evaluation Works
Understanding the mechanism of RTSE helps clarify its power. The process is designed to be instantaneous:
* **User action:** A user performs a trigger event on your app or website (for example, adds an item to their cart, views a specific product, or completes a sign-up).
* **Real-time evaluation:** MoEngage immediately checks if this user qualifies for your campaign's audience criteria based on this new action and their recent behavior.
* **Campaign trigger:** If the user qualifies, the campaign is triggered instantly.
This ensures your message is delivered at the moment of highest relevance, rather than hours after the user's action when the opportunity may have passed.
> [!NOTE]
>
> A workspace can have up to **10 active real-time segments** at a time and can register up to **10 new real-time segments per day**. If you exceed the active-segment limit, new campaigns or flows that use a real-time segment fail to launch. To raise these limits, contact Support.
## Periodic Refresh Intervals
When a segment is not evaluated in real time, MoEngage refreshes it on a schedule. The interval depends on the campaign type:
| Campaign Type | Approximate Refresh Interval |
| - | - |
| Event Triggered campaigns and Flows | 3 hours |
| Inbound channels (In-App, On-Site Messaging, and Cards) | 6 hours |
Between refreshes, segment membership is applied as of the last refresh. This affects both entry and exclusion: a user who starts qualifying is not targeted until the next refresh, and a user who was just sent a campaign can receive it again if they perform the trigger event before the next refresh. For more information, refer to [Create an Event-Triggered Campaign](/docs/user-guide/campaigns-and-channels/getting-started/triggers/event/create-an-event-triggered-campaign) and [Event Triggered Flows](/docs/user-guide/flows-cross-channel-messaging/faqs/event-triggered-flows).
## Advantages of RTSE
* **Improved retention rate**: Real-time segmentation allows businesses to target specific groups of customers based on their behavior, preferences, or past interactions. This personalized approach, combined with real-time segmentation, can lead to higher engagement and user retention.
* **Timeliness**: Real-time segmentation enables businesses to send targeted campaigns at the right moment, such as when a user is browsing a website, adding items to their cart, or reaching a milestone. This timeliness can increase the chances of capturing the user's attention and prompting them to take action.
* **Relevance**: By segmenting users in real-time, businesses can ensure that the campaigns they send are relevant to the individual's current interests or needs. This relevance can enhance the user experience and make the campaign more likely to resonate with the recipient.
* **Improved conversion rate**: Real-time segmentation allows businesses to target users with highly relevant and timely offers, increasing the likelihood of conversions. By reaching users at critical moments in their customer journey, businesses can boost conversion rates and drive revenue growth.
## Channels That Support RTSE
* Push
* Email
* SMS
* WhatsApp
* Flows
* On-site Messaging
* In-app Messaging
* Web Personalization
# Use Cases
| Industry | Use Case | Description |
| - | - | - |
| E-commerce | Abandoned cart recovery | RTSE allows you to identify users who have added items to their cart but haven't completed the purchase. You can send a personalized reminder or offer to nudge them towards checkout. |
| | Flash sale notifications | RTSE can target users who have shown interest in such products that are a part of a limited-time sale. It allows you to send them instant push notifications or emails as the sale begins. |
| Travel and hospitality | Last-minute booking deals | RTSE can identify users searching for specific destinations and offer them special last-minute booking deals to boost occupancy rates. |
| | Booking milestone | If a traveler frequently books trips and reaches a certain milestone (for example, the fifth booking), you can run a "thank you" campaign with RTSE, offering a discount or upgrade on their next booking. |
| Retail and quick commerce | In-store purchase follow-up | When a user makes a significant in-store purchase (tracked through a loyalty program), you can trigger an event with RTSE to send a care guide, related accessories promotion, or a satisfaction survey. |
| | Order milestone | A user who has ordered a certain number of times (for example, the tenth order) is added to a real-time segment, triggering a campaign to thank them with a discount or free item on their next order. |
| Entertainment | Content recommendation | OTT platforms could segment viewers based on real-time viewing habits to recommend new episodes or movies instantly. |
| Banking and financial services | Large transaction alert | Users who make transactions above a certain threshold will be segmented in real time and receive an email-triggered campaign to confirm the transaction. |
# Create a Campaign with RTSE
You can leverage RTSE in event-triggered campaigns to target customers with personalized messages based on their actions in real time. For example, if a user updates your application to the latest version, you can instantly communicate the new features and capabilities.
Perform the following steps:
1. On the left navigation of your MoEngage dashboard, click **+ Create new** > **Campaign**.
2. Select any of the [RTSE-supported channels](#channels-that-support-rtse) and choose an **Event triggered** delivery type. For more information, refer to [creating an Event-Triggered Campaign](/docs/user-guide/campaigns-and-channels/getting-started/triggers/event/create-an-event-triggered-campaign).
3. In the **IF user performs** section, select the trigger event, such as *App update*. This is the primary action that will start the evaluation.
4. In the **THEN trigger the message** section, select **Immediately** to send the campaign within seconds of the user's action.

5. In the **Select audience** section, select **Filter users by** and add your segmentation criteria under the **User property** or **User behavior** tabs.
> [!NOTE]
>
> If the segmentation criteria you've chosen are supported by RTSE, you will see a confirmation message directly in the UI:
>
> *"Campaign segments will be evaluated in real-time on the latest data."*
>
> If this message does not appear, your campaign will use periodic segmentation, which refreshes on a regular schedule. For the intervals, refer to [Periodic Refresh Intervals](#periodic-refresh-intervals).

# FAQs
> [accordion] How do I know if my campaign is using RTSE?
>
> While creating your campaign, if the segmentation filters are eligible for real-time evaluation, you will see the following message on the UI: "Campaign segments will be evaluated in real-time based on the latest data.” Note that this indicator is only visible during the creation process and is not displayed on the main campaign dashboard.
> [accordion] Why is RTSE most relevant for Event-Triggered campaigns?
>
> RTSE is designed to react to user actions as they happen. Its core value comes from its ability to evaluate a user's eligibility for a segment at the precise moment they perform a key event (the "trigger"). This makes it a perfect fit for event-triggered campaigns, where timeliness and context are critical for success. For other campaign types that target broader audiences based on historical data rather than immediate actions, periodic segmentation is more suitable.
> [accordion] How should I interpret the 'Reachable Users' count for an RTSE campaign?
>
> When you click **Show count**, you see a snapshot of how many users meet your criteria at that moment. However, the true power of RTSE is that the evaluation happens live for each user who performs the trigger event. This means a user who doesn't qualify now might qualify in an hour after taking an action, and they will then enter the campaign. The count is a helpful estimate, but the actual audience is determined in real time.
> [!NOTE]
>
> The sample users list might show entries with duplicate contact information (for example, the same email ID). MoEngage automatically de-duplicates when sending the campaign, ensuring each unique user receives the message only once.
# Segment Nesting
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/segment-nesting
Combine multiple segment criteria using AND/OR logic and nested conditions in MoEngage to build complex, multi-layered audience targeting rules.
Marketers usually segment users based on multiple criteria such as User Property rules (User Properties), User activity rules (Event Properties), User Affinity rules, and Custom Segments. Most of the time, a combination of multiple criteria using AND or OR conditions is used to create a complex user segment.
For better understanding, let’s say A, B, C, and D represent the ‘segment blocks’, which are events & user properties with all their filters. For example, A can be ‘users who are male’, B can be ‘users who added to cart: wallet in the last 3 days, and so on. You can always create segments like A AND B AND C AND D and A OR B OR C OR D by combining segment blocks using AND/OR operators.

But when a complex segment like ‘(users who are male AND added to the cart: wallet in the last 3 days), OR (users who are female AND added to cart: handbag in the last 3 days)’ is required, it cannot be simply done using just these operators. The reason being either AND, or OR, only one of these will be used to combine these segment blocks. A combination of AND as well as OR cannot be used together. If you change one of the operators in the definition, the rest will automatically change. This is when nesting comes into the picture.
## **What is Nesting?**
When a complex segment like the above example is to be created, we will need to group some of the segment blocks. Logically, if the segment blocks A and B are grouped inside brackets i.e. ‘(A AND B)’, then they are multiple segment blocks ‘nested’ together. So a combination of segment blocks represents the ‘nested blocks’.
With the nested AND/OR capabilities, you can create complex segments with combinations such as:
* (A AND B) OR (C AND D). Here, (A AND B) and (C AND D) are 2 nested blocks combined together with the OR operator.
* (A OR B) AND (C OR D). Here, (A OR B) and (C OR D) are 2 nested blocks combined together with the AND operator.
* (A OR B) AND C AND D. Here, (A OR B) is 1 nested block combined together with 2 other segment blocks C and D using the AND operator.
* (A AND B) OR C OR D. Here, (A AND B) is 1 nested block combined together with 2 other segment blocks C and D using the OR operator.

## **Understanding Nesting Levels**
The examples mentioned above have 1 level of nesting. As in, for the complex segment (A AND B) OR (C AND D). In the above example A, B, C, and D have simple definitions using user properties or event properties. Those are not segments, those are simple user properties or event properties.
But when the A, B, C, or D are in itself a nested block or a segment instead of simple definitions, they will have more than 1 level of nesting.
**Actions that increase the nesting level:**
1. **By using a custom segment in a query**: If a custom segment is used in a query it increases the nesting level of query in below way:\
\[Nesting level of that query = nth level of custom segment + 1 Level increase]
2. **By using a nested filter in a query:** If a nested filter is used in a query it increases the nesting level of the query by 1 level

**Note**:
> [!NOTE]
>
> 1. Using the normal filter button to the query will not affect the nesting level. Any custom segment created using this logic will create a custom segment with nesting level 1.
> 2. Adding multiple nested filters to the query will not add to the nesting level by subsequent levels. At least 1 nested filter is sufficient to increase the nesting level by 1.

### Various cases of nesting levels:
| **Custom segment** | **Definition** | **Nesting level** |
| - | - | - |
| Type 1 | Created a segment using attributes (no nested filter) Or Created a segment using attributes and nested filter | Level 1 |
| Type 2 | Created a segment using only 1 custom segment of Level 1/Type 1 | Level 2 |
| Type 3 | Created a segment using 2 linked custom segments (only segments and no nested filters in their definition) - Eg: A -> B -> C, so C will be a Custom Segment of level 3 which has Custom Segment B (Level 2) and Custom Segment A (Level 1) nested/linked inside it. Or Created a segment using a custom segment of Level 1/Type 1 with at least 1 nested filter | Level 3 |
| Type 4 | 1 segment (of Level 2/Type 2) + 1 attribute outside with nested filter | More than 3 level of nesting |
| Type 5 | 2 linked segment inside + 1 attribute outside with nested filter | More than 3 level of nesting |
| Type 6 | Created using 4 linked segment | More than 3 level of nesting |
### Let’s understand this using few examples:
### Case 1: Level 1 Nesting
F is an event “Has executed App Inbox Icon Clicked atleast 1 time in the last 3 days”
G is an event “Email viewed in Browser”
H is an user property “Install status is True”
I is an event “WhatsApp message clicked”

**Here, the nesting level is 1 (one) because:**
1. Any custom segment created only using attributes or nested filter will create a custom segment of Level 1
For example, if a custom segment E is created using these attributes, let’s say with a definition, E = (F AND G) OR (H AND I), the level of nesting for segment E will be 1. Here, the OR is a normal filter and AND is a nested filter.
**OR**
By simply creating a custom segment with an user property or user behavior

The nesting level of the custom segment will be 1 in this case.
Segment F = Nesting level 1
### Case 2: Level 2 Nesting
Let’s say, Segment F = Unsubscribe is False

Using this Segment F (of nesting Level 1) in a query to create another custom segment

**The above query is of nested level 2, the nesting level in this case is defined as:**
1. Nesting level of that query = nth level of custom segment + 1 Level increase
Thus, Nesting level of the above query = Level 1 (Segment F) + 1 Level = Level 2
### Case 3: Level 3 Nesting
**Definition of segment:** F is a custom segment made up of event property “Best time to send Email is between 10 Hrs and 13 Hrs. This will create a custom segment F of nesting level 1.

If this created custom segment F (Seg F - Nesting level 1) is used in the query along with other attributes, as shown below:

**Here the level of nesting for the query is 3 because:**
1. Two level because a custom segment F (of nesting level 1) has been added in the query (Level 1 of custom segment F + 1 Level = Nesting Level 2)
2. Another level - Using nested filter an event property is used that increases the nesting level to 2
If this query is used to create a custom segment, the created custom segment will be of nesting level 3.
**OR**
If you create a custom segment with 2 custom segments inside it, it will create a query of level 3.
Example:
Let’s say, Segment cs_level_1 = Created a custom segment of level 1 using an attribute (Has executed Allowed web Push Subscription atleast 1 time in the last 3 days)

Segment cs_level_2 = Created a level 2 custom segment by adding custom segment cs_level_1 in the query
Level 2 = 1 level of cs_level_1 + 1 level of nesting (as per rule mentioned in the beginning)

Cs_level_3 = Created a level 3 custom segment by adding custom segment cs_level_2 in the query
Level 3 = 2 level of cs_level_2 + 1 level of nesting (as per rule mentioned in the beginning)

### Case 4: > Level 3 Nesting
**Definition of segment**: F is a custom segment made up of user or event properties J, K, L, M and F is used as a custom segment in Segment E’s definition
F is a nested segment defined as - (J OR K) AND (L OR M).
J is an event “Has executed Notification Received Android predominantly with (Device Model is Nexus 5 (case insensitive) ) in the last 3 days”
K is an user property “Best time to send Email is between 10 and 13”
L is an user property “SPAM is false”
M is an user property “Mobile user is True”

In the above image, the query has 2 levels of nesting and if the segment F is created using these filters the nesting level will be 2 (E -> F -> J.)
If the above Custom segment F (Level 2 nesting) is used in a query, it will increase the nesting level of the query to 3. As per definitions above.
Where E = (F and G) OR (H AND I)
So the overall segment E is now defined as - `( {(J OR K) AND (L OR M)} AND G) OR (H AND I)`.

**Here the Level of nesting for the given query is 4 because:**
1. Three levels because a custom segment F (of nesting level 2) has been introduced (Level 2 of custom segment F + 1 Level = Level 3) - as per rule mentioned in the beginning.
2. Another level - Using nested filter an event property is used that increases the nesting level to 4
If this query is used to create a custom segment, the created custom segment will be of nesting level 4. Since MoEngage supports up to 6 levels of nesting, segment E is within the limit and is processed. A custom segment is only rejected when its nesting exceeds 6 levels.

## **How to use nested filters**
Use the '+ Nested Filter' button to add a nested block. To create a segment with more than one level of nesting, you will need to create a custom segment first (segment E in the above example) and then use the custom segment in the filters.
The nested condition will be preselected, opposite to the outer condition. So, if the outer condition is AND, the nested condition will be OR (ex: (A AND B) OR (C AND D)) and vice-versa (ex: (A OR B) AND (C OR D)).
Both the nested as well as the outer conditions can be changed. When the outer condition is changed (let's say, from AND to OR), the nested condition automatically gets updated to the opposite condition (in this case, OR to AND) and vice versa.
Nested AND/OR functionalities are available in segmentation as well as campaign creation pages in the target audience section. They are not supported in Trigger Criteria in Event-triggered campaigns.
A particular user segment can also be excluded from the selected user segment. To use this, click on Exclude user checkbox.
MoEngage supports up to 6 levels of nesting. These combinations offer flexibility in defining specific conditions for segmenting your users.
**Note**:
> [!NOTE]
>
> [File Segments](/docs/user-guide/segment/create-segments/file-segments) are not counted towards the nesting Limits.
## **How to simplify if there are more than 6 levels of nesting?**
Segment queries are logical expressions of conditions. Any logical expression can be simplified into 1 level of nesting. Logical rules can be utilized to simplify it.
Logical rules used to simplify the nesting -
* (X AND Y) AND Z = X AND Y AND Z
* (X OR Y) OR Z = X OR Y OR Z
* (X AND Y) OR Z = (X OR Z) AND (Y OR Z)
* (X OR Y) AND Z = (X AND Z) OR (Y AND Z)
Here is an example of collapsing a multi-nested segment into a single level of nesting. Start with segment blocks `A` and `B` combined as `A AND B`, then expand each block that is itself a segment:
1. `A = C OR D`, so the segment becomes `(C OR D) AND B`.
2. `C = E AND F`, so the segment becomes `((E AND F) OR D) AND B`, which simplifies to `(E OR D) AND (F OR D) AND B`.
3. `E = G AND H`, so the segment becomes `((G AND H) OR D) AND (F OR D) AND B`.
Applying the logical rules above, this simplifies to `(G OR D) AND (H OR D) AND (F OR D) AND B` — a query with a nesting level of 1. Any segment definition can be broken down into a single level of nesting this way.
> [!WARNING]
>
> These rules reduce nesting depth, but they repeat terms — `D` appears three times in the result above — so the query gets longer as it gets flatter. A segment query is serialized before it runs and cannot exceed 256 KB (262,144 characters), which is a separate limit from the 6-level nesting limit. When you flatten a definition that already references several custom segments or filters with long value lists, run the query afterwards to confirm it still returns a count. See [Why Does My Segment Query Fail With a Query Length Error?](/docs/user-guide/segment/faqs-segment/why-does-my-segment-query-fail-with-a-query-length-error)
# Segmentation in a Multi-Project Portfolio
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/segmentation-in-a-multi-project-portfolio
Build cross-project user segments with MoEngage Portfolio by combining data from multiple apps and websites into unified audience targeting rules.
# Overview
With the [*Portfolio*](/docs/user-guide/settings/account/portfolio/portfolio) feature, you can create powerful user segments by combining user data and behaviors from all the different apps and websites (called **Projects**) within your workspace. This allows you to build highly specific audiences for more effective, targeted campaigns.
The primary goal is to enable cross-targeting. For example, you can create a segment of users who are frequent shoppers on your *Grocery* app and then send them a promotional campaign from your *Fashion Retail* app.
## Build a Multi-Project Segment
When you create a segment in a multi-project workspace, the process for filtering users differs slightly depending on whether you are using **User behavior** (events) or **User property**.
1. From the left navigation menu in the MoEngage UI, navigate to **Segment** > **Create segment**. The Create segment page appears.
2. Select **Filter users by**.
3. Click **+ User property** or **User behavior**.
> [!NOTE]
>
> Affinity segments are not supported in Portfolio-enabled workspaces.
4. Before selecting an attribute or event, use the **Select Project** list to choose the specific project you want to filter for.

5. Define the rest of your condition as usual. For more information, refer to [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
6. You can add multiple rules, each targeting a different project, using **AND**/**OR** conditions to build a cross-project segment.

#### Filter by User Behavior (Events)
When you filter by user behavior, the project drop-down menu will list all of your individual projects as well as a global **Portfolio** option.
* **Filtering by a specific project**: To find users who performed an event in a single project, select the specific project from the drop-down list, and then choose the event.
* **Filtering at the portfolio level**: Selecting the *Portfolio* option serves two main purposes:

* **To create an "OR" condition across all projects**: For common events tracked across multiple apps (like *Purchase* or *Added to Cart*), selecting *Portfolio* finds users who performed this action in any of your projects. This is a shortcut that prevents you from having to create a separate rule for each project and combine them with "OR".
* **To access portfolio-only events**: The only campaign events at the project level are for Push Notifications. To segment users based on these other campaign events, you must select *Portfolio*. Certain events are not yet associated with individual projects. Currently, this includes most campaign engagement events (for example, `Email Opened`, `SMS Sent`).
#### Filter by User Property
When you filter by user properties, you must first select a specific project. There is no *Portfolio* option in this list. After you select a project, the attribute list will display both global and project-specific attributes.
* **Global attributes**: These attributes are shared across all projects in your portfolio (for example, `First Name`). They appear without any special label. [Computed traits](/docs/user-guide/data/computed-traits/computed-traits-overview#computed-traits-in-a-multi-project-portfolio) are also global attributes, even when they are built from the events of a single project.
* **Project-specific attributes**: These are attributes associated with a single project (for example, `Last Seen` for a particular app). You can identify them by the project name suffix that appears next to the attribute name, for example, *Last Seen \{Project name}*.

This distinction exists because while all users are stored in a single database, their attributes can be stored either globally or at an individual project level.
### Understanding Reachability
How reachability is calculated depends on where you are in the MoEngage dashboard. Understanding this concept is critical when working with multi-project segments.
#### Reachability in the Segment Builder
When you are on the **Create Segment** page, there is no context for a specific campaign project yet. Therefore, the reachability count shown here is a **Global Reachability** count. A user is considered "globally reachable" if they are reachable on **at least one** of the projects in your portfolio. For example, if a user has a valid push token for Project A but not for Project B, they are still considered globally reachable for push. The count you see reflects the total potential audience across all your projects that matches your rules and is reachable on at least one project.

#### Reachability in Campaign Creation
When you use your segment in a campaign, you must select one specific project to send the campaign from. Thus, the reachability count here becomes project-specific.
When you click **Show Count** in the campaign's **Target Audience** step, you will see two figures:
* **Total Users**: The total number of users who match your segment's rules, across all the projects you defined in your segment.
* **Reachable Users**: The number of users from that total who are specifically reachable for the single project you selected for the campaign.
**Example**: Your segment might find 10,000 users who match your rules across Project A and Project B. However, when you create a Push campaign and target it *only* to Project A, the final "Reachable Users" count might show 4,000 because it only includes users from the segment who have a valid push token for Project A.
### Custom Segments
When you save a segment, it is stored at the **Portfolio** (workspace) level. It is not associated with any single project and can be used in campaigns for any of your projects.
### Dynamic Attribute Comparison
You can create advanced segments by comparing attributes between different projects.
* **User property comparison**: Compare a user property from one project to an attribute from another project.
*Example*: Find users where `Project A - Loyalty Tier` is equal to `Project B - Loyalty Tier`.
* **Event property comparison**: Compare an event property from one project to an event property from another project.
For example, target users who triggered the *Add to Cart* event in `Project B`, where the `Category` attribute matches the `Category` from their *Purchase* event in `Project A`.
### How This Affects the User Profile
On the **Activity Info** tab of a user's profile, you will see a combined feed of all events performed by that user across all projects. There is no filter to view activities for a single project. However, each event will have a **Project** attribute to show you which app or website the action came from.
# Value Suggestions
Source: https://moengage.com/docs/user-guide/segment/advanced-concepts/value-suggestions
Speed up segment creation with value suggestions that auto-populate event and user property values as you build queries on the MoEngage dashboard.
Value Suggestions is a small but very useful feature for MoEngage dashboard users. Value suggestions are the exact values present in an event property or user property, which are shown to the users while creating segments or performing any analysis, so users do not have to remember long attribute names and can directly select the value from the suggested ones.
For example, when the user selects the campaign name as an event property, the MoEngage dashboard displays the list of campaigns. If the list is too long, type the value and shorten the suggested list.

## **Suggestions Criteria**
* Suggestions are provided for all attributes, except for date values which must be selected from drop-down menus. String and numeric values are eligible for suggestions, while boolean values offer a default selection dropdown for true or false.
* For event properties, data becomes available in the value suggestions one day after they are received. Similarly, for user properties, data becomes available in the value suggestions two days after they are received.
* If an event property or user property receives no values for 60 days, MoEngage removes all value suggestions for that attribute. Any value that arrives for the attribute, including a value already in its suggestions, resets this 60-day period. While the attribute keeps receiving data, its existing suggestions stay, even values last received more than 60 days ago. New values are added to the suggestions and don't cause older values to be removed until the attribute reaches the 5,000-suggestion limit.
* Suggestions reflect the data type each value was ingested as. After you change the [allowed data type](/docs/user-guide/settings/data-management/overview-data-management#set-allowed-data-types) of an attribute, suggestions for values already stored under the previous data type keep appearing. They're removed when new values replace them after the attribute reaches the 5,000-suggestion limit, or when the attribute receives no values for 60 days. Seeing suggestions for both data types does not mean the change failed to apply.
* Only values upto **100 characters** are supported in value suggestions. If the values have more than 100 characters they will be dropped and won't be visible in value suggestions.
* MoEngage generates value suggestions daily at 12:30 AM UTC based on the previous day's data. For backdated ingestion (data occurring in the past but uploaded to MoEngage today), suggestions are derived from the four most recent days of that specific event, provided the data is no older than 60 days.
> [!WARNING]
>
> Backdated ingestion does not support previous-day (T-1) data. The daily 12:30 AM UTC job processes the previous day's events; once it runs, the backdated flow skips that day.
>
> If your daily import carries yesterday's events and lands after 12:30 AM UTC (common with periodic SFTP imports), MoEngage does not generate or backfill value suggestions for those events.
* ***MoEngage does not show value suggestions for:***
* **Naming Conflicts** - Custom events or user properties whose names conflict with MoEngage reserved names will not be considered for generating value suggestions, e.g., *appVersion, sdkVersion, os, and user_id.*
* A maximum of 5,000 suggestions are generated for each attribute. After an attribute reaches this limit, new values replace older ones.
* You can select a maximum of 1000 values to filter the attribute value.

If you select more than 1000 values, you cannot continue the query. If you click **Show count**, an error message is displayed in the lower right corner.

* If you select the condition "in the following", you can select multiple values. Use the **Value suggestions** checkbox to select multiple values. For example, if there are 5000 values, you can select the first 1000 values.

* Click **Select all** to select all values. For example, if there are 5000 values, you can select the first 1000 values. Click **Clear all** to clear all the selected values.

* You can see all the results/suggestions (a maximum of 5000) as soon as you focus on the input field. Enter the first few characters of the value you wish to search and get the list of values. For example, you see many value suggestions when you enter "Bro":

If the list is still long, enter more characters until you find your desired value. Continuing with the previous example, when you enter "Brooke", you will see an exact match in value suggestions:

* When you enter comma-separated values, for example, "John, Harry":
* They are listed as a single value "John, Harry" under a new category **Freeform**.
* They are listed as separate values "John" and "Harry" under the **Newly created** category.

> [!NOTE]
>
> For comma-separated values, MoEngage does not show Value Suggestions.
* When you paste a large number of comma-separated values, for example, 200 values:
* You will see a single value under a new category **Freeform**.
* You will see 200 separate values under the **Newly created** category.
* For masked PII attributes, MoEngage does not show value suggestions even if you enter values that have matching suggestions. For example, if Email ID is a PII attribute and you enter an email ID in the input field, you will not see any value suggestions.
* If you close the input box after selecting a few values, you can still search for new values. When you enter a new value, MoEngage searches for it from both **Selected Items** and **Value Suggestions** and shows the matching values and newly created values. If the value is an exact match, MoEngage does not show the **Newly Created** value.

# Affinity Segments
Source: https://moengage.com/docs/user-guide/segment/create-segments/affinity-segments
Target users based on their preferences and behavioral patterns with MoEngage Affinity Segments. Analyze traits like content interests and app habits.

**Affinity Segments**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3129283-affinity-segments)
Affinity Segments allow you to choose and target your users based on their personalities, lifestyles, beliefs, and choices (as displayed within your app). This will help you optimize your campaigns by sending them messaging that addresses their needs.
With Affinity Segments, you can analyze personality traits to understand your users better. For example, you can:
* View users who listen to Madonna’s albums more often than any others, so you can recommend a similar album
* Filter users who book cab rides from your app between 10 AM to 12 PM at least 40% of the time, so you can send more coupons to them around that time period
* Find the bottom 20% of users who book hotels on a weekday, and send them discounts to incentivize weekend bookings
* View the top 10% of users who read political news to recommend better articles for them on your app
Affinity Segments help you filter user traits, positive or negative, and use the data to send campaigns that are more likely to resonate with them.
To create an Affinity Segment,
1. Navigate to the MoEngage Dashboard **Segment** on the sidebar
2. Click on **Create Segments**.\
The Create Segments page is displayed.

3. Click User Affinity and select the event from the drop-down list.
4. From the drop-down list, select one of the following affinity filters:
1. Predominantly
For more information, refer to [Predominantly](#predominantly).
2. Minimum of
For more information, refer to [Minimum of](#minimum-of).
3. Most no. of times
For more information, refer to [Top users or Bottom users](#top-users-and-bottom-users).
4. Least no. of times
For more information, refer to [Top users or Bottom users](#top-users-and-bottom-users).
5. Select the attributes used with the affinity filter.
6. Click **Show Count** to show the count of users in the affinity segment.
# Affinity Filters
## Predominantly
Any user that performs a certain action (from the selected attribute values) more times than all other attribute values is said to perform the action predominantly.
For instance, a user has bought 10 books through your e-commerce app, out of which 5 are thrillers, 3 are biographies, and 2 are self-help. In this case, the predominant genre is thrillers. Another user, who has purchased 25 books, could have 15 books in the thriller genre, 4 biographies, and 6 self-help. In this case, too, the predominant genre is thrillers, even though the minimum number of books purchased varies.
The ‘Predominantly’ filter helps you segment your users based on fluid filters that realistically reflect your users’ actions. It's important to note that there is no minimum number of times an event needs to be performed, nor does the most frequent action need to beat others by a specific margin, for a user to qualify. As long as it's the most performed action, even by a small difference, the user is included. Even a single instance of an event with a particular attribute value can lead to a user being included in that segment if no other attribute value for that event has occurred. Furthermore, in the case of a tie in the number of times different attribute values occur for an event, the user will qualify for all the corresponding 'Predominantly' segments.
To set up the ‘predominantly’ filter:
1. In the User affinity tab select *event*
2. Select *predominantly,* then select attribute and filter condition
3. Select the value that should be predominant.
For example, the event is *Song Played, the* attribute name is *Artist Name* and Rihanna is the value. The users who have played songs of Rihanna predominantly in all of their songs are listed. For instance, if a user has only played one song, and it's by Rihanna, they will be included in this segment. If a user has played two songs, one by Rihanna and one by Taylor Swift, they will be included in both the 'Rihanna predominantly' and 'Taylor Swift predominantly' segments.

You can choose multiple affinity attributes for an action, and all of them combined will be considered to be one value, based on which predominance will be calculated.
Let’s take a music streaming app, for example: Along with listing the number of users who listen to a particular artist name (Rihanna), you can also select the platform from which it is played (Android). So the artist + platform is combined into a single value (Rihanna_Android) which shows users who predominantly display the attribute value over all other values (Rihanna_iOS, BTS_Android, and so on).

Normal event property filters can be used to filter out the desired events. On the filtered events, the *Predominantly* calculation is performed.

Here are some instances where you can use the Predominance filter across industries:
1. Filter out users that purchase more T-Shirts compared to other apparel.
2. Find users who predominantly transact more than a threshold amount on your payment platform every week compared to other transaction values.
3. View users who predominantly purchase groceries between the 1st to 5th of the month, compared to all other grocery orders during the month.
4. View the users who predominantly order desserts on Saturday evenings compared to other days of the week.
## Minimum of
Segment users based on them performing an action *at least* x% of times compared to all other actions— this is called the “Minimum of” filter.
For example, if you want to send coupons to users who watch movies on your streaming platform—but only to users who watch RomComs *at least* 25% of the time.
The number of movies played is different for different users, but with the ‘*Minimum of’* filter, you can select users who have played RomComs for at least a select percentage of the time.
To segment users who have executed an action (event) at least for a set percentage of times with an attribute value:
1. In the User affinity tab, select *event*, then select *For a minimum of* & percentage
2. Select attribute and filter condition
3. Select the value that should be a minimum of the attribute
For example, the event is *Song Played*, the attribute name is *Artist Name* is Enrique and the minimum value is 25% of the time. The users who have played songs of Enrique at least 25% of the time in all of their songs are listed.

In the example, along with the genre (RomCom), the Day of the Week (Monday) is also selected. The movie genre + Day of the Week is a single value (RomCom_Monday) and is a minimum set percent across all other values (Thriller_Tuesday, Drama_Wednesday, Horror_Monday, Animated_Tuesday, and so on.)

You can choose multiple affinity attributes for an action, and all of them combined will be considered to be one value based on which ‘Minimum of’ is calculated.
You can further filter these results to reflect app version, gender, location, etc.

The ‘Minimum of’ filter is applicable in the following scenarios:
1. Users who book cab rides from 10 AM to 12 PM at least 60% of the time compared to other hours of the day.
2. Users who make at least 20% of transactions worth more than a threshold amount in a week compared to other transactions.
3. Users whose grocery purchases occur between the 1st and 5th of a month at least 70% of the time compared to other days.
4. Users who buy dessert on a Saturday at least 50% of the time compared to other days of the week.
> [!NOTE]
>
> Affinity Attributes (predominantly & Minimum of attributes) only support string and double data types. Affinity Attributes do not support array data types.
## Top Users and Bottom Users
Filter the users who are performing an action most no. of times or least number of times. The top or bottom users are determined by the number of times they perform that action when compared to other users.
> [!NOTE]
>
> For a user to be eligible for this segment, they must have performed at least one event with the selected action.
For example, you can segment the top 10% of users who book cabs through your app or choose the least 20% who book cabs and send targeted campaigns accordingly.
To segment users who are in the top or bottom percentages of the users and execute an action or event:
1. In the User affinity tab, select event, then select Most no. of times or Least no. of times.
2. Type the percentage value.

You can further filter these results to reflect app version, date, location, etc. The top or bottom users are determined based on the filtered events.

Filtering your users based on Affinity Segments will help you set up more targeted and personalized campaigns that convert better and align your messaging according to your customer's preferences.
# File Segments
Source: https://moengage.com/docs/user-guide/segment/create-segments/file-segments
Upload external user lists to MoEngage as file segments for campaign targeting or further analytics. Supports CSV files with unique user identifiers.

**File & Custom Segments**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3127855-file-custom-segments)
Growth teams often perform their custom analysis on the users and user data. Post the analysis, growth teams would want to use these users in a campaign or perform further analysis.
These users can be uploaded to MoEngage and used as the File Segment. The File Segment is a list of users. File Segment can be used for MoEngage campaigns or Analytics.
File Segments provide flexibility to create and target user segments that you may have identified through some user analysis at your end. You can import a list of users containing one of the User Properties that identifies a unique user, and a custom segment of these users gets created.
# Create a File Segment
Step 1:
Navigate to MoEngage Dashboard > Segment > All Segments > +Segment > File Segment

Step 2:
1. Provide a Custom segment name and description.
> [!NOTE]
>
> The name `All Users` is reserved by MoEngage and cannot be used as a custom segment name. Names also cannot contain the characters `:` `|` `*` `?` `\` `<` `>` `=` `$` `"`, cannot start with a period (.), cannot consist only of whitespace, and cannot exceed 200 characters. A file segment with an invalid or reserved name is rejected: it does not appear in the custom segment dropdown or shows zero users. This also applies to file segments created through the API or external integrations.
2. Select the file which has the user list. You can either upload a CSV or provide a URL to the same.
3. Select the User Property that your list is using. For example, if you have a list of the Driving IDs of your users, select Driving ID from the user property dropdown.
4. Provide one or more email IDs where MoEngage can inform, once the custom segment is created.
**Note:** If you don't see the segment after receiving the email, please refresh the page and search.

> [!WARNING]
>
> A user property value must uniquely identify a single user. If an attribute value identifies multiple users (e.g. a city attribute with the value 'London' may have many users) these multiple users may get mapped to a single attribute, become part of the segment, and may block other users from being included in the segment.
>
> For example, you upload 5 emails, and the first email matches with 3 users (A, B, and C), and the remaining 4 emails match with one user each (D, E, F, and G). In this case, the system will randomly pick 5 users to be added to the file segment.
>
> The system does the processing in batches of 2,000 attribute values and add maximum of 2,000 users into file segment for each batch. Even with fewer user property values, more users could be added to the file segment. For example if 1500 user property values results into 2500 users, system will randomly add 2000 of these 2500 users into the file segment.
>
> Ensure all users are imported into MoEngage before including them in a file segment; only existing profiles can be successfully mapped.
>
> File segments archived for more than 30 days will undergo permanent user deletion. This data cannot be recovered once deleted.
## File Requirements
Before uploading, ensure your file meets the following requirements:
* The file must be in CSV format with a single column containing the user property.
* The file size must not exceed 64 MB.
* The file must not contain duplicate values, empty rows, or empty columns.
The values inside the file are not restricted by character; any character is allowed in a user property value. Character restrictions apply only to the file segment name, not to the file's contents. However, leading or trailing spaces, values wrapped in double quotes, and non-UTF-8 characters can prevent values from matching users and lower the final user count.
[Download a sample CSV file.](https://app-cdn.moengage.com/assets/Sample_GAIDs.csv)
## URL Requirements
If you are providing a URL instead of uploading a file directly, the following conditions must be met:
* The URL must be publicly accessible. Private or expired URLs cannot be downloaded by MoEngage and will result in a segment with zero users.
* If the file is hosted behind a private endpoint, whitelist the relevant MoEngage IP addresses to grant access. Contact your MoEngage CSM or the Support team for the list of IP addresses to whitelist.
* The file at the URL must meet the same format requirements as a direct CSV upload.
* A file provided via URL can be up to 300 MB, compared to the 64 MB limit for direct uploads.
## Custom Segment Availability
As soon as the MoEngage system receives the File Segment request, it creates the custom segment. After creating a custom segment, the system processes the users and adds those users to the custom segment.\
Hence custom segment is **available** when the file is processing and also if the file processing is failed. When the File Segment is processed, its status (either completed or failed) is communicated through an email.
In case the file upload/processing has failed, you can upload the file again using the same custom segment name. The system will add the new user to the provided custom segment. This functionality also enables adding new users to any existing file custom segment.
## Status and Warnings for File Segment Processing
To prevent issues arising from using file segments before they are fully processed, MoEngage provides warnings in the UI. These warnings help you understand if a segment is still being processed and when it's advisable to use it.

> [!NOTE]
>
> You will see these warnings on the following pages:
>
> * Create segment page
> * **Target audience** sections on all the campaign creation pages
> * **Target audience** sections on analytics pages
### Warnings During Segment Usage
When you select a file segment that is still being processed for use in creating another segment, while targeting a campaign, or in analytics, a warning message will be displayed. The warning is displayed based on the following conditions:
* **If a single selected segment is being processed**: "Users are being updated in this segment - ``. We suggest that you wait until the confirmation email is received to use this segment in a campaign. Keep an eye here for the latest update."
* **If segments nested in another segment are processing**: "Users are being updated in these segments - ``. These segments are nested in the parent segment chosen. We suggest that you wait until the confirmation email is received to use the segment in a campaign. Keep an eye here for the latest update."
Refresh the page or choose the segment again to see its latest status. This warning will no longer appear after the last file in the queue is successfully processed.
### Warning in the Segment Detail Page
If you navigate to the detail page of a custom segment that is currently being updated (i.e., a file upload is still processing), a warning message will be displayed as follows: "Users are being updated in this segment - ``. We suggest that you wait until the confirmation email is received to use this segment in a campaign. Keep an eye here for the latest update."
Refresh the page to see the segment's latest status. This warning will no longer appear after the file processing is successfully completed.
## User Availability
File Segments can only have users that are present in MoEngage. If you upload a user, who is not present in MoEngage systems, that user is not processed and can not be part of the File Segment.
To upload new users into the MoEngage and create a File Segment of those users, refer to [Import Users](/docs/user-guide/data/imports/file-based-imports/import-user-data-using-csv).
The total number of users uploaded via the File segment is limited to 2 million per day.\
(This limit is customizable, please get in touch with support to increase the limits.)
A single file segment can contain up to 5 million users. When you use the File Segment API to create or update file segments, a workspace can run up to 10 operations per hour and 100 per day (calculated on a rolling 24-hour window); requests beyond these limits are rejected with a 429 response.
# Edit a File Segment
Editing an existing file segment is possible via the MoEngage dashboard. On the MoEngage dashboard, you can perform the following actions on a file segment:
1. Add users: A new list of users can be added to an existing file segment.
2. Remove users: A list of users can be removed from an existing file segment.
3. Replace users: A list of users can be replaced in an existing file segment.
Step 1:
Navigate to the file segment that you would like to edit from the Segment > All Segments page.
Step 2:
From the Actions tab, click on the More Actions vertical ellipses and choose the Edit option.
Step 3:
1. Choose the Edit action that you want to perform on the file segment among Add users, Remove users and Replace users.
2. Select the file which has the user list to be added, removed, or replaced. You can either upload a CSV or provide a URL to the same.
3. Select the User Property that your list is using. For example, if you have a list of the Driving IDs of your users, select Driving ID from the user property dropdown.
4. Provide one or more email IDs where MoEngage can inform, once the custom segment is processed.

All functionalities of file segments: Create segments, Remove and Replace users from the File Segment can also be accessed using [File Segment API](/docs/api/file-segments/create-file-segment).
# Archive/Unarchive a File Segment
File Segments can be archived from the MoEngage dashboard.
1. File segments that have not run (query not executed) in the last 60 days are automatically archived.
2. Continuous cohort or file syncs are not counted as a run, so a regularly-syncing externally-imported file segment can still be auto-archived. To keep it active, run it manually from the dashboard or use it in a segmentation filter.
3. Externally-imported file segments (for example, from Amplitude and other external tools) cannot be archived or unarchived from the dashboard. To unarchive one, use the [Unarchive Segment API](/docs/api/manage-segments/unarchive-segment).
4. All the users from the archived File Custom Segment are dropped after 30 days of archival. Hence after 30 days of archival, the archived custom segment returns 0 users.
5. File segments expire after a fixed time, even if they are still used in campaigns or flows. When a file segment expires, all its users are dropped and the segment is archived. The expiry time depends on how the segment was created:
* File segments created from the MoEngage dashboard have a default expiry time of 365 days.
* File segments created using the [File Segment API](/docs/api/file-segments/create-file-segment) expire after the `expiry_time` set in the request. The maximum expiry time is 365 days.
> [!WARNING]
>
> Archived segments will not be shown beyond 180 days.
# FAQs
> [accordion] Why Does the User Count Differ Between the File Segment in MoEngage and the Uploaded File?
>
> ### Problem
>
> There is a discrepancy in the user count between the uploaded file and the file custom segment in MoEngage.
>
> ### Explanation
>
> The following are the possible reasons for these differences:
>
> * Zero count
> * **Wrong attribute provided:** The attribute selected during the file segment upload does not match the values provided in the file. For example, if the attribute selected is *age* (double data type) but the file contains values for *name* (string data type), there will be no matching users in MoEngage, resulting in a zero count.
> * **File not downloadable:** If the file URL provided is private or expired, MoEngage cannot download the file, leading to no users being added to the custom segment and a zero count.
> * **Inappropriate CSV content:** Issues such as leading or trailing spaces in values, rows with only spaces, non-UTF-8 characters, values enclosed in double quotes, or values ending with a comma can result in a zero user count.
> * **File processing delay:** After you upload a file, users will not be immediately added to the custom segment. Processing time increases with the number of values in the file. Querying the custom segment immediately after upload may result in a zero count.
> * Less count
> * **Less users in MoEngage:** If the values mentioned in the file do not match those in MoEngage, they will not be considered, resulting in a lower user count.
> * **Inappropriate CSV content:** Similar to the zero count scenario, issues with CSV content can lead to a lower user count.
> * **File upload still processing:** A custom segment is created with zero users immediately after the file upload. Users are then added during the file processing. Querying the segment during processing may display a lower user count.
> * More count
> * **Attribute value matches multiple users:** If the value provided in the file matches multiple users in MoEngage, all those matched users will be added to the custom segment, resulting in a higher user count.
>
> For more information, read [File Segments](/docs/user-guide/segment/create-segments/file-segments).
> [accordion] Why Does CSV Upload to File Segment Fail?
>
> ### Problem
>
> While uploading a CSV file in a file segment, the following error message appears:
>
> There seems to be an error. We are working to fix this.
>
> ### Solution
>
> Perform the following steps:
>
> 1. **Verify the File Format**:
> * Ensure the file is in the CSV format.
> 2. **Check the File Size**:
> * Confirm that the file size does not exceed 64 MB. If the file is larger than the allowed limit, reduce its size before uploading.
> 3. **Confirm the Unique Identifier Column**:
> * Ensure the file includes only one column designated as the segment's unique identifier.
> * It is recommended to use a unique identifier (UID).
> 4. **Remove Empty Rows and Junk Data**:
> * Check for empty rows at the end of the file.
> * Remove any unnecessary or duplicate values that might cause issues.
> 5. **Match Record Values to Attribute Data Types**:
> * Ensure the record values align with the specified data types.
> 6. **Use a Valid File Segment Name**:
> * Character restrictions apply to the file segment name, not to the values inside the file. Ensure the name does not contain the characters `:` `|` `*` `?` `\` `<` `>` `=` `$` `"`, does not start with a period (`.`), is not empty or whitespace-only, and does not exceed 200 characters.
>
> For more information, read [File Segments](/docs/user-guide/segment/create-segments/file-segments).
> [accordion] Why Does Third-Party Link Upload to File Segment Fail?
>
> ### Problem
>
> While uploading a third-party link in a file segment, the following error message appears:
>
> There seems to be an error. We are working to fix this.
>
> ### Solution
>
> Perform the following steps:
>
> 1. **Whitelist IPs for private files**:
> * If the file is private, whitelist the relevant IP addresses to grant access exclusively to MoEngage.
> 2. **Verify the file format**:
> * Ensure the file is in the CSV format.
> 3. **Check the file size**:
> * Confirm that the file size does not exceed 64 MB. If the file is larger than the allowed limit, reduce its size before uploading.
> 4. **Confirm the unique identifier column**:
> * The file must contain only one column that serves as the segment's unique identifier.
> 5. **Remove empty rows and junk data**:
> * Check for empty rows at the end of the file.
> * Remove any unnecessary or duplicate values that might cause issues.
> 6. **Match record values to attribute data types**:
> * Ensure the record values align with the specified data types.
> 7. **Use a valid file segment name**:
> * Character restrictions apply to the file segment name, not to the values inside the file. Ensure the name does not contain the characters `:` `|` `*` `?` `\` `<` `>` `=` `$` `"`, does not start with a period (`.`), is not empty or whitespace-only, and does not exceed 200 characters.
>
> For more information, read [File Segments](/docs/user-guide/segment/create-segments/file-segments).
# Manage Segments
Source: https://moengage.com/docs/user-guide/segment/create-segments/manage-segments
Create, reuse, and manage custom segments in MoEngage. Save segment queries for reuse across campaigns and analytics, then view, edit, rename, archive, and analyze them from the All Segments page.
A custom segment is a saved, named segment query that you can reuse across campaigns, flows, and analytics pages without rebuilding the query each time. A custom segment can be a [file segment](/docs/user-guide/segment/create-segments/file-segments) or a rule-based [filter segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments), and it can combine both — along with other custom segments.
This article explains how to create and use custom segments, and how to view and manage them from the **All Segments** page.
> [!NOTE]
>
> A workspace can have up to 1,000 active segments (file, filter, and custom combined). To raise this limit, contact Support.
## Creating a Custom Segment
In the MoEngage dashboard, custom segments can be created in three ways:
* Navigate to **Segment** > **Create Segment**. After entering the query, click **Create** and select **Create Custom Segment**. Enter the custom segment name and save it. You can also create one from the Recent Query section: for a selected query, click the **Create Custom Segment** icon, enter a name, and save. These sections create a dynamic custom segment. For more information, see [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
* While importing users. The users in the segment remain fixed, so this is a static custom segment. [Learn more about importing user data using CSV.](/docs/user-guide/data/imports/file-based-imports/import-user-data-using-csv)
* From Behavior analysis, Funnel analysis, and RFM Segments. These sections create a dynamic custom segment. [Learn more about RFM Segments.](/docs/user-guide/segment/create-segments/rfm-segments)
> [!NOTE]
>
> **Segment naming rules:** The name `All Users` is reserved by MoEngage and cannot be used as a custom segment name. A segment name also cannot contain the characters `:` `|` `*` `?` `\` `<` `>` `=` `$` `"`, cannot start with a period (`.`), cannot consist only of whitespace, and cannot exceed 200 characters. These rules apply to the name only — not to the values inside an uploaded file. A segment with an invalid or reserved name is rejected. When the segment is created through the API or an external integration (such as a Mixpanel cohort sync), the rejection can be silent: the segment does not appear in the custom segment dropdown or shows zero users.
## Using a Custom Segment
On the MoEngage dashboard, custom segments can be used in multiple ways:
* Use a custom segment to build a complex user segment, combined with user properties and user activities.
* Use a custom segment while creating other custom segments. Custom segments support up to 6 levels of recursion/nesting — for example, Custom Segment A can include Segment B, which can include Segment C, and so on. [File Segments](/docs/user-guide/segment/create-segments/file-segments) are not counted toward the nesting limit. For advanced nesting techniques, see [Segment Nesting](/docs/user-guide/segment/advanced-concepts/segment-nesting).
* While defining a new custom segment, up to 10 existing custom segments can be used. [File Segments](/docs/user-guide/segment/create-segments/file-segments) are not counted toward this limit.
* Use a custom segment as the target audience while creating a campaign for channels such as Push, Email, SMS, In-App, Facebook, and Flows.
> [!NOTE]
>
> A definition that stays within the nesting and custom segment limits above can still fail to run. Every referenced custom segment expands into its full definition when the query is serialized, and the serialized query cannot exceed 256 KB (262,144 characters). Combining several custom segments with OR — including in the exclusion block — is the pattern that most often crosses that limit. For the symptoms and how to reduce the size of a definition, see [Why Does My Segment Query Fail With a Query Length Error?](/docs/user-guide/segment/faqs-segment/why-does-my-segment-query-fail-with-a-query-length-error)
### Custom Segment Analysis
Users of a custom segment can be analyzed on the MoEngage Analytics pages — [Behavior](/docs/user-guide/analyze/analytics/behavior/behavior-overview), [Funnel](/docs/user-guide/analyze/analytics/funnels/funnels-overview), [Retention](/docs/user-guide/analyze/analytics/retention/retention-overview), [Session & Source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview), [User Paths](/docs/user-guide/analyze/analytics/user-paths/user-paths-overview), and [RFM Segments](/docs/user-guide/segment/create-segments/rfm-segments). By default, all users are analyzed for the above analyses. To analyze users of a specific custom segment, select the desired custom segment from the custom segment dropdown, provide the other required parameters for the respective analysis, and click **Apply**.

# All Segments
The All Segments page provides a unified view of all custom segments created and used in MoEngage. This enables growth teams to quickly get an overview of their custom segments in one place and perform actions on them. They can also navigate to the detail page of each custom segment from the All Segments page. If Teams are enabled for your account, the custom segments created for all the teams (to which you have access) will be displayed. To see the custom segments created for a specific team, select the team in the **All Segments for** dropdown list.
This page lists all the custom segments, showing the Custom Segment name, Segment Type, Segment created time, Segment last run time (time at which the segment was the last run in a query or a campaign), and actions that can be performed on a custom segment.
Clicking on the Custom segment name will lead the marketer to that segment’s detail page.
You can sort the table by any of the columns in ascending or descending order. By default, the table is sorted in descending order of the last run time.

You can search for a segment by entering the desired segment name in the search box.
Segments can also be filtered by Segment Type. Select one or more types from the **Select Segment Type** list to show only those segments.

1. **File** - These are custom segments that are created when growth teams upload a list of users. You can import a list of users containing one of the User Properties that identifies a unique user, and a custom segment of these users gets created. [Learn more about file segments in this article](/docs/user-guide/segment/create-segments/file-segments).
2. **Filter** - These are custom segments that are created from the MoEngage dashboard. Growth teams can create rules and criteria to define a user segment. The rules and criteria can be applied to user properties, events & event properties, and a combination of the two. [Learn more about filter segments here.](/docs/user-guide/segment/create-segments/rule-based-filter-segments)
3. **Warehouse - SQL** - These are custom segments created by writing a SQL query against your connected data warehouse. [Learn more about creating a warehouse segment using SQL.](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql)
4. **Warehouse - filter** - These are custom segments created from your data warehouse using dropdown filters instead of SQL. [Learn more about creating a warehouse segment using filters.](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters)
Clicking on **+Segment** opens a panel that redirects to the **Create Segment** page (to create a filter segment), the RFM segment page, and the **Create File Segment** popup (to create a file segment). If Teams are enabled, and you are a part of multiple teams, you will need to select a team from the **Teams** dropdown before clicking **+ Segment**.
> [!NOTE]
>
> MoEngage Teams with the Segmentation Filters is a Beta feature. To get it enabled for your account, reach out to your CSM.

## Archived Segments
Clicking on the Archived Segment toggle on the All Segments page leads to Archived Segments Listing Page.
Filter segments archived in the last 6 months (or a maximum of 1000 archived segments) will be listed here. You can unarchive these segments from here.
File Segments archived beyond 30 days from the date of archival will not be listed on this page as they have expired. [Learn more about file segments here.](/docs/user-guide/segment/create-segments/file-segments) Within 30 days of archival, you can unarchive the file segments from this page.
# Actions on Custom Segments
| Action | Description |
| - | - |
| View | For both file and filter segments, clicking on View will redirect to that segment’s detail page. |
| Edit |
For Filter segments, the Edit option will open the Create Segments page will the filters of the segment pre-populated. These filters can be edited and the new query can be saved as a new custom segment.
For File segments, the Edit option can be used to add, remove or replace users in an existing file segment. [Learn more about file segments here.](/docs/user-guide/segment/create-segments/file-segments)
|
| Duplicate |
For filter segments, the Duplicate option will open the Create Segments page with the filters of the segment pre-populated. These filters can be edited and the new query can be saved as a new custom segment.
File segments cannot be duplicated. This is because they represent a static list of users from an uploaded file and are not defined by editable rules. Duplicating a segment is useful for copying and then modifying its rules, but since a file segment has no rules, this action isn't applicable. To reuse the same list, you can simply use the original segment.
|
| Archive | Both file and filter segments can be archived from the dashboard depending on the segment source. |
| Rename | Update the name of a segment without disrupting existing campaigns, analytics, or downstream integrations. When renamed, the segment's unique ID remains unchanged. **Early Access:** Contact your MoEngage CSM or Support team to enable this. Not available for segments sourced from Campaigns, Imports, Locales, Global Control Groups, or partner integrations. |
| Export Users | Export Users can be used to download any one or more user properties belonging to that segment. Please run the custom segment before exporting users to get the updated list of users. Export Users does not support [Object data-type](/docs/user-guide/data/key-concepts/support-for-object-data-type) attributes (including array of objects): if a selected attribute is an Object, it is exported as invalid or incomplete JSON and cannot be reliably parsed. |
| Create Campaign | Create Campaign action leads to the create campaign page with Target Audience pre-populated with the segment’s definition. |
| Analyze Segment | Analyze a segment directly from the Segmentation page. This action auto-populates the segment in the Target audience section of Behavior, Funnels, Retention, Session and Source, User Paths, and RFM analysis. |
## Segment Sources
All custom segments fall into one of the following sources, depending on where they are created on MoEngage or where they are imported from into the MoEngage systems.
| Sources | Description | Actions available |
| - | - | - |
| Segmentation | Custom Segments created from MoEngage Segmentation have the source as Segmentation. | 1. View 2. Edit 3. Duplicate 4. Archive/Unarchive 5. Export Users 6. Create Campaign 7. Analyze Segment |
| CSV Upload, API, Import Users | These are custom segments that are uploaded into the MoEngage systems as File segments. File segments cannot be duplicated. | 1. View 2. Edit 3. Rename 4. Archive/Unarchive 5. Export Users 6. Create Campaign 7. Create Campaign 8. Analyze Segment |
| Campaigns, Analyse, Prediction, Campaign Locale, Global Control Group, Custom | These are custom segments that are created on MoEngage from sources other than Segmentation - such as Campaigns, Analyze, and Predictions. Edit actions such as - Edit, Duplicate, Archive, and Unarchive are not available for these segments as they may have an impact on campaigns/analysis that these segments are a part of. | 1. View 2. Export Users 3. Create Campaign 4. Analyze Segment |
| Cohort Sync, Amplitude, Mixpanel, mParticle, Segment IO | These are custom segments that are imported into the MoEngage systems from other third-party or external sources. Edit actions such as - Edit, Duplicate, Archive, and Unarchive are not available for these segments as they are externally managed. | 1. View 2. Export Users 3. Create Campaign 4. Analyze Segment |
## How to Manage Segments
### Edit a Segment
To edit the filters or rules of a segment:
1. Go to **Segment** > **All Segments**.
2. Find the segment and click the ellipsis icon in the **Actions** column.
3. Select **Edit**.
* For filter segments, the Create Segments page opens with the segment's current filters pre-populated. Update the filters and click **Save**.
* For file segments, choose to add, remove, or replace users, then upload the updated file.
### Rename a Segment
> [!NOTE]
>
> **Early Access**
>
> This is an Early Access feature. To enable it for your account, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
You can update the name of a segment without disrupting existing workflows, historical data, or downstream integrations. When a segment is renamed, its unique Segment ID remains unchanged.
To rename a segment:
1. Go to **Segment** > **All Segments**, click the ellipsis icon on the desired segment, and select **Rename**. 
2. In the **Rename custom segment** window, enter the new name in the **Segment name** field and click **Save**. 
Keep the following in mind when renaming:
* Only users with **Create & Manage** permission in Segments can rename a segment.
* Segment names must pass character limits and uniqueness checks. Names cannot be reused, even for archived segments.
> [!NOTE]
>
> You cannot rename segments sourced from Campaigns, Imports, Locales, Global Control Groups, Data Science (predictions), or partner integrations (such as Amplitude, Mixpanel, or Segment).
### Archive and Unarchive a Segment
To archive a segment:
1. Go to **Segment** > **All Segments**.
2. Search for the segment you want to archive.
3. Click the ellipsis icon and select **Archive**.
Note the following archival behavior:
* Archived segments are not available in the segment dropdown across the MoEngage dashboard.
* If an archived rule-based segment is used in a campaign, the campaign still calculates it based on its rules. If an archived file segment is used, it returns 0 users.
* Segments that have not been run in the last 60 days are automatically archived.
* Continuous cohort or file syncs are not counted as a run, so an externally-imported segment (for example, from Amplitude) can be auto-archived even while it syncs regularly. To keep such a segment active, run it manually from the dashboard or use it in a segmentation filter.
* Externally-imported segments (for example, from Amplitude and other external tools) cannot be archived or unarchived from the dashboard. Attempting to unarchive one shows "Unarchive is not available for this segment as it is imported from Amplitude." To unarchive it, use the [Unarchive Segment API](/docs/api/manage-segments/unarchive-segment).
* All users from an archived file segment are dropped after 30 days of archival. After that, the segment returns 0 users.
* File segments expire after a fixed time, even if they are still in use. File segments created from the dashboard expire after 365 days by default, and file segments created using the [File Segment API](/docs/api/file-segments/create-file-segment) expire after the `expiry_time` set in the request, up to a maximum of 365 days. On expiry, all users are dropped and the segment is archived. For more information, refer to [File Segments](/docs/user-guide/segment/create-segments/file-segments).
* Segment names cannot be reused, even when a segment is archived.
To unarchive a segment, go to **Segment** > **All Segments**, enable the **Archived Segments** toggle, find the segment, and click **Unarchive**.
# Segment Details
Clicking on the Segment Name from the All Segments page will lead you to the Segment Details page of that particular segment. You can navigate to this page from All Segments > Choose segment > Actions: View as well.
The Segment Details page lists the Segment type, description, created time, source, and the last run time of the segment.
This page also shows the user count, reachable users, and the last refreshed time of a custom segment. You can run the segment from here to get the latest user count and reachable users as well.
All actions on a custom segment (edit, duplicate, archive, export users and create campaigns) are available on this page based on the segment type and segment source.
Growth teams can also view the reachability and sample user information as available currently on the Create Segment Page. You can also view the Segment Edit History based on the type of the segment.

## Reachability and Sample users
**Reachable Users**
This will show the reachable user count across all outbound channels (Push, Email & SMS). Reachable user count is also available for specific channels individually.
This count can differ from the reachable count on a campaign page or the Reachability dashboard. For the reasons, see [Why Reachable User Counts Differ Across Pages](/docs/user-guide/segment/reachability/user-reachability#why-reachable-user-counts-differ-across-pages).
**Sample users** initials or GU(Stands for Guest) - Click on these bubbles to open the user profile.
## Segment Edit History
The Segment Edit History section on the Segment Details page is based on the Segment Type of the chosen segment.
### File Segment Edit History
The Edit history for file segments shows the following columns - Segment Edited on (time of edit), Operation (Add, Remove, Replace users), Status of Operation, and details of the file processed.

The Status of the Operation can have the following values:
1. Pending: Pending file segments are yet to be processed as there is already another file in the processing queue.
2. Processing: These file segments are currently being processed by the system.
3. Successful: File segments are processed successfully and their attributes are updated.
4. Failed: File segments that have failed while processing. On hovering over this status, you will be able to view the reason for failure as well.
Details of the file processed:
1. Attribute name: This column shows the user property uploaded in the file along with its data type.
2. Valid attributes: This indicates the number of records that were successfully processed in the file uploaded.
3. Users resolved: This indicates the number of existing users updated with the user property provided in the file. These users then become part of the custom segment.
4. Invalid attributes: This indicates the number of records in the file that failed during processing.
By default, this table is ordered in the ‘Segment edited on’ column, showing the latest edit first. You should be able to see the last 20 edits in the edit history of the file segment.
### Filter Segment Edit History
The Edit History for filter segments shows the following columns - Segment edited on(time of edit), Segment description, and Option (Use this version).

You can click on **Use this version** on an older version of the segment, to update the current segment definition to the chosen version. Refresh the segment count to get the latest user count and reachability of the edited segment.
By default, this table is ordered in the ‘Segment edited on’ column, showing the latest edit first. You should be able to see the last 20 edits in the edit history of the filter segment.
### Segment Renamed
> [!NOTE]
>
> **Early Access** \
> This is an Early Access feature. To enable it for your account, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
When a segment is renamed, the Segment Detail Page automatically updates its dynamic headers. Additionally, the Segment Edit History table will reflect this change: 
* The previous name appears with a strikethrough before the new name (For example, Name : ~~Custom Segment 1~~ -> Custom Segment 2)
* Users cannot take action on this specific row.
* All historical versions of the segment are stored as static text and will not change with the event name change or segment name change.
* The **Updated By** column in the Segment Edit History records who modified a segment, with the following conditions:
* **Filter-based segments**: Tracks all subsequent edits, but does not track the initial creation.
* **File-based segments**: Only tracks when a segment is renamed. It does not track the initial creation or general file updates.
## Synced Segments
You can sync and send customer segments created on MoEngage to any other platform in your tech stack. For more information, refer to [Outbound Segment Sync](/docs/user-guide/data/exports/segments/outbound-segment-sync).
## Troubleshooting
> [accordion] Why Is the Custom Segment Count Less Than the Import User Count?
>
> If the user count in your custom segment is lower than the number of users in your uploaded file, there are two common reasons:
>
> * **Duplicate user IDs in the file:** MoEngage ignores duplicates. Each unique user ID is counted once.
> * **Users not yet in MoEngage:** File segments can only contain users who already exist in MoEngage. If an uploaded user ID doesn't match an existing profile, that user is excluded from the segment.
>
> For more information, read [Import User Data Using CSV](/docs/user-guide/data/imports/file-based-imports/import-user-data-using-csv).
>
> 
> [accordion] Why Do Date Range Filters Fail Sometimes for Custom Attributes in Segmentation?
>
> The filters available for a custom attribute depend on the data type MoEngage receives for it. If date-based filters (such as "before", "after", or "between") are unavailable for a date attribute, the attribute is likely being received as a string instead of a datetime.
>
> This typically happens when:
>
> * The attribute was initially set up as a datetime, but your app later started sending it as a string.
> * The same attribute is sent with different data types from different sources.
>
> To fix this, ensure all sources send the attribute in the same, correct data type. Contact your development team to verify the data type being sent.
> [accordion] Why Does the Error 'Custom Segment Name Already Taken' Occur?
>
> MoEngage uses segment names as unique identifiers to track and manage references across the system. To protect data integrity, a segment name cannot be reused — even if the original segment is archived and no longer visible in the dashboard.
>
> To resolve this, use a different name for your new segment.
# RFM Segments
Source: https://moengage.com/docs/user-guide/segment/create-segments/rfm-segments
Segment users automatically with the RFM model in MoEngage based on recency, frequency, and monetary value for targeted marketing campaigns.

**RFM Segments**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3133828-rfm-segments)
**RFM** (Recency, Frequency, and Monetary) Model provides auto-segmentation and buckets users into categories such as Champions, Loyal Customers, and Hibernating based on their behavior. These auto segments can be used in multiple different ways such as user analysis, churn analysis, and campaign effectiveness. RFM can also be used for predictive segmentation, customers who are more likely to respond to promotions, and also for future personalization.
RFM analysis is a widely used marketing model for behavior-based customer segmentation. This was primarily used in the retail industry and made its way into digital marketing. It groups customers based on their transaction history – how recently, how often, and how much did they buy.
RFM Analysis can be used to answer questions like -
* Who are your loyal customers?
* Which are the customers who are most likely to churn?
* Which customers are purchasing the most on your platform?
* Which are the customers who can be turned into the best customers with little effort?
* Which customers are most likely to engage with your campaigns?
## RFM Segments Overview
[YouTube video player](https://www.youtube.com/embed/9biMzkAJLJw)
## What is RFM Analysis
RFM analysis is a customer behavior segmentation method that uses customers' past interactions such as a visit to the platform or purchase of an item and based on these interactions divides customers into different RFM groups.
### The Factors for RFM Analysis
The primary factors are R, F, and M for this model, which are explained below-\
R is RECENCY - Time since the last visit to the app/site or time since the last purchase.\
F is FREQUENCY - The total number of times a user has visited the app/site or the total number of purchases\
M is MONETARY - Total money spent by a user or total time spent watching content
## How RFM is calculated
### Value for Recency, Frequency, and Monetary
Value for Recency, Frequency, and Monetary is the exact value for a specific user, for example, the recency value is 3 days ago, the frequency value is 5 times, and the purchase value is \$1523.
### Scores for Recency, Frequency, and Monetary
MoEngage gives each user a Recency score, a Frequency score, and a Monetary score. Each score runs from 1 (low) to 3 (high).
A score is a percentile rank. It places the user in one of three groups based on where their value sits relative to the other users in the analysis. It is not a fixed threshold, so the same value can earn a different score in a different analysis. For Recency, a more recent last event earns a higher score.
The three scores together form the user's combination, written as (R, F, M). For example, (3,3,3) means the top score on all three.
Here is an example with three users:
| **User ID** | **R Value** | **R Score** | **F Value** | **F Score** | **M Value** | **M Score** | **Combination** | **Segment** |
| - | - | - | - | - | - | - | - | - |
| 1 | 1 day ago | 3 | 10 times | 3 | \$1000 | 3 | (3,3,3) | Champions |
| 2 | 5 days ago | 2 | 4 times | 2 | \$560 | 2 | (2,2,2) | Potential Loyalist |
| 3 | 9 days ago | 1 | 1 time | 1 | \$100 | 1 | (1,1,1) | Lost |
With only three users, each user lands in a different group. In a real analysis, many users share each group.
The segment comes from the combination, not from an average of the three scores. For example, (3,3,1) and (2,2,3) both average 2.33, but (3,3,1) is Price Sensitive and (2,2,3) is Potential Loyalist.
#### M Value and M Score
The M score and the M value are different things. The M score (1 to 3) ranks a user's monetary value against other users. The M value shown for a segment is the average monetary value per user in that segment: the sum of the monetary values of all users in the segment, divided by the number of users in it.
For example, suppose three users in a segment have total prices of 100, 150, and 200 for the selected monetary event. The segment's M value is (100 + 150 + 200) / 3 = 150.
Two segments can have the same M score and different M values. The M score only says which spending group users fall into. The M value is the average spend of the users in that particular segment, and segments with different Recency and Frequency combinations contain different users. The M value also changes with the date range, because scores are ranked against the users active in that period.
A Behavior analysis on the same attribute will not reproduce this number. It averages across all users, or across whichever filter you apply, and not only the users who belong to that RFM segment at the time of analysis.
### Segment Buckets for RFM Score
Users who show similar behavior on their R, F, and M scores are grouped into the same RFM bucket, or segment. The segment a user lands in comes from their score combination, not from an average of the three scores.
MoEngage has two RFM models, and each has its own set of segments. The default RFM model uses all three scores and has 10 segments. The RF model uses only Recency and Frequency and has 8 segments.
## Engagement Strategies for RFM Segments
The RFM segment predicts user behavior and accordingly, marketers can take action to make the best of these user segments. Here are some basic strategies to be used for different RFM Segments:
| | |
| - | - |
| **RFM Bucket** | **Engagement Strategy** |
| **Champions** | Reward these users. They promote your products, they can be early adopters for your new launches. |
| **Loyal Customers** | These users are responsive to your promotions, and you can suggest to them higher-value products. Also, ask them for reviews. |
| **Potential Loyalist** | Engage them with long-term offers like loyalty programs or membership rewards. Suggest other categories of products to them. |
| **Recent Users** | For new users, make their onboarding experience smooth and provide assistance when needed. |
| **Promising** | Make them loyal by creating brand awareness and giving free trials. |
| **Needs Attention** | Need to bring back these customers, provide limited-period offers, and recommend products using purchase history. |
| **About To Sleep** | The user will be lost if not reactivated. Recommend them popular products and provide discounts for memberships. |
| **Price sensitive** | Users looking for the best deal, recommend them the highest rated products and send discount communications. |
| **Can’t Lose Them** | Listen to their feedback, suggest them newer products, and make them stick to your platform. |
| **Hibernating** | Recommend products for other categories and provide personalized offers. |
| **Lost** | Make your presence known through different campaigns. |
Let's see how it works on the MoEngage dashboard:
## RFM Events
By default **App/Site Open** is selected as Recency event, Frequency event is selected as '**Same as Recency Event**'. Monetary event & Revenu Attribute is default set to the **Conversion Goal** Event and **Revenu Attribute** defined in MoEngage Dashboard > Settings > APP > General.
Users can change these Recency, Frequency, and Monetary events and apply desired filters for the selected events. This helps run RFM analysis on a specific category, specific business unit, product, or service.
Accounts do have an identifier (event property) for different currencies. This identifier has to be used to filter the monetary events. Needless to say, Recency and frequency events should also be of that specific market or category, or business unit for which the monetary event is being analyzed.

## RFM Model & Duration of Analysis
MoEngage dashboard provided RF (Recency & Frequency), RM (Recency & Monetary), and FM (Frequency & Monetary) analysis model other than the default RFM model.
Users can select a desired time duration for the RFM model analysis.
The recommended analysis period is 30 days - the more the data the better. Individual users can decide the RFM model analysis duration based on their customer acquisition, activation, and retention period. RFM duration should cover all of these customer lifecycle phases if possible. In the case of retail & e-commerce, 3 month time period is an industry-standard for RFM model analysis.\
RFM analysis can be performed on all data that is present in MoEngage Analytics. In most cases, the data retention is 1 year or 2 years.

MoEngage performs RFM analysis in real-time, hence users don’t have to configure and wait for the analysis. The time taken for the analysis is proportional to the time period and the number of data points scanned. For an account that has 45 million MAU, the RFM model takes just a few minutes to complete the analysis.
## Understanding Charts & Tables
### RFM Models
The chart represents the different RFM segments, their respective user count, and segment size as a percentage of total users in the selected time duration. The size of the segment on the chart is proportional to the user count.
Hover over a segment to see its Recency, Frequency, and Monetary scores and values. For Recency and Frequency, the value in parentheses is the range (low - high) across users in the segment. For Monetary, it is the average monetary value per user in the segment, not a range. Each score in the tooltip is the average of the individual scores of users in the segment, so it can be a decimal, such as 2.68.
Chart images can be downloaded in png format for further use.

### RFM Table
The table represents the same data shown in the chart, in tabular format. the table shows the RFM Segment Name, Recency Score, Recency Value Range, Frequency Score, Frequency Value Range, Monetary Score, Monetary Value Range, User Count, and Percentage of Users.
Table data can be downloaded in CSV format for any further use.

If your user role doesn’t have download permission, there will not be a download CTA for the user.
> [!NOTE]
>
> Counts for the same time frame can change slightly between runs. A user near the boundary between two score groups can land in a different group when the analysis runs again, and new data arriving between runs can also move users. This applies to every segment. It is most visible in Lost, About to Sleep, and Hibernating, because their definitions are close.
## RFM Transition
RFM transition represents the count of users, of RFM Segments from Period 1, moving into RFM Segments of Period 2, over the Transition Duration.
Transition Duration is the time period over which users migrate from one RFM segment to another RFM segment. The time duration of the origin RFM & destination RFM remains the same.
Period 2 is what users select on the **Date Range** field, let's say it is x days. Hence Period 1 will also be x days. The chronology here is - Period 1: Transition Duration: Period 2.

There is no specific day on which users transition from one RFM segment to another. It is completely based on the whole period of analysis and relative to other users' actions.
Hovering over a segment shows -\
a. Total number is users who got into that segment and number of moved-in users as a percentage of overall user migration.\
b. Total number of users moved out of that segment and number of moved-out users as a percentage of overall user migration.

Hovering over a transition shows -\
a. Total number is users moved from a specific segment of period 1 RFM to a specific segment of period 2 RFM.\
b. It also displays the number of moved-out users as a percentage of overall user migration.

If your user role doesn’t have download permission, there will not be a download CTA for the user.
RFM Transition table shows the period 1 RFM segment names, period 2 RFM segment names,\
their respective user migration count, and percentage with respect to overall user migration.

### Why Model and Transition Counts Differ
RFM scores are relative rankings, so the size of a segment depends on which users are in the analysis.
The RFM Model ranks the users active in the date range you select. RFM Transition ranks users across Period 1 and Period 2 together. Because the two reports rank different sets of users, the same segment can show different counts for the same period. For example, the number of Champions in the RFM Model can be much smaller than the number of users who move from Champions to Champions in Transition.
Neither number is wrong. Compare counts within one report, and don't compare a Model count directly with a Transition count.
## Actionable Analytics on RFM
Users are able to create a custom segment or a campaign from RFM Chart or User Transition chart. Clicking on the chart area of the RFM segment or User Transition chord shows a popup, which let the user create a custom segment or campaign.


Creating a campaign from the RFM page on the MoEngage dashboard, the dashboard redirects to the selected campaign page with the chosen RFM or User transition segment. Users can complete the campaign creation on that page.
Actionable analytics on RFM creates a dynamic custom segment, which saves the RFM segment definition, not the exact users. The next time when a campaign with an RFM segment is sent, one time or periodically, that RFM segment gets calculated each of the sending times and the newly created RFM segment will be used in the campaign.
Custom segments saved from RFM analysis can be used with other segments. Other segments can have their own definition or can be fixed/uploaded as custom segments. In this way, RFM segments can be used with any other segments, which can be RFM segments uploaded by growth teams.
## RFM Distribution
RFM Distribution charts show the distribution of users on Recency, Frequency, and Monetary parameters. Recency Distribution is a distribution of time, from the last visit to the app or time since the last purchase. Frequency Distribution is a distribution of the number of times, users have visited the app or users made purchases. Monetary Distribution is a distribution of revenue generated by reach users.

The primary use for these charts is to analyze where users are located in the distribution chart with respect to overall users. Using these charts marketers can also customize RFM Segments - using these distribution values and executing them on the segmentation page will result in the desired segment based on RFM distribution.
# Rule-Based (Filter) Segment
Source: https://moengage.com/docs/user-guide/segment/create-segments/rule-based-filter-segments
Step-by-step guide to creating user segments in MoEngage using event filters, user properties, and behavioral rules for targeted campaign delivery.

**Rule Based Segments**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3133772-rule-based-segments)
A segment is a group of users defined by specific properties, values, or rules. Segments can be used to send campaigns or to analyze specific information or behavioral traits of users.
This article helps growth teams with segment definitions such as - Users who have opened the app in the last 30 days or Users whose Location is New York AND have executed Purchase at least 3 times in the last 30 days. Hence whenever this segment executes, all the users who fulfill the criteria become part of the segment.
After creating a user segment, follow it up with creating a campaign to target these users. [Learn more about creating campaigns in this article.](/docs/user-guide/campaigns-and-channels/mobile-push/create)
The MoEngage dashboard enables growth teams to create multiple types of segments, including [File Segments](/docs/user-guide/segment/create-segments/file-segments), Rule-Based Segments, and Custom Segments. [Learn more about segment types.](/docs/user-guide/segment/getting-started/types-of-segments) You can also build and count these segments conversationally through an AI assistant using the [MoEngage MCP segmentation tools](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server#segments).
This document explains Rule-Based Segments in detail and how to combine them with other segment types.
> [!TIP]
>
> **Prerequisites**
>
> Rule-based segments are built from user property data and event data sent from your app or website. Before creating rule-based segments, ensure that MoEngage SDK integration and event tracking are complete. [More details on integration in our documentation.](/docs/developer-guide/introduction)
>
> If you want to create a segment without SDK integration, use [File Segments](/docs/user-guide/segment/create-segments/file-segments) or [Warehouse Segments](/docs/user-guide/segment/create-segments/warehouse-segments) instead.
# Rule Based Segments
On the MoEngage dashboard, growth teams can create rules and criteria to define a user segment. The rules and criteria can be applied to user properties, events & event properties, and a combination of the two.
User properties are attributes of the user in the MoEngage system such as email, name, last location, etc. The value of user properties gets updated almost in real time and the latest values are available for calculation.\
Events are activities done by users such as App Open, Product Purchase, etc. These events also have event properties such as app version, platform name, product category, product price, etc. Event properties are tracked with events and are specific to the selected event.
# Creating Rule-Based Segments
To create a Rule-Based Segment, click on Segment on the sidebar and then click on Create Segments. This lands on the Create Segments page.
.png?fit=max\&auto=format\&n=SXGokmA3wsSiD1jZ\&q=85\&s=819a94b2a42f849d0f561d11afff977e)
## Use User Properties
Select the User Property section then:
1. Select desired user property and filter conditions.
2. When navigating the dropdown, the description of the first item is displayed in the right-hand panel by default. The attribute dropdown width dynamically adjusts based on your selected event and available screen space.
3. Provide the filter value/s to create a rule.
The description for the selected user property appears in the right section of the dropdown.

## Use Event and Event Properties
Select the User Behavior section then -
1. Select the execution condition and the desired user activity (event)
2. Provide event frequency and time duration for the event execution
3. If you change an attribute within the same event, your previously entered value is retained instead of cleared. The copy icon next to values allows you to copy them to your clipboard instantly.
4. Add Event property with a filter condition
5. Provide the filter value/s to create a rule.
The description for the selected event appears in the right section of the dropdown.

> [!NOTE]
>
> * MoEngage generates a few default user properties, events, and event properties. [A list of all derived events and attributes can be found in this article.](/docs/user-guide/data/event-data/derived-events-and-attributes)
> * The analysis of segments is performed based on server time for all of the time-bound analyses. For more information about server time, refer to [Event Time and Server Time](/docs/user-guide/data/event-data/event-time-and-received-time).
## Use User Affinity
Affinity Segments are groups of users created based on the user performing an action with a specific attribute value.\
[User affinity is explained in detail in this article.](/docs/user-guide/segment/create-segments/affinity-segments)
Select the User Affinity section then -
* Select the desired user activity (event)
* Select the user affinity parameter from - Predominantly, Minimum of, Most no. of times, and Least no. of times.
* For Predominantly & Minimum of, select affinity attribute with a filter condition and provide the affinity value/s.
* For Most no. of times & Least no. of times, provide top/bottom percentage of users
* Provide time duration for the event execution
* Add Event property with a filter condition and provide the filter value/s to create a rule.

## Use Custom Segment
Select the Custom Segment section, then select the desired custom segment to create a rule.\
[Custom Segments are explained in detail in this article](/docs/user-guide/segment/create-segments/manage-segments).
The description for the selected custom segment appears below the custom segment selection dropdown.

> [!NOTE]
>
> * You can duplicate primary filters and nested filter blocks using the Duplicate filter icon.
> * Individual attributes can be copied using the dedicated Copy icon.
# Teams in Segments
If teams are enabled for your account, you will be able to create segments for them by selecting the team from the Teams dropdown. Every team has a segment criteria specified for it during its creation. This condition gets added with an AND condition to segments created. For example, if you create a custom segment as a set of *users whose last known city is Los Angeles* and the segmentation criteria for your team is frequent buyers (users who have purchased products more than ten times in the last seven days), your custom segment will comprise frequent buyers whose last known city is Los Angeles. For more information, refer to [Teams in MoEngage](/docs/user-guide/settings/account/team-management/teams-in-moengage).
> [!NOTE]
>
> When Teams are enabled:
>
> * The **User Affinity** filter will not be available in the **Filter users by** section.
> * The **Select a segment** dropdown in the **Custom segment** filter section lists only the custom segments that are associated with the selected team.

> [!NOTE]
>
> MoEngage Teams with the Segmentation Filters is a Beta feature. To get it enabled for your account, reach out to your CSM.
# Combining Segments
Multiple User Property rules, User activity rules, User Affinity rules, and Custom Segments can be combined using AND, OR and Exclude conditions to create a robust and complex user segment.
> [!TIP]
>
> For advanced techniques such as nesting segment blocks within each other, aggregation operations, and object data type filtering, refer to the [Advanced Segmentation](/docs/user-guide/segment/advanced-concepts/segment-nesting) section.
With Nested AND/OR capabilities, along with (A AND B AND C AND D) and (A OR B OR C OR D) type of segments, complex segments such as the following can be created:
* (A AND B) OR (C AND D)
* (A OR B) AND (C OR D)
* (A OR B) AND C AND D
* (A AND B) OR C OR D
Use the 'Add Nested Filter' button to add a nested block (Event block - Event with all its filters. Nested block - Multiple nested event blocks)
The nested condition is preselected, opposite to the outer condition. If the outer condition is AND, the nested condition will be OR and vice-versa. By default, the nested condition is OR and the Outer condition is AND.
Both the nested as well as the outer conditions can be changed. When the outer condition is changed (let's say, from AND to OR), the nested condition automatically gets updated to the opposite condition (in this case, AND) and vice versa.

Nested AND/OR functionalities are available in segmentation as well as campaign creation pages in the target audience section. They are not supported in Trigger Criteria in Event-triggered campaigns.
A particular user segment can also be excluded from the selected user segment, to use this click on Exclude user checkbox.
# Segment Actions

### Show count
To see the user count for the created segment and other details explained in the Recent queries section below.
### Create
In Create, there are 2 options available:
1. Create Custom Segment - To save the created Segment as a Custom Segment, provide the segment name and click on Create button.

2. Create Campaign - To create a campaign using the created Segment, select the channel type and the campaign type. Clicking on Create Campaign will redirect to the respective campaign page with the created segment populated in the Target Audience section.
The following channels are available for Creating a campaign from Segmentation - Push, Email, SMS, Whatsapp, Cards, Facebook Audience, Google Ads Audience, In-App, and Connector campaigns.
**Note**: When Teams are enabled, you can only create SMS, Email, and WhatsApp campaigns.

### Analyze
Analyze a segment directly from the Segmentation page. This action auto-populates the segment in the Target audience section of Behavior, Funnels, Retention, Session and Source, User Paths, and RFM analysis.

# Recent Queries
The recent query section lists all the user segment queries run across the MoEngage dashboard. Be it segment queries run from Create Segment page or from All Campaigns (Email, Push, SMS, etc.), MoEngage users would be able to see contextual numbers for the target audience (Both Total and Reachable users on the channel where the query was made) along with query source information. When Teams are enabled, you will be able to see the recent queries for the selected team (team chosen in the Teams dropdown).

Segment execution at the respective campaign page adds extra filters (which are not present in the segment rules), these queries can be identified by the **Source** column. The same segment executed in Create Segment page and campaign page may result in different reachable user numbers as the campaign page segment shows the reachable users for the respective channel (Push, Email & SMS), and Create Segment page shows the reachable users across all channels.
Click on the refresh icon to rerun any query.
If there is a delay in the execution of any query, click on the email icon and provide the email address to get notified when the query execution is completed.

Click on any query row to expand it and view the details about the query -


On expanding a query, you will see
* **Reachable Users**
* where the source is Segmentation, it will show the reachable user count across all outbound channels (Push, Email & SMS). Reachable user count is also available for specific channels individually.
* where the source is the Push campaign, it will show the reachable user count for push notifications. Reachable user count is also available for Android, iOS, and Web platforms for the Push.
* **Sample user's** initials or GU(Stands for Guest) - Click on these bubbles to open the user profile
* **Edit query** option to edit the query.
* Campaign and Custom segments can be created using:
* **Create campaign** to create a campaign directly from the Segment page
* **Create custom segment** to create a custom segment for reuse later
* **Analyze segment**to analyze a segment in Behavior, Funnels, Retention, Session and Source, User Paths, and RFM analysis directly from the Segment page
* **Export users** option to export users and desired User Properties of the Segment. More details in this [article](/docs/user-guide/analyze/analytics/user-data-exports).
* **Show More** to see the list of all sample users. The sample users count is limited to 50 at this point.
# User Search
For a quick user view, users can be searched using ID, Email, Mobile No. or MoEngage ID. Just enter the text in the user search box and hit enter. MoEngage system will search for the provided text in all the four mentioned fields and show the results.

The search result shows the 50 users sorted on the last active time. This list of users can be sorted on any of the columns. Click anywhere on the row to open the respective user's [User Profile](/docs/user-guide/data/user-data/user-profile).

> [!NOTE]
>
> PII (Personally Identifiable Information) marked attributes are shown as **_Private_** or **---** in the User Search and Show more popup. [Know more](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
# Warehouse Segments - Overview
Source: https://moengage.com/docs/user-guide/segment/create-segments/warehouse-segments
Build audience segments in MoEngage using data from your data warehouse directly, with no need to copy or migrate data between platforms.

**Warehouse Segments**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3134411-warehouse-segments)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Warehouse segments enable you to create segments on MoEngage based on data from your data warehouse without the hassles of copying or moving it to MoEngage.
Let's say that your brand wishes to offer exclusive discounts to loyal shoppers based on an engagement score that is computed with your proprietary logic. This data is stored and accessible only from your data warehouse. With Warehouse segments, you can access this data from the warehouse directly, build an audience on MoEngage, and send a campaign from MoEngage within a few clicks.
Because the data stays in your warehouse, you get access to it without syncing delays, and it remains inside your own security and compliance boundary.
# How to Set One Up
**1. Connect your data warehouse**
Grant MoEngage read access and set up the connection. The steps differ by warehouse. Required for both methods below.
[Connect Your Data Warehouse](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse)
**2. Choose how you define the audience**
Write a SQL query, or build the segment from dropdown filters. See the comparison below.
**3. Map your warehouse schema (filters only)**
To use the filter builder, map your warehouse tables to MoEngage users, events, and attributes in **Settings**.
[Warehouse Schema](/docs/user-guide/data/warehouse-schemas)
# Two Ways to Define a Warehouse Segment
Both methods run against your warehouse and produce a custom segment you can target with a campaign.
| | [SQL tab](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql) | [Filter tab](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters) |
| - | - | - |
| Best if you | Are comfortable writing SQL | Would rather not write SQL |
| How you define the audience | A SQL query you write | Dropdown filters on mapped attributes and events |
| Setup needed | Warehouse connection | Warehouse connection, plus your tables mapped in [Warehouse Schema](/docs/user-guide/data/warehouse-schemas) |
| Warehouses | BigQuery, Snowflake, Databricks, Redshift | BigQuery, Databricks |
| Aggregations and custom SQL logic | Available | Not available |
| Segment type | Warehouse - SQL | Warehouse - filter |
Use filters for everyday audience building. Use SQL when your logic needs aggregations or transformations the filter builder does not cover.
# In This Section
> [card] [Connect Your Data Warehouse](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse)
>
> Grant read access and save a connection for BigQuery, Snowflake, Databricks, or Redshift.
> [card] [Create a Segment Using SQL](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql)
>
> Write a query that returns user IDs and save the result as a custom segment.
> [card] [Create a Segment Using Filters](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters)
>
> Build an audience from dropdown filters, with no SQL required.
> [card] [Warehouse Schema](/docs/user-guide/data/warehouse-schemas)
>
> In Settings. Map your warehouse tables to MoEngage users, events, and attributes.
# Connect Your Data Warehouse
Source: https://moengage.com/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse
Grant MoEngage read access to BigQuery, Snowflake, Databricks, or Redshift and save the connection in App Marketplace.
Before you can build a warehouse segment, connect MoEngage to your data warehouse and grant it read access to the tables you want to query. You do this once per connection, and it needs administrative access to your warehouse.
Select your warehouse below for the full setup steps. They differ by warehouse.
> [tab] Big Query
>
> Follow the below steps to grant read access to certain tables in BigQuery to MoEngage. Additionally, it covers providing access to BigQuery Jobs API, enabling Moengage to submit jobs and download query results.
>
> These instructions assume you have administrative privileges in the Google Cloud Platform, specifically in the project that hosts the BigQuery dataset and jobs.
>
> ### Create a Service Account for MoEngage
>
> 1. Open the [Google Cloud](https://console.cloud.google.com) Console.
> 2. Navigate to the project housing the **BigQuery** dataset and jobs.
> 3. Go to the **IAM & Admin** section and select **Service Accounts**.
>
> 
> 4. Click **Create Service Account**.
> 5. Provide a name for the service account (e.g., moengage-access).
>
> 
> 6. Set the appropriate role for the service account as **BigQuery Job User**.
>
> 
> 7. Create the service account.
> 8. Navigate to the **service account** and select the **KEYS** tab.
> 9. Click the **ADD** KEY dropdown and then select Create new key.
>
> 
> 10. Select **JSON** as the screen type in the pop-up
> 11. Click CREATE to generate and download the JSON key file.
> 12. Keep the JSON file securely and share it with MoEngag as below.
>
> Share the below details to [warehousesegments@moengage.com](mailto:warehousesegments@moengage.com) to get warehouse segments enabled on your workspace:
>
> 1. JSON key file of the service account created for MoEngage as per the steps above
>
> 2. Your MoEngage workspace name, along with your data cluster (DC)
>
> 3. Your BigQuery location
>
> > [!NOTE]
> >
> > To rotate the service account key later, follow the steps in [Rotating Your BigQuery Credentials](/docs/partner-guide/data-and-analytics/data-warehouses/google-bigquery#rotating-your-bigquery-credentials).
>
> ### Share Access to Specific Tables with Moengage
>
> 1. In the BigQuery console, navigate to the dataset containing the tables you want Moengage to access.
>
> 2. Click the **SHARING** dropdown and then select **Permissions.**
>
> 
>
> 3. Add the service account's email address (found in the JSON key file) as a member with the "BigQuery Data Viewer" role.
>
> 
>
> 4. Click **Save** to grant access to the dataset.
>
> ### Grant Access to BigQuery Jobs API
>
> Skip if access is already given in the first step.
>
> 1. In the Google Cloud Console, go to the **IAM & Admin** section and then select IAM.
>
> 2. Click **Grant Access**to add a new member.
>
> 3. Enter the service account's email address (found in the JSON key file).
>
> 4. Assign the **Role** as **BigQuery Job Use**r to enable interaction with the BigQuery Jobs API.
>
> 5. Click **Save** to grant access to the API.
>
> 
>
> > [accordion] Limit Access to Specific Tables (Optional)
> >
> > 1. Open the JSON key file shared with Moengage.
> > 2. Locate the private_key_id attribute in the JSON content.
> > 3. In the BigQuery console, open the dataset with the desired tables.
> > 4. Select the table(s) you want to restrict access to and click on "Share Table" from the context menu.
> > 5. Add the service account's email address as a member and restrict the role to "BigQuery Data Viewer" only for these table(s).
>
> By following the above steps, you have successfully granted Moengage read access to specific tables in BigQuery.
>
> Additionally, you have authorized access to the BigQuery Jobs API, allowing them to submit jobs and download query results. It is essential to review and manage access permissions periodically to maintain data security.
> [tab] Snowflake
>
> In order to run queries on data from Snowflake, you will first need to connect MoEngage to your Snowflake data warehouse.
>
> ### Steps to create a new Snowflake Connection
>
> 1. On your MoEngage Dashboard, go to the **App Marketplace.**
> 2. Search for Snowflake. 
> 3. Go to the **Integrate tab,** and click **Add Connection**
> 4. Provide your Snowflake data warehouse details.
>
> 
>
> Enter the following fields in Snowflake.
>
> 1. **Connect Name:** Give this connection an identifiable name, e.g., My Snowflake Prod
>
> 2. **Snowflake Account Identifier**
> * It is always found at the beginning of your Snowflake URL, for example; ([https://ACCOUNT_IDENTIFIER.snowflakecomputing.com](https://ACCOUNT_IDENTIFIER.snowflakecomputing.com)).
> * The format may differ based on Snowflake account age. For details, [refer to Snowflake documentation.](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html)
>
> 3. If you're using Snowsight, you can find **your account name** at the bottom of the left navigation. Select the account you want to import from and then click on the “copy” icon to copy the Account ID. For up-to-date information and details, [refer to Snowflake documentation.](https://docs.snowflake.com/en/user-guide/admin-account-identifier.html)
>
> 
>
> 4. **Warehouse:** The name of the warehouse MoEngage uses to execute the queries. For example, COMPUTE \_WAREHOUSE
>
> 5. **Database:** The database that MoEngage should use to read the tables from. You can choose the schema while setting up warehouse segments/imports/exports. e.g., MY_DEMO_DB
>
> 6. **Username:** The database that MoEngage should use to read the tables from. You can choose the schema while setting up warehouse segments/imports/exports.
>
> 7. **Authentication Method:** MoEngage can connect to your Snowflake Instance using two methods:
> * **Password:** If you select a password, provide the password of the database user (username) you entered above.
> * **Key:** If you select "Key" as your authentication method. Perform the below-mentioned steps.
> * Click on "Generate Key," and MoEngage will display your public key. You will need to add this public key to your database user. Follow the instructions mentioned on [Snowflake help docs](https://docs.snowflake.com/en/user-guide/key-pair-auth#assign-the-public-key-to-a-snowflake-user) to set this up: **Key** - MoEngage can connect to your Snowflake Instance using the Key pair authentication method. To use this method: 
> * Once you have added this key to your database user, click on "Test connection," and MoEngage will attempt to verify the credentials.
>
> 8. MoEngage also supports the rotating of keys. If your IT Policy requires to rotate the keys, you can do it by following these steps:
> * Go to the **App Marketplace** > **Snowflake** > **Integrate and edit the connection.**
> * Click on the generate new key icon: 
> * You will be asked for a confirmation to review. Please read the instructions carefully. Once you save the connection with the newly generated key, MoEngage will no longer use the previous key. You have to ensure that the new key is attached to your database user as the second RSA key (see [Snowflake](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation) help doc on rotating keys) for the rotation to work properly. If the new key is not attached after saving the connection, your imports and exports might break:
>
> 
> * Your new key will be generated and shown to you. At this point, it is highly recommended to copy this new key and attach it as an additional key to your Snowflake database user by following the instructions provided on the [Snowflake help docs](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation). Once you have attached the new key, you need to test the connection successfully to complete the rotation.
> * If you decide to close the edit form or do not click **Connec**t at any point after generating the new key, your old (existing) key will continue to be used as before, and the newly generated key will be deleted from our system.
>
> 9. **Role:** This role will be used to execute queries from MoEngage.
>
> Once you have set up a Snowflake Connection, you can use it to set up warehouse segments, imports and exports in MoEngage. If your Snowflake instances aren't public and are on AWS, we recommend you set up [AWS Private Link](https://docs.snowflake.com/en/user-guide/admin-security-privatelink) with MoEngage AWS account. Please reach out to your account manager for more information on this.
> [tab] Databricks
>
> In order to run queries on data from Databricks, you must connect MoEngage to your Databricks warehouse. Ensure, you have administrative privileges in the Databricks platform.
>
> ### Steps to grant read access to MoEnagage
>
> 1. [Add a service principal in Databricks](#add-a-service-principal-in-databricks)
> 2. [Assign a service principal to Databricks workspace](#assign-a-service-principal-to-databricks-workspace)
> 3. [Provide data reader access to the service principal](#provide-data-reader-access-to-the-service-principal)
> 4. [Provide compute permissions on SQL warehouses to service principal](#provide-permissions-for-service-principal-to-compute-on-sql-warehouses)
> 5. [Create a personal access token (PAT)](#create-a-personal-access-token-pat)
> 6. [Fetch the HTTP path and Hostname](#fetch-the-http-path-and-hostname)
> 7. [Connect Databricks on the App Marketplace](#connect-databricks-on-the-app-marketplace)
>
> ### Add a Service Principal in Databricks
>
> Account admins can add service principals to the Databricks account using the account console. For more information, refer [here.](https://docs.databricks.com/aws/en/admin/users-groups/service-principals#add-service-principals-to-your-account-using-the-account-console)
>
> Perform the following steps to add a service principal:
>
> 1. Log in to your [account console](https://accounts.cloud.databricks.com/) in Databricks as an admin.
> 2. In the sidebar, click **User Management**.
> 3. On the **Service principals** tab, click **Add Service principal**.
> 4. Enter a name for the Service principal.
> 5. Click **Add**.
>
> ### Assign a Service Principal to Databricks Workspace
>
> As an admin, assign a service principal to a workspace using the [account console](https://accounts.cloud.databricks.com/). For more information, refer [here](https://docs.databricks.com/aws/en/admin/users-groups/service-principals#assign-a-service-principal-to-a-workspace-using-the-account-console).
>
> Perform the following steps to assign permissions:
>
> 1. Log in to your account console in Databricks as an admin.
> 2. In the sidebar, click **Workspaces**.
> 3. Click your workspace name.
> 4. On the **Permissions** tab, click **Add permissions.**
> 5. Search for and select the service principal, and assign the permission level (Workspace **User**). You can assign the [workspace admin role](https://docs.databricks.com/aws/en/admin/users-groups/service-principals#add-sp-admin-console) to the workspace admin settings page.
> 6. Click **Save**.
>
> ### Provide Data Reader Access to The Service Principal
>
> Provide data reader access, as shown below to the entire workspace or individual schemas to the service principal, ensuring that the tables you want to query in MoEngage are available in the schema.
>
> 
>
> ### Provide Permissions for Service Principal to Compute on SQL Warehouses
>
> Perform the following steps to provide compute permissions:
>
> 1. In the Databricks dashboard, Click **Settings > Compute > SQL warehouses**
> 2. Select the warehouse that needs to be accessed by the service principal.
> 3. Click **Permissions**. In the list, select *Can use* for the service principal.
>
> 
>
> ### Create a Personal Access Token (PAT)
>
> You can create a PAT for a service principal using Databricks CLI. For more information, refer [here](https://docs.databricks.com/aws/en/dev-tools/auth/pat#step-1-as-a-databricks-admin-create-a-pat-for-your-databricks-service-principal-from-the-cli).
>
> > [accordion] Create a PAT for a user (optional)
> >
> > You can also create a user, assign appropriate access to the user, and allow MoEngage to access your warehouse from that user’s role. However, Databricks recommends the service principal approach. In case you want to create a personal access token for a user, please follow the steps below:
> >
> > 1. In your Databricks workspace, select your Databricks username in the title bar, and then select **Settings** from the dropdown list.
> > 2. On the **Access Tokens** tab, select **Generate New Token.**
> > 3. Enter a comment to identify this token, and change the token’s lifetime to no lifetime by leaving the Lifetime box empty.
> > 4. Click **Generate** and copy the generated token
> > 5. Click **Done**. 
>
> ### Fetch the HTTP Path and Hostname
>
> Perform the following steps to fetch the HTTP path and Server hostname, which MoEngage requires to access your Databricks workspace.
>
> 1. In your Databricks workspace, select **SQL warehouses**.
> 2. Choose your warehouse.
> 3. Click the **Connection details** tab and copy the hostname and HTTP path provided, which is required for MoEngage.
>
> 
>
> ### Connect Databricks on the App Marketplace
>
> To connect Databricks on the App marketplace, perform the following steps:
>
> 1. On the left navigation menu in the MoEngage dashboard, click **App marketplace**.
>
> 2. On the App Marketplace page, search for **Databricks**.
>
> 
>
> 3. Click the **Databricks** tile.
>
> 4. On the Databricks page, go to the **Integrate** tab and click +**Add Connection**.
>
> 5. Enter the following details:
> | Field | Required | Description |
> | - | - | - |
> | **Connection name** | Yes | Type a name for the Databricks connection. |
> | **Host name** | Yes | This refers to the unique identifier assigned to a specific cluster. Type the hostname that you want to connect. To find your server hostname, visit the Databricks web console and locate your cluster. Then, click to reveal Advanced options and navigate to the JDBC/ODBC tab. |
> | **Port** | Optional | Type the port to which you want to connect your Databricks server. It defaults to 443. |
> | **HTTP path** | Yes | Type the HTTP path of your compute resource on Databricks. To find your HTTP path, go to your Databricks workspace, locate your warehouse, and then get your HTTP path from the connection details tab. |
> | **Access token** | Yes | This is an authentication token used to access Databricks APIs securely. Type the Access token, which helps you make authorized requests to the Databricks server with the necessary permissions. On your Databricks workspace, go to **Settings** > **Developer** > **Access tokens** > **Manage tokens**. |
> | **Catalog** | Yes | Type the Databricks Catalog name to which MoEngage will have access. |
> |  | | |
>
> 6. Click **Connect**. Your Databricks connection is now integrated.
>
> After you have set up a Databricks connection, you can use it to set up various imports and exports in MoEngage.
>
> > [!NOTE]
> >
> > Ensure at least two to five minutes of warm-up time when MoEngage connects to Classic and Pro SQL instances. There might be a delay in connection setup and testing, as well as during warehouse segment query execution, segment creation, and refresh. Using a serverless SQL instance will minimize warmup time and improve query throughput but may result in slightly higher integration costs
> [tab] Redshift
>
> To run queries on data from Redshift, you must connect MoEngage to your Redshift warehouse and ensure you have administrative privileges on the Redshift platform.
>
> > [!NOTE]
> >
> > * Administrative privileges on the Redshift platform.
> > * Trust Policy JSON obtained from MoEngage
>
> ### Steps to create an IAM role and Provide Access to MoEnagage
>
> > [!NOTE]
> >
> > If you have created a Redshift connection earlier, make sure you have the [current permissions](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse) listed below.
>
> ### Step 1: Create an Identity and Access Management (IAM) Role in Your Account
>
> 1. Sign in to your AWS account in the **AWS Management Console**.
>
> 2. In the **Find Services** search box, search for IAM. You will be directed to the IAM dashboard. 
>
> 3. In the IAM dashboard, select the **Roles** tab.
>
> 4. Click **Create role.**
>
> 5. Select **AWS account**.
>
> 6. Under the **Select trusted entity** section, select **Custom trust policy.**
>
> 
>
> 7. Paste the Trust Policy JSON obtained from MoEngage, as shown below. MoEngage's AWS Account ID is 612427630422. Ensure this ID is present in the trusted relationship JSON.
> ```text theme={null}
> {
> "Version": "2012-10-17",
> "Statement": [
> {
> "Effect": "Allow",
> "Principal": {
> "Service": [
> "redshift.amazonaws.com",
> "ec2.amazonaws.com"
> ]
> },
> "Action": "sts:AssumeRole"
> },
> {
> "Effect": "Allow",
> "Principal": {
> "AWS": "arn:aws:iam::612427630422:root"
> },
> "Action": "sts:AssumeRole"
> }
> ]
> }
> ```
>
> 8. Select **Allow assuming roles** from this account option.
>
> 9. Click **Next** > **Permissions.**
>
> 10. Add the permissions mentioned below:
> ```text theme={null}
> redshift_finegrained (customer-managed policy)
> ```
> ```text theme={null}
> {
> "Version": "2012-10-17",
> "Statement": [
> {
> "Sid": "DataAPIPermissions",
> "Action": [
> "redshift-data:ExecuteStatement",
> "redshift-data:CancelStatement",
> "redshift-data:ListStatements",
> "redshift-data:GetStatementResult",
> "redshift-data:DescribeStatement",
> "redshift-data:ListDatabases",
> "redshift-data:ListSchemas",
> "redshift-data:ListTables",
> "redshift-data:DescribeTable"
> ],
> "Effect": "Allow",
> "Resource": "*"
> },
> {
> "Sid": "Redshiftminimal",
> "Action": [
> "redshift:Get*",
> "redshift:Describe*"
> ],
> "Effect": "Allow",
> "Resource": "*"
> },
> {
> "Effect": "Allow",
> "Action": "iam:CreateServiceLinkedRole",
> "Resource": "arn:aws:iam::*:role/aws-service-role/redshift.amazonaws.com/AWSServiceRoleForRedshift",
> "Condition": {
> "StringLike": {
> "iam:AWSServiceName": "redshift.amazonaws.com"
> }
> }
> }
> ]
> }
> ```
> ```text theme={null}
> stsAssumerRole (customer-managed policy)
> ```
> ```text theme={null}
> {
> "Version": "2012-10-17",
> "Statement": [
> {
> "Sid": "123",
> "Effect": "Allow",
> "Action": [
> "sts:AssumeRole"
> ],
> "Resource": [
> "*"
> ]
> }
> ]
> }
> ```
>
> 11. You can optionally restrict access to specific db-groups and users by selecting those options in the policy editor. 
>
> 12. Click **Next.**
>
> 13. In the **Add tags** section, click the Add new tag button to add the tags required for this IAM role.
>
> 
>
> 14. Click on **Next** > **Review.**
>
> 15. In **Role name** box, enter the name for your role (for example, moengage-redshift-data-access-role"). 
>
> 16. Click on **Create IAM role**. 
>
> ### Step 2: Share Details with MoEngage
>
> Share the following details to [*warehousesegments@moengage.com*](mailto:warehousesegments@moengage.com) to get warehouse segments on Redshift enabled on your workspace:
>
> * **ARN** (Amazon Resource Name):
> * In your AWS Management Console, go to the IAM dashboard and select the IAM Role that you created in step 1.
> * Copy the ARN for the IAM role. MoEngage will use this ARN to assume the IAM role in your account to access the Redshift cluster. 
> * **Database name:** The default Redshift database name is used for the queries that will be running. It is recommended that separate connections be created for each database.
> * **Redshift Cluster Identifier name:** It is recommended that separate connections be created for each provisioned Redshift cluster.
> ```text theme={null}
> #{
> "role_arn" : "arn:aws:iam::5822XXXX730:role/Segmentation_Redshift",
> "aws_regions" : "ap-south-1",
> "cluster_identifier" : "redshift-segmentation-cluster",
> "default_db" : "dev",
> }
> ```
# Next Steps
With a connection saved, choose how you want to define your audience:
* To write a query that returns user IDs, refer to [Create a Segment Using SQL](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql).
* To map your tables so your marketers can build segments from dropdown filters, refer to [Warehouse Schema](/docs/user-guide/data/warehouse-schemas).
# Create a Warehouse Segment Using Filters
Source: https://moengage.com/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters
Build an audience from your data warehouse using dropdown filters instead of SQL, with attributes and events mapped from your warehouse tables.
The filter builder lets you build audiences from data in your warehouse using the same dropdown filters you use for regular MoEngage segments. You pick attributes and events from a list rather than writing a SQL query, so you do not need to involve your analytics team to create or change a segment.
MoEngage builds the SQL for you and runs it against your warehouse. Your data stays where it is. This is one of two ways to build a warehouse segment. For a comparison with the SQL method, refer to [Warehouse Segments - Overview](/docs/user-guide/segment/create-segments/warehouse-segments).
> [!NOTE]
>
> **Prerequisites**
>
> * A connected data warehouse. For more information, refer to [Connect Your Data Warehouse](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse).
> * Your warehouse tables mapped to MoEngage users, events, and attributes. Your data or engineering team does this once in [Warehouse Schema](/docs/user-guide/data/warehouse-schemas). Only mapped columns appear in the dropdowns.
> [!NOTE]
>
> The filter builder supports **BigQuery** and **Databricks**.
# Build a Segment
Building an audience and acting on it are two separate steps. You define filters and run them to get a count, and the result lands in **Query results**, where you turn it into a segment, a campaign, or an export.
To build a warehouse segment, perform the following steps:
1. On the sidebar menu in MoEngage, click **Segment** > **Warehouse Segments**. The Warehouse Segments page appears.
2. Select your warehouse connection from the dropdown beside the page title. The attributes and events mapped from that connection load into the filter dropdowns.
3. Select the **Filter** tab.

4. Build your audience in the filter block. Each block filters on either a **User property** or a **User behavior**. Use the toggle to switch between them.
* To narrow the same block further, click **+ Nested Filter**.
* To add a separate condition, click **+ Filter**.
* To remove everyone matching a condition instead of including them, select **Exclude Users**.
* To start over, click **Reset Filters**.
5. Click **Show count**. MoEngage builds the SQL, runs it against your warehouse, and adds a row to **Query results** below.
6. In **Query results**, click the ellipsis icon on the row and select what to do with the audience. For more information, refer to [Act on the Result](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters#act-on-the-result).
> [!NOTE]
>
> There is no save button on this page. A warehouse segment becomes reusable only when you create a custom segment from a query result.
# Filter on User Properties
Select **User property** in a filter block to filter on the properties mapped from your user master table. Each row reads as attribute, operator, then value.

The value dropdown lets you compare the attribute against a **Constant value** you type, or against another attribute.
Only properties your data team mapped appear here, under the display names they gave them. Columns that were skipped during mapping are not available. If a property you expect is missing, ask your data team to map it in [Warehouse Schema](/docs/user-guide/data/warehouse-schemas).
# Filter on User Behavior
Select **User behavior** in a filter block to filter on what users did. Choose **Has Executed** or **Has Not Executed**, select the event, then set how many times and over what period.

Two links appear under the filter:
* **+ Attributes** narrows the filter to specific event property values, such as an order above a certain amount.
* **+ Aggregation** filters on a computed value across the matching events rather than on a count of them.
Only events and attributes your data team mapped appear here. The event names are the display names set on each event schema.
## Event Occurrence Operators
Set how many times a user performed the event:
| Operator | What it matches |
| - | - |
| **exactly** | The user performed the event exactly n times. |
| **at least** | The user performed the event n or more times. |
| **at most** | The user performed the event n or fewer times. |
| **for the first time** | The user's first occurrence of the event falls inside the date range, with no occurrence before it. |
| **for the last time** | The user's most recent occurrence of the event falls inside the date range. |
> [!NOTE]
>
> **for the first time** and **for the last time** are bounded by the **Max event look-back** window set on your warehouse connection, which is 60 days by default. An event that first occurred before that window looks like a first occurrence inside it.
# Operators by Data Type
Available operators depend on the MoEngage data type your team mapped the column to.
| Data type | Operators |
| - | - |
| **String** | is, is not, contains, contains spaces, does not contain, starts with, does not start with, ends with, does not end with, exists, does not exist, is empty, is not empty |
| **Boolean** | is, is not, exists, does not exist |
| **Numeric** | is equal to, is not equal to, is between, is not between, is less than, is greater than, exists, does not exist |
| **Array (numeric)** | (any of / all of) is equal to, is not equal to, (any of / all of) is between, is not between, (any of / all of) is less than, (any of / all of) is greater than, exists, does not exist |
| **Array (string)** | (any of / all of) is, is not, (any of / all of) contains, (any of / all of) contains spaces, does not contain, (any of / all of) starts with, does not start with, (any of / all of) ends with, does not end with, exists, does not exist, (any of / all of) is empty, is not empty |
| **Date / time** | on, is between, before, after, in the next, in the last, is today, exists, does not exist |
| **Time of the day** | is, is between, in the following |
| **Day of the week** | is, is between, in the next, in the last, is today, in the following |
| **Day of the month** | is, is between, in the next, in the last, is today, in the following |
| **Month of the year** | is, is between, in the next, in the last, is this month, in the following |
You can also compare one attribute against another, and use special date filters, as you can in rule-based segments. For more information, refer to [Filters in Segmentation](/docs/user-guide/segment/advanced-concepts/filters-in-segmentation).
# Read the Query Results
Every time you click **Show count**, MoEngage adds a row to **Query results**. Each row records what you ran and what it returned.

| Column | What it means |
| - | - |
| **Query Time** | When the query ran. |
| **Description** | The filter conditions in plain language, so you can tell runs apart. |
| **Source** | The warehouse connection the query ran against. |
| **User Count** | How many users MoEngage could resolve from the rows your warehouse returned. |
| **Reachable Users** | How many of those users can receive a campaign on at least one channel. |
Click the refresh icon to re-run a query without rebuilding the filters.
> [!NOTE]
>
> The user count is usually smaller than the number of rows your warehouse matched. A row becomes a user only if its user identifier matches a user already in MoEngage. If your warehouse returns 1,000 rows and 90 of those users exist in MoEngage, the count is 90.
>
> That number is not fixed either. The same query can resolve to more users later, as those users become known to MoEngage.
# Act on the Result
Click the ellipsis icon on a query result row to choose what to do with the audience.

| Action | What it does |
| - | - |
| **Create custom segment** | Saves the audience as a reusable custom segment. This is how a warehouse query becomes something you can target repeatedly. For more information, refer to [Manage Segments](/docs/user-guide/segment/create-segments/manage-segments). |
| **Create campaign** | Starts a campaign with this audience already selected. |
| **Export users** | Exports the users the query resolved. For more information, refer to [Outbound Segment Sync](/docs/user-guide/data/exports/segments/outbound-segment-sync). |
| **Show sample users** | Shows a sample of the users the query matched, so you can sanity-check the audience before acting on it. |
| **Edit query** | Loads the filters back into the builder so you can change them and run again. |
## When Queries Run
MoEngage queries your warehouse at three points: when you click **Show count**, when you re-run a query result or a saved custom segment, and automatically at campaign run time for any campaign using a segment built this way.
> [!WARNING]
>
> These queries run on your data warehouse directly, so you incur the compute costs your warehouse charges for them. Checking counts repeatedly while building a segment runs a query each time.
# After You Create a Custom Segment
A custom segment created from a query result behaves like any other custom segment on the All Segments page, where it appears with the type **Warehouse - filter**. To show only these segments, select that type in the **Select Segment Type** list. You can view, edit, duplicate, archive, and create a campaign from the segment. For more information, refer to [Manage Segments](/docs/user-guide/segment/create-segments/manage-segments).
The segment detail page shows its type, source connection, creation date, last run time, user count, reachability, and edit history. Running the segment from this page refreshes the user count by re-querying your warehouse.
Exports return MoEngage attributes. MoEngage cannot resolve warehouse attribute values during an export, so warehouse columns are not included.
# Limitations
The filter builder does not support:
* **All Users segments.** Every warehouse segment needs at least one filter.
* **Value suggestions.** Attribute value dropdowns stay empty, so type values manually.
* **Analyse.** A warehouse segment cannot be used as the audience for an analysis.
* **Custom segment, affinity, and analytics filters** inside a warehouse segment.
## Unsupported Attribute Types
Attributes of these types cannot be filtered on, because they are not mappable in a warehouse schema:
* Object and object array attributes.
* Location attributes.
* Boolean arrays and date arrays.
For the full list of what can and cannot be mapped, refer to [Data Types](/docs/user-guide/data/warehouse-schemas#data-types).
## Unsupported Aggregations
Aggregating on a warehouse attribute is not available yet. The following aggregations are not supported at all:
* **Median.**
* **Change** and **percentage change.**
## One Connection per Query
A query reads from one warehouse connection. To combine data across connections, create a custom segment per connection and combine those on the standard segment builder.
# When a Segment Breaks
A warehouse segment depends on the warehouse tables behind it staying as they were mapped. If a column is renamed, a table is dropped, or a data type changes, the segment stops working.
> [!WARNING]
>
> You are not notified when this happens. A broken segment fails the next time it runs, which may be at campaign run time.
If a segment stops returning a count, ask your data team to check the mapping in [Warehouse Schema](/docs/user-guide/data/warehouse-schemas). Once it is corrected, run the segment again.
# Frequently Asked Questions
> [accordion] Why is my segment smaller than the number of rows returned?
>
> MoEngage only targets users it already knows. A row in your warehouse becomes a segment member only if its user identifier matches a customer ID in MoEngage. Rows for users MoEngage has never seen are skipped.
>
> Mapping a warehouse schema does not import users. To bring new users into MoEngage, use [Imports](/docs/user-guide/data/imports/overview/overview-imports).
> [accordion] I added a column in my warehouse but cannot find it in the dropdown.
>
> Two things have to happen first.
>
> MoEngage refreshes warehouse metadata every 6 hours, so a column added just now may not be visible yet. Your data team can use **Force refresh** on the schema to pick it up sooner.
>
> Then the column has to be mapped. Unmapped and skipped columns never appear in the segment builder, even after a refresh.
> [accordion] Why are the attribute value dropdowns empty?
>
> Value suggestions are not available for warehouse attributes. Listing the distinct values of a column means scanning the whole table in your warehouse, which is slow and costly, so MoEngage does not do it automatically.
>
> Type the value you want to filter on. It must match what is stored in your warehouse, including capitalisation.
> [accordion] Can I combine warehouse data with data already in MoEngage?
>
> Not inside a single warehouse segment, because one segment reads from one connection.
>
> Run your warehouse filters, then use **Create custom segment** on the query result. That custom segment can be combined with MoEngage attributes and events on the standard segment builder.
> [accordion] Does the segment refresh on its own?
>
> A segment used in a campaign refreshes automatically at campaign run time, so the campaign targets a current audience.
>
> Elsewhere, the count you see is from the last run. Run the segment from its detail page to refresh it.
> [accordion] How far back does event data go?
>
> As far back as the **Max event look-back** window set on your warehouse connection, which defaults to 60 days. Events older than that are not visible to any filter, including **for the first time**.
>
> Your data team sets this in **Settings** > **Data** > **Warehouse Schema**. Longer windows scan more data and cost more to query.
> [accordion] My segment worked last week and is failing now.
>
> Something in the underlying warehouse table most likely changed, such as a renamed or dropped column, a changed data type, or a deleted schema. MoEngage does not warn you when this happens, so a working segment can start failing without notice.
>
> Ask your data team to review the mapping in [Warehouse Schema](/docs/user-guide/data/warehouse-schemas). Once it is corrected, run the segment again.
> [accordion] Why can I not run an analysis on a warehouse segment?
>
> Analysis needs event data stored inside MoEngage. A warehouse segment resolves to a list of users at run time and carries no warehouse event history with it, so there is nothing for an analysis to read.
>
> You can still target the segment with campaigns and see campaign performance as normal.
# Create a Warehouse Segment Using SQL
Source: https://moengage.com/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql
Write a SQL query against your connected data warehouse and save the result as a custom segment in MoEngage.
Once you have [connected your data warehouse](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse), you can write a SQL query against it and save the users it returns as a custom segment.
> [!NOTE]
>
> If you would rather build a segment from dropdown filters than write SQL, refer to [Create a Warehouse Segment Using Filters](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters).
# Run a Warehouse Query
1. Navigate to the **Warehouse segment** tab under **Segment** on the MoEngage dashboard.
2. Here, you can choose the data warehouse connection you [set up earlier](/docs/user-guide/segment/create-segments/warehouse-segments/connect-your-warehouse), from the **Source** dropdown on the top.
3. Once a source is chosen, the data warehouse **schema** - database, tables, and columns, will be populated on the left panel. From here, you can search for any database, table, or column that you want to use in your query. The schema is refreshed every hour.
4. You can enter your SQL query in the **SQL editor** on the right. You can perform any operations, such as joining multiple tables, sub-queries, aliases, etc., as required to return your optimal results.
5. Click on **Run Query** to run the SQL query in your data warehouse. You should be able to see a new row added in the Query results section below.

6. The **Query results** section provides a list of recently run warehouse queries with query metrics such as Run time, Data scanned, and the number of rows of data returned by a specific query from your data warehouse. These metrics are useful for gauging the performance of your data warehouse queries and can be used to optimize your queries while you write them on MoEngage.
1. Credits used per query are available for Snowflake.
2. Databricks does not provide credits utilized when a query is executed; hence, regularly monitoring the [usage](https://docs.databricks.com/aws/en/admin/account-settings/usage) is recommended.
3. Redshift does not provide data scanned when a query is executed; hence, regularly monitoring the usage is recommended.
7. The Query results section also provides the status of each warehouse query run from MoEngage. The status can be successful, failed, or processed.
8. Once a query has run successfully, you should be able to expand the row from the Query results section and see the sample results of each query. We show up to 100 rows and 10 columns of data for each query.
9. Each query result also has a set of actions that can be accessed from the 3-dot menu on each row.
* **Insert in SQL editor:** You can directly insert a particular SQL query from the Query results section on the editor.\
Do note that this action will replace any existing query in the editor.
* **Create a custom segment:** You can directly create a custom segment from any query result. However, we expect the query to return a single column of IDs (the unique user identification that is present as an ID in MoEngage) in order to be saved as a custom segment. Hence, this option will be active only for those queries that return a single column.
* **Copy query:** This action will copy the query to the clipboard.
* **Run query:** You can run the query from Query results directly using the Run query action. A new row will be added to the Query results section at the top for the new execution.
* **Download results**:You can download the results of a query using the download results action. The downloaded file will contain a maximum of 100 rows and 100 columns of data 
10. **Preview Table**: Now you can one-click preview a few sample rows from any table listed in the schema section. On hovering over a table name in the schema, you should be able to see an eye icon, clicking on this will run a sample query on the table providing up to 10 rows of data as a preview.
> [!WARNING]
>
> 1. The SQL query must return a single column of IDs in order to be saved as a custom segment. If the query returns multiple columns, the segment will not return any users.
> 2. The SQL query runs on your data warehouse directly. Please note that when utilizing this feature, you will incur the costs associated with running the queries from your data warehouse.
> 3. The SQL queries are subject to a 15-minute timeout limit. To manage warehouse costs and ensure efficiency, optimize your SQL scripts for faster execution.
> 4. The SQL query should be compatible with your DWH. If you are using Warehouse segments on BigQuery, the SQL query must be supported by [GoogleSQL.](https://cloud.google.com/bigquery/docs/introduction-sql) Similarly, Snowflake supports [Standard SQL](https://docs.snowflake.com/guides-overview-queries) for querying, Databricks supports [ANSI standard SQL,](https://www.databricks.com/blog/2021/11/16/evolution-of-the-sql-language-at-databricks-ansi-standard-by-default-and-easier-migrations-from-data-warehouses.html) and Redshift supports [PostgreSQL](https://docs.aws.amazon.com/redshift/latest/dg/c_SQL_commands.html).
# Define a Warehouse Custom Segment
Once the SQL query is finalized, you can proceed to create a custom segment. We expect the custom segment query to return a single column of IDs (the unique user identification that is present as an ID in MoEngage). Give a name and a description for the segment.

# Use the Warehouse Custom Segment
Custom segments created this way are of type **Warehouse - SQL** and are listed on the All Segments page.

## Actions Possible on External Custom Segments
* **View** - View the details of the custom segment on the segment info page. Here you can:
* View the SQL query that defines the segment
* Run the custom segment to update user count - This is when MoEngage connects to your data warehouse, runs the SQL query, and updates the user count.
* **Edit** - You can edit the SQL query that was used to define the custom segment
* **Create campaign** - You can create a campaign directly from the All Segments page. The target audience section of campaign creation will be populated with the selected custom segment.
* External data warehouse segments can be combined with other custom segments as well as user properties, and behaviors captured in MoEngage.
# Refresh the User Count of a Warehouse Segment
You can update the user count of an external data warehouse segment in two ways:
* **On campaign run-time** - The data warehouse segment that is part of the Target audience of a campaign will auto-refresh at the campaign run-time.
* **Run the custom segment from the segment info page** - You can also run the segment manually from the segment info page.

# Considerations
* One warehouse segment can be defined on one data warehouse connection. You can combine multiple custom segments pointing to different sources and create a new custom segment.
* Running analysis - Behaviour, Funnel, etc., will not refresh the user count of a warehouse segment. The target audience containing a warehouse segment will either:
* Return 0 if the segment has never run.
* Return the last run count of users if the segment has run before.
# How to Troubleshoot Campaigns with Segmentation Scenarios Containing Date of Birth?
Source: https://moengage.com/docs/user-guide/segment/faqs-segment/how-to-troubleshoot-campaigns-with-segmentation-scenarios-containing-date-of-birth
Fix issues with birthday-based campaigns not reaching users by validating date-of-birth segmentation conditions and time zone settings in MoEngage.
## Problem
Users segmented based on their date of birth are not receiving campaigns.
## Instructions
Perform the following steps:
1. Validate the segmentation condition used. Ensure the birthday condition is set to "Birthday yearly where the date is today."

2. Ensure the timing is set based on the user’s time zone.
## Example
If a user's birth date is May 24, 1998, at 3:00, and they did not receive the campaign:
* The birth date is stored in the MoEngage data warehouse as "1998-05-24 00:00:00.000."
* If the database time zone is Egypt (UTC '+03:00), the birth date is adjusted accordingly.
If the segment execution time was recorded at "2024-05-24T21:45:02.804+00:00" (UTC) in the Egypt time zone, it converts to "2024-05-25T00:45:02." Thus, the date becomes May 25, causing the issue.
> [!NOTE]
>
> The birth_date attribute is a custom attribute.

# Why Did My Campaign Send to Zero Users When the Segment Has Users?
Source: https://moengage.com/docs/user-guide/segment/faqs-segment/why-did-my-campaign-send-to-zero-users-when-the-segment-has-users
Troubleshoot a MoEngage campaign that resolves to zero recipients even though the selected segment returns users, including the Developer role test-device restriction.
## Problem
A campaign targets a segment that returns users when you run the segment query, but the campaign resolves to 0 recipients. Segmentation completes successfully and returns an accurate count of 0.
## Instructions
Check whether a user with the Developer role created the campaign on a live app.
On a live app, MoEngage limits campaigns created under the [Developer role](/docs/user-guide/settings/account/team-management/access-roles#developer) to users marked as test users or test devices. The campaign audience becomes the intersection of the selected segment and your test users, so a segment that contains no test users resolves to 0 recipients. In segmentation debug output, this restriction appears as an added `moe_test_device = true` filter on the query.
To confirm, open the campaign and check the role of the user who created it.
To reach the full segment, choose one of the following options:
* Ask a user with a role that publishes to live users — Admin, Manager, or Marketer — to create the campaign, or to duplicate the campaign and send it.
* Mark the users you want to reach as test users before you send the campaign from a Developer account.
* Send the campaign from a test app when the intent is Developer testing.
When the campaign uses the [campaign approval workflow](/docs/user-guide/settings/account/team-management/campaign-approval-workflow), an approver who edits the campaign before approving it passes their own role to the campaign, which also changes who the campaign targets.
## Example
A custom segment returns 146 users, but the campaign built on that segment reaches 0 recipients. A user with the Developer role created the campaign on a live app, so the test-device restriction applies. The segment contains no test users, so the intersection is empty. Duplicating the campaign from a Marketer account and sending it reaches all 146 users.
# Why Does My Segment Query Fail With a Query Length Error?
Source: https://moengage.com/docs/user-guide/segment/faqs-segment/why-does-my-segment-query-fail-with-a-query-length-error
Troubleshoot a MoEngage segment query or campaign that fails because the segment definition exceeds the maximum query length, and learn how to reduce the size of the query.
## Problem
A segment query fails instead of returning a user count, and the campaigns that use the segment fail along with it. Depending on where the query fails, you see one of the following:
* A failure reason that names a length constraint, such as `'queryString' failed to satisfy constraint: Member must have length less than or equal to 262144`.
* A generic failure reason stating that an unexpected error occurred while executing the query, with no cause named.
* The segment stays in a running state and never returns a count.
The segment may fail even though it is within every documented segmentation limit — for example, a segment that combines 10 custom segments with OR, which is the maximum number of custom segments allowed in one definition.
## Instructions
A segment definition is serialized into a single query before it runs, and that serialized query has a maximum length of 256 KB (262,144 characters). MoEngage evaluates the query as a whole, so the limit applies to the fully expanded definition — including the definitions of every custom segment referenced inside it, not just the conditions you see on screen.
This is a separate limit from the [nesting limit](/docs/user-guide/segment/advanced-concepts/segment-nesting). A segment can be well within 6 levels of nesting and still exceed the query length, and a segment can exceed the nesting limit while being far shorter than 256 KB. Staying inside one limit does not keep you inside the other.
Query length grows fastest in these patterns:
* **Many custom segments combined with OR.** Each referenced custom segment expands into its own full definition inside the parent query.
* **Custom segments used in the exclusion block.** Excluded custom segments expand the same way as included ones, so an exclusion list of several custom segments adds as much length as an inclusion list of the same size.
* **Filters with a large number of selected values.** A single filter that matches hundreds of values — mobile numbers, product IDs, city names — can contribute more length than several ordinary conditions combined.
To bring the query under the limit, apply the options below in order of how much length they remove:
1. **Replace a list of OR'd custom segments with one segment.** Where several custom segments differ only by the value of one attribute, rebuild them as a single segment with one filter matching all of those values. Ten segments that each match one language become one segment whose language filter lists ten values.
2. **Move long value lists into a file segment.** Upload the identifiers as a [file segment](/docs/user-guide/segment/create-segments/file-segments) and reference that instead of listing the values in a filter. File segments are also not counted toward the nesting or custom segment limits.
3. **Flatten redundant references.** Where a custom segment is referenced only to add one or two conditions, inline those conditions into the parent query and drop the reference.
4. **Split the segment and the campaign.** Where the definition covers audiences that do not need to be evaluated together, create two or more segments and run a campaign for each.
> [!WARNING]
>
> Simplifying nesting can make the query length problem worse. The logical rules on the [Segment Nesting](/docs/user-guide/segment/advanced-concepts/segment-nesting) page reduce nesting depth by distributing conditions — for example, `(X AND Y) OR Z` becomes `(X OR Z) AND (Y OR Z)` — which repeats terms and produces a longer query. When you flatten nesting on a segment that is already large, check that the query still runs.
After you edit the segment, run the query from the **Create Segment** page and confirm it returns a count before you rely on it in a campaign. Campaigns that reference a failing segment fail at send time, so a segment that has started failing can affect several live campaigns at once.
## Example
A segment is defined as ten custom segments combined with OR — one per preferred language, each already filtered to the same audience. The definition is within the limit of 10 custom segments per definition and is only 2 levels deep, but each of the ten references expands into its own full definition, so the serialized query exceeds 256 KB and fails with the `length less than or equal to 262144` error. Every recurring campaign that targets the segment fails with it.
Rebuilding the definition as a single segment — the shared audience filter AND preferred language is any of the ten values — replaces ten expanded definitions with one filter holding ten values. The query returns a count, and the campaigns resume.
# Why Is There a Mismatch in the Events and Users Count Between Data Warehouses and the MoEngage Dashboard?
Source: https://moengage.com/docs/user-guide/segment/faqs-segment/why-is-there-a-mismatch-in-the-events-and-users-count-between-data-warehouses-and-the-moengage-dashboard
Understand why event and user counts may differ between your data warehouse exports and the MoEngage dashboard due to event time vs server time.
## Problem
The count of users who performed an event, like *App/Site Opened* on a particular day, differs between data warehouses and the MoEngage dashboard.
## Explanation
There may be slight discrepancies due to the following reasons:
* The data warehouse export uses *event_time* (when the event occurred), while MoEngage Analytics and Segmentation use server time (when the event was received at MoEngage servers).
* When an event is exported, its associated user profile (user ID and attributes) is also exported. If a profile merge, deletion, or update occurs shortly after the event is picked for export, these changes will not be reflected in the exported event. However, new events will contain the updated profile attributes.
* The report on the MoEngage Dashboard is in the App's Timezone, while MoEngage Automated Data Exports happen in the UTC Timezone. This difference should be accounted for when you generate reports on your end.
> [!NOTE]
>
> MoEngage Analytics works on unique users, whereas Exports contain raw data for all exported events. For more information, read [Analyze the Volume of Data Exports](/docs/user-guide/data/exports/events/analyze-the-volume-of-data-exports).
If the difference is more than 10%, you must investigate it for data loss or other errors.
> [!NOTE]
>
> MoEngage supports multiple data warehouses as destinations to forward events directly to your tables. The data warehouses supported are:
>
> * Amazon Redshift
> * Google BigQuery (via GCS)
> * Snowflake
>
> MoEngage also supports multiple cloud storage as destinations to forward events as JSON files in your buckets. The cloud storage supported are:
>
> * Amazon S3
> * Google Cloud Storages
> * SFTP
# Basics of Segmentation
Source: https://moengage.com/docs/user-guide/segment/getting-started/basics-of-segmentation
Learn how MoEngage segmentation works, what data drives it, and how to group users by attributes, events, and behavior for targeted campaigns.

**Data and Segmentation Path**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3128889-data-and-segmentation-path)
Segmentation is the process of grouping users who share common properties or behavior patterns. A segment can be based on user properties, events, event properties, or a combination of all three.
With MoEngage Segmentation, you can build audiences such as users in a specific city, users who made a purchase in the last 30 days, or users whose last session was more than 7 days ago. These segments can be used to send personalized campaigns or to analyze behavioral trends.
> [!NOTE]
>
> A workspace can have up to 1,000 active segments (file, filter, and custom combined). To raise this limit, contact Support.
## What Data Does MoEngage Use?
Segments are built from two primary types of data that MoEngage stores about your users:
* **User Properties** — properties that describe who a user is
* **Events and Event Properties** — records of what a user has done
> [!TIP]
>
> **Prerequisites**
>
> Before you start with segmentation, ensure that user properties and/or events and event properties are present in MoEngage. To set up your data flow, refer to the MoEngage [Developer](/docs/developer-guide/introduction) and [API](/docs/api/introduction) documentation.
Understanding these data types helps you decide which segment type and filters to use. For a complete overview of how MoEngage stores and organizes data, refer to [Overview of Data in MoEngage](/docs/user-guide/data/key-concepts/overview-data).
### User Properties
User properties are properties of a user in MoEngage, such as email, name, city, subscription status, or any custom property your app tracks. Attribute values are updated in near-real time and always reflect the latest known value — MoEngage does not store historical values for user properties.
Examples of segments based on user properties:
* Users whose last known country is India
* Users who have unsubscribed from email
* Users where Push iOS Reachability is true
Some user properties are generated automatically by MoEngage; others are sent by your app or data pipeline. For more information, refer to [User Profile](/docs/user-guide/data/user-data/user-profile) and [Derived Events and Attributes](/docs/user-guide/data/event-data/derived-events-and-attributes).
### Events and Event Properties
Events are actions that users perform, such as App Open, Add to Cart, or Product Purchase. Each event can have event properties — properties specific to that action — such as product category, price, or platform.
Unlike user properties, events are stored historically and can be queried over a time range.
Examples of segments based on events:
* Users who placed an order at least 3 times in the last 90 days with category "sportswear"
* Users who viewed a page at least 5 times in the last 30 days, with category "laptop"
* Users who added to cart at least once in the last 30 days, with category "mobiles"
For a complete guide to event tracking, refer to [A Complete Guide to Event Tracking](/docs/user-guide/data/event-data/a-complete-guide-to-event-tracking).
## How Segments Use Your Data
### Filters
Filters are conditions applied to user properties or event properties to identify matching users. For example, you can filter users from London, or users who purchased shirts in the last 30 days.
For a full reference of available filter types and operators, refer to [Filters in Segmentation](/docs/user-guide/segment/advanced-concepts/filters-in-segmentation). You can also build and validate these filters through an AI assistant using the [MoEngage MCP segmentation tools](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server#segments).
### Joins
Multiple segment conditions are joined using AND, OR, or Exclude logic:
* **OR** — users who match either condition
* **AND** — users who match both conditions
* **Exclude** — users from one condition minus the overlap with another
## Getting Data into MoEngage
Before you can create segments, MoEngage needs data about your users. The most common ways to send data are:
* **SDK integration** — mobile or web SDK sends user properties and events in real time. Refer to the [Developer Guide](/docs/developer-guide/introduction) to get started.
* **API integration** — send data programmatically using the MoEngage [Data API](/docs/api/introduction).
> [!NOTE]
>
> You do not need an SDK or API integration to start creating segments. If your user data is in a file or a data warehouse, you can use [File Segments](/docs/user-guide/segment/create-segments/file-segments) (upload a CSV list) or [Warehouse Segments](/docs/user-guide/segment/create-segments/warehouse-segments) (connect directly to BigQuery, Snowflake, Databricks, or Redshift) to build an audience immediately.
# Types of Segments
Source: https://moengage.com/docs/user-guide/segment/getting-started/types-of-segments
Explore all segment types in MoEngage: file, rule-based, affinity, custom, RFM, and warehouse segments — with links to detailed setup guides.
MoEngage provides several segment types to cover different use cases and data sources. Each type is suited to a particular kind of audience-building scenario.
Use this table to find the segment type that matches your goal, then follow the links for detailed setup steps.
| Segment type | What it is | When to use it |
| - | - | - |
| [File](/docs/user-guide/segment/create-segments/file-segments) | A static list of users uploaded as a CSV file. | You have a fixed, known list of users — for example, a migration list or an export from an offline database. |
| [Rule-based (filter)](/docs/user-guide/segment/create-segments/rule-based-filter-segments) | A dynamic group defined by conditions on user properties, events, and event properties. | You want membership to update automatically as user data and behavior change. |
| [Affinity](/docs/user-guide/segment/create-segments/affinity-segments) | A group based on behavioral patterns and preferences, such as how often or how consistently users take an action. | You want to target users by the strength of a behavior — for example, users who book rides at a certain hour at least 40% of the time. |
| [Custom](/docs/user-guide/segment/create-segments/manage-segments) | A saved, named segment query you can reuse across campaigns, flows, and analytics. | You reuse the same audience logic in multiple places, or you combine file, rule-based, and other custom segments. |
| [RFM](/docs/user-guide/segment/create-segments/rfm-segments) | Automatic buckets — such as Loyal, Promising, and At Risk — based on the recency, frequency, and monetary value of transactions. | You want to group users by transaction behavior without building rules manually. |
| [Warehouse](/docs/user-guide/segment/create-segments/warehouse-segments) | An audience built directly from your data warehouse without copying data into MoEngage. Define it with SQL, or with dropdown filters if your warehouse tables are mapped in MoEngage. | Your segmentation depends on scores or data that live only in your warehouse, or you have not integrated the MoEngage SDK yet. |
## File Segment
A file segment is a static list of users uploaded as a CSV file. Use this when you have a fixed list of users that you want to target — for example, users migrated from another platform or a list from an offline database.
[Learn how to create File Segments.](/docs/user-guide/segment/create-segments/file-segments)
## Rule-Based (Filter) Segment
A rule-based segment is defined by conditions applied to user properties, events, and event properties. MoEngage evaluates these rules against your data to produce a dynamic group of users. The segment membership updates as user data changes.
[Learn how to create Rule-Based Segments.](/docs/user-guide/segment/create-segments/rule-based-filter-segments)
## Affinity Segment
An affinity segment targets users based on behavioral patterns and preferences within your app — for example, users who predominantly listen to a specific music genre, or users who book rides between certain hours at least 40% of the time.
[Learn how to create Affinity Segments.](/docs/user-guide/segment/create-segments/affinity-segments)
## Custom Segment
A custom segment is a saved and named segment query that can be reused across multiple campaigns, flows, and analytics pages. Custom segments can combine file segments, rule-based segments, and other custom segments.
[Learn how to create and manage Segments.](/docs/user-guide/segment/create-segments/manage-segments) You can also create and count custom segments through an AI assistant using the [MoEngage MCP segmentation tools](/docs/user-guide/ai-and-intelligence/merlin-ai/moengage-mcp-server#segments).
## RFM Segment
RFM (Recency, Frequency, Monetary) segments automatically group users by their transaction behavior — how recently they engaged, how often, and how much they spent. MoEngage generates RFM segments automatically once you configure the model, placing users into buckets such as Loyal, Promising, At Risk, and others.
[Learn how to use RFM Segments.](/docs/user-guide/segment/create-segments/rfm-segments)
## Warehouse Segment
A warehouse segment lets you build an audience directly from your data warehouse — BigQuery, Snowflake, Databricks, or Redshift — without copying data into MoEngage. Use this when your segmentation logic depends on proprietary scores or data that lives exclusively in your warehouse.
There are two ways to define one:
* **SQL editor** — write a query that returns a single column of user IDs. Works on any connected warehouse. [Learn how to create a segment using SQL.](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-sql)
* **Filter builder** — pick attributes and events from dropdowns, as you would for a rule-based segment. Requires your warehouse tables to be [mapped in MoEngage](/docs/user-guide/data/warehouse-schemas) first, and supports BigQuery and Databricks. [Learn how to create a segment using filters.](/docs/user-guide/segment/create-segments/warehouse-segments/create-using-filters)
> [!NOTE]
>
> Warehouse Segments do not require an SDK or API integration with MoEngage. If you have not yet integrated the MoEngage SDK, Warehouse Segments are a way to start creating audiences immediately.
## Segment Processing
Segmentation computation timing varies by campaign type.
**One-time and periodic campaigns**: Segment membership is computed at the scheduled execution time, in seconds.
**Event-triggered campaigns**: Segment membership can be defined in three layers:
### Trigger Criteria
This layer qualifies users in real time based on their actions or inaction. You can include use cases like cart abandonment directly in the trigger criteria.
### User Properties
User property evaluation for segment membership in event-triggered campaigns happens in real time.
### Past Behavior Segmentation
#### Real-Time Segment Evaluation
Segments using data within the last 30 days — user properties, user events, event properties, and event duration — are evaluated in real time. This is available for Push, Email, SMS, WhatsApp (all event-triggered), In-Apps, On-Site Messaging, Personalize, and Flows.
#### Precomputed Segments
For historical event data beyond 30 days, MoEngage uses precomputed segments. Segment membership is calculated ahead of time (from 30 minutes to a few hours, depending on configuration), giving users a real-time experience at the moment of the event trigger.
# Email Reachability
Source: https://moengage.com/docs/user-guide/segment/reachability/email-reachability
Learn how MoEngage calculates email reachability for your segments, what causes users to be unreachable, and steps to improve email deliverability.
Email reachability provides the number of reachable users via Email channel in a segment. Email reachability number is required to decide whether to choose Email channel for sending a campaign if your goal is to reach users via the best-performing channel.
This article explains how the reachability of Email channel is derived. This article also lists the parameters considered to calculate reachability for users reachable via Email. There is a list of reasons why the users could not be reachable via Email channel and potential solutions to convert the non-reachable users to reachable users.
## **User reachability - Email Campaign**
Email campaign will allow to reach users via emails and the reachable users count will be the number of users that are eligible to receive emails on their registered email ID.

## **How is user reachability calculated for Email campaigns?**
The given parameters derive email reachability -
1. User email should exist
2. User property **Hard Bounce** should be false
3. User property **Spam** should be false
4. User property **Unsubscribe** should be false
5. User email contains '@'
> [!NOTE]
>
> Email campaign considers all of the above-mentioned parameters for email reachability.\
> Segmentation and User profile consider the first four parameters to calculate email reachability.
For all users by default Hard Bounce, Spam, and Unsubscribe are false. If a user unsubscribes from an email or marks any email as spam, then Unsubscribe and Spam are updated as true, respectively. If the user's email is bounced, then Hard Bounce is updated as true. You can see this in the user info page of the user profile (as shown below).

## **How to analyze and find reasons for users' non-reachability?**
Step 1: Go to Analyse and select "Users" to do the user analysis
Step 2: Select the 3 user properties in the User Properties section (Unsubscribe, SPAM, and Hard Bounce)
Step 3: Below in the User Analysis Options select Analysis type as "Distribution" and click Apply button
Step 4: Analyse the generated graph and look at the reasons for non-reachability for the Email channel along with the distribution count

## **Potential solutions to solve users' non-reachability problems**
Non-reachability reasons
What could be a potential solution to solve this?
**Unsubscribe**Denotes if the user has unsubscribed to the emailThese users are considered non-reachable via email channel
1\. Target these users who are not reachable, via other channels like In-app, SMS, WhatsApp, Push, etc. Use campaign content wisely so that the outcome of the campaign is these users subscribing again. Provide a CTA to the landing page for subscribing again.2. Diversify your content strategy so that the customers don't feel your only intention is to make them subscribe or unmark as SPAM. Experiment with educational content, FOMO content, nostalgic content, etc.
**SPAM/Complaint**Denotes if the user has reported email as SPAMThese users are considered non-reachable via email channel
**Hard Bounce**Denotes if the email to the user has hard bounced because of email being wrong or a technical issue with email senderThese users are considered non-reachable via email channel
You can create a segment of these users and run a campaign using similar channels as above. Here, using the CTA you can redirect them to their user profile on your app or a landing page and ask them to input their email ID correctly.
**Note**: Above solutions are some of the potential solutions, which may or may not result in the expected result/success.
## **Example:**
If you want to make all the email unsubscribed users subscribe back to receive emails, you can do it in this way:
Step 1: Select the reason on the pie chart, for example: unsubscribe in the below example
Step 2: Create a segment or take action by choosing a Specific channel and Delivery type to target the email unsubscribed users
Step 3: Configure the content in the campaigns page

Similarly, you can target users for other reasons who are not reachable through the Email channel.
# Push Reachability
Source: https://moengage.com/docs/user-guide/segment/reachability/push-reachability
Understand how push notification reachability is calculated across Android, iOS, and Web in MoEngage, with tips to increase reachable user counts.
Push reachability provides the number of reachable users via the Push channel in a segment. Push reachability number is required to decide whether to choose the Push channel for sending a campaign if your goal is to reach users via the best-performing channels.
This article explains how the reachability of the Push channel is derived. For the Push channel, it also explains the reachability of respective platforms (Web, Android, iOS). This article also lists the parameters considered to calculate reachability for users reachable via Push. There is a list of reasons why the users could not be reachable via the Push channel and potential solutions to convert the non-reachable users to reachable users.
## **User and Platform reachability - Push Campaign**
By using the Push channel in a campaign users can be reached on 3 types of devices i.e. Web, Android, and iOS. The push campaign will allow to reach users via push notifications and the reachable user count will be the number of users that are eligible to receive Push notifications.

## **How is user reachability calculated for Push campaigns?**
Push reachability is derived by the given parameters -
1. Users should have at least one active device.
* In the case of iOS, the app should be installed on the device, and the device should be opt-in for push notifications.
* In the case of Android, the app should be installed on the device, and the device should not be opt-out for push notifications.
* In the case of the Web, the user should have visited the website once and must Opt-in to the browser permission
2. Push token for this device should exist.
3. For reachability on the different iOS & Android, at least one active device for the respective platform should exist, and the device should have the app installed.
Based on the above parameters system generates reliability codes for all platforms. The reachability codes are stored in User Properties '*Reachability Push Android*', '*Reachability Push iOS*', and '*Reachability Push Web*'. The user is considered to be reachable on the respective platform if the attribute value (reachability code) in these attributes is 200 and 201.
MoEngage also updates users' reachability based on feedback from silent Push (run periodically if the setting is ON) or Push notifications.
### **Reachable users across different channels:**

### **Push reachable users across different platforms:**

## **How to analyze and find reasons for users' non-reachability?**
Step 1: Go to Analyse and select "Users" to do the user analysis
Step 2: Select the user property in the User Properties section (either from Push reachability Android, Push reachability iOS or Push reachability web)
Step 3: Below in the User Analysis Options select Analysis type as "Distribution" and click Apply button
Step 4: Analyse the generated graph and look at the reasons for non-reachability for Push channel along with the distribution count

Similarly, you can do this for all the 3 platforms (Android, iOS, Web) together or for other platforms individually.
## **Potential solutions to solve users' non-reachability problems**
Reachability Push Code (All devices)
Reachability Description
What could be a potential solution to solve this?
202
**Not reachable due to Opt-out.**This is the reachability value for any user who has opted out of receiving push notifications on all of their Android devices.These users are no longer considered reachable and will not be targeted for campaigns.*To exclude opted-out users and thereby have more accurate delivery reporting, please reach out to your Customer Success Account Manager.*
Targeting **inbound campaigns** (In-Apps, Card, On-site) to lure the user to opt-in by redirecting to the permissions setting page. As user needs to modify the permission to be reachable.
300
**No device found**User will not be reachable if the device is not found for the user. The reason for the device not being found is when just the user creation has happened but any device is not present for that user. Such type of user can be created in the following ways:
If the user is created using user import using a file
If the user is created using S2S API call (Server call)
Using outbound email, SMS or WhatsApp campaign target these users to install the app and sign up through any device using the same credentials.
403
**Not reachable due to App uninstalled**Any user who is not reachable due to app being uninstalled
An outbound email, SMS or WhatsApp campaign can be targeted to these users using suitable content (Offer, FOMO, etc) to make them install the app again.
404
**Not reachable due to Push ID not found for the app**Any user who is not reachable due to Push ID not found
Check this with your app development team if they have not opted for the MoEngage solution to generate a Push token. The problem could be with the calls made to FCM/APNS for token generation or authentication.
409
**Not reachable due to invalid push ID**Any user who is not reachable due to an invalid push ID
**Note**: Above solutions are some of the potential solutions, which may or may not result in the expected result/success.
## **Example:**
If you want to make all the push unsubscribed users to subscribe for your push notifications, you can do it in this way:
Step 1: Select the section in the pie chart that denotes Push unsubscribed users
Step 2: Create a segment or take action by choosing a Specific channel and Delivery type to target the Push unsubscribed users
Step 3: Configure the content on the campaigns page

Similarly, you can target users with other reasons who are not reachable through the Push channel.
# SMS Reachability
Source: https://moengage.com/docs/user-guide/segment/reachability/sms-reachability
Find out how MoEngage calculates SMS channel reachability in your segments, why some users are unreachable, and what steps can improve your SMS reach.
SMS reachability provides the number of reachable users via the SMS channel in a segment. SMS reachability number is required to decide whether to choose SMS channel for sending a campaign if your goal is to reach users via the best-performing channels.
This article explains how the reachability of the SMS channel is derived. This article also lists the parameters considered to calculate reachability for users reachable via SMS. There is a list of reasons why the users could not be reachable via SMS channel and potential solutions to convert the non-reachable users to reachable users.
## **User reachability - SMS Campaign**
SMS campaign will allow to reach users via SMS and the reachable users count will be the number of users that are eligible to receive SMS on their registered phone number.

## **How is user reachability calculated for SMS campaigns?**
SMS reachability calculation is derived based on two conditions, as explained below:
**1. Presence of Mobile number string value in the attribute - Mobile number (Standard)**
Mobile Number (String) should exist for the user to be reachable. There is no mobile number format validation used for reachability calculation in Segmentation/Recent queries.
> [!NOTE]
>
> Mobile Number attribute should be stored as a string data type for proper functioning
But before sending the actual SMS campaign, the system validates the mobile number, the country code, and the format.
Here is how you can look at the Mobile number presence in the user profile:

**2. Subscription management (SMS subscription status attribute)**
If subscription management is enabled in your account, there will be an additional check for an attribute (SMS subscription status) that will determine the reachability of users on the SMS channel. If the SMS subscription status is True then the user will be marked reachable otherwise the user will be marked non-reachable.

In case subscription management is not enabled for your account, only mobile number presence will be checked for deriving reachability. In case subscription management is enabled for your account, if any of the above two conditions are not satisfied, then the user cannot receive the SMS campaign (not reachable).
> [!NOTE]
>
> There could be a difference in the reachable user count on the "Create segment" page and "SMS campaign" page because segmentation only checks if user data and user permission to receive the campaign is present, it does not do mobile number validation and considers control group while calculating reachable users.
## **How to analyze and find reasons for users' non-reachability?**
Step 1: Go to Analyse and select "Users" to do the user analysis
Step 2: Select the user property present in the User Properties section (Mobile number (Standard) or SMS Subscription Status)
Step 3: Below in the User Analysis Options select Analysis type as "Distribution" and click Apply button
Step 4: Analyse the generated graph and look at the reasons for non-reachability for SMS channel along with the user count

## **Potential solutions to solve users' non-reachability problems**
| **Non-reachability reasons** | **What could be a potential solution to solve this?** |
| - | - |
| **Incorrect user data/mobile number not present** Denotes if the user's mobile number in MoEngage is incorrect/mobile number not present *(Incorrect mobile number validation does not happen while calculating reachable users in segmentation, the check happens just before sending the SMS campaign)* | You can create a segment of these users and run a campaign using outbound or inbound channels like InApps, Push, Email, etc. Here, using the CTA you can redirect them to their user profile on your app or a landing page and ask them to correctly input their mobile number. You can also use OTP to verify if the provided number is correct. |
| **Subscription status (Only if subscription management is enabled for SMS channel)** Denotes if the user has opted out or un-subscribed for SMS These users are considered non-reachable via SMS channel | *(This will be applicable only if "**Subscription Management**" is enabled for your account)* Target these users who are not reachable on SMS, via other channels like In-app, Email, WhatsApp, Push, etc. Use campaign content wisely so that the outcome of the campaign is these users subscribing again. Provide a CTA redirecting the user to the SMS message inbox for users to type the keyword leading to user opting in (Eg: Start, Begin, etc). |
**Note**: Above solutions are some of the potential solutions, which may or may not result in the expected result/success.
## **Example:**
If you want to target the non-reachable users via SMS channel due to mobile number not present, you can do it in this way:
Step 1: Select the reason on the chart, for example: Mobile number - Empty
Step 2: Create a segment or take action by choosing a Specific channel and Delivery type to target the email unsubscribed users
Step 3: Configure the content on the campaigns page
## 
Similarly, you can target users with more conditions e.g. users who have the mobile number present in the user profile but opted out of SMS subscription.
# User Reachability
Source: https://moengage.com/docs/user-guide/segment/reachability/user-reachability
Get a complete overview of user reachability across Push, Email, SMS, and WhatsApp channels in MoEngage, including how each module calculates reach.
As the name suggests, Reachability represents the number of users who can be contacted or connected using the respective communication channels or platforms on MoEngage.
This article explains how the reachability of Push, Email, SMS, and WhatsApp channels are derived. For the Push channel, this also explains the reachability of respective platforms. This article also lists the method of calculation for the different pages present on the MoEngage dashboard.
# Reachability
Reachability in different modules across MoEngage:
## Segmentation
Queries executed on the segmentation page ([Create segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments)) show reachability for Push, Email, SMS, and WhatsApp channels and reachability across these 4 channels.

The segmentation page also shows the queries executed on the channel's page. You can identify them via the source column.
For reachability calculation on the segmentation page:
* Email ID is taken from **Settings** -> **Channels** -> **Email** -> **General settings**
* Mobile Number is taken from **Settings** -> **Channels** -> **SMS** -> **General settings**
### Reachable Users Across Channels
The **Reachable users** count at the top of the Reachability card is the number of users in the segment who are reachable on at least one of the four channels. This count is a union of the individual channel reachabilities, not a sum:
* A user who is reachable on more than one channel is counted once.
* The count is always equal to or higher than any individual channel count shown under **Reachability by channel**.
In the preceding screenshot, the segment has 22 reachable users, while the highest individual channel count is 19. The percentage below each channel is calculated against the **Reachable users** count, not the total user count. For example, 9 email-reachable users out of 22 reachable users is 40.91%.
## User Profile
The [User Profile](/docs/user-guide/data/user-data/user-profile) represents the reachability of a specific user for different channels and platforms.

The green icons on the push reachability card represent the reachability as true for a specific platform. If reachability is true for any of the above platforms, the overall push reachability is true and represented by a green tick mark on the push reachability card. If all platforms are not reachable, it's represented by the red exclamation mark.
Similarly, for Email, SMS, and WhatsApp, if the user is reachable, it is represented by a green icon and a green tick mark on the reachability card. Non-reachable users will have red icons and a red exclamation mark.
For reachability calculation on the User Profile page:
* Email ID is taken from **Settings** -> **Channels** -> **Email** -> **General settings**
* Mobile Number is taken from **Settings** -> **Channels** -> **SMS** -> **General settings**
## Campaign
Before sending a campaign, users need to be segmented. A segment can have all users or a desired group of users. All of these segmented users may not be reachable, as the required information or the required permissions are not available for the respective users.\
Here is the list of the outbound channels and the respective reachability -
### Push
Queries executed on the Push campaign page show push reachability for Android, iOS, and Web reachability across these 3 platforms.

For more information, see [Push Reachability](/docs/user-guide/segment/reachability/push-reachability).
### Email
Queries executed on the Email campaign page show email reachability.\
For reachability calculation, the email campaign uses the attribute specified on the campaign page under the **User property with email address** list.

For more information, see [Email Reachability](/docs/user-guide/segment/reachability/email-reachability).
### SMS
Queries executed on the SMS campaign page show SMS reachability.
For reachability calculation, the SMS campaign uses the attribute specified on the campaign page under the **User property that stores user’s mobile numbers** list.

For more information, see [SMS Reachability](/docs/user-guide/segment/reachability/sms-reachability).
### WhatsApp
Queries executed on the WhatsApp campaign page show WhatsApp reachability. ([Configure WhatsApp](/docs/user-guide/campaigns-and-channels/whatsapp/getting-started-with-whatsapp/configure-whatsapp))
For reachability calculation, the WhatsApp campaign uses the attribute specified at **Settings** -> **Channels** -> **WhatsApp** -> **General settings**. The user should have the WhatsApp mobile number and the user’s WhatsApp Opt-In status should be *True*.

For more information, see [WhatsApp Reachability](/docs/user-guide/segment/reachability/whatsapp-reachability).
## Differences Between Segmentation and Campaign Reachability
The reachable user count on the **Create segment** page can be higher than the count on a campaign page for the same segment. The following differences account for this:
| Difference | Segmentation | Campaign |
| - | - | - |
| Control group | Includes users who are part of a [control group](/docs/user-guide/campaigns-and-channels/getting-started/introduction/control-groups). | Excludes users who are part of a control group, because they are held out of the campaign. |
| Mobile number validation | Does not validate the mobile number format or country code. | Validates the mobile number, country code, and format before sending an SMS or WhatsApp campaign. |
| Email address validation | Checks that the email address exists and that the Hard Bounce, Spam, and Unsubscribe user properties are false. | Runs the same checks and also verifies that the email address contains an `@` symbol. |
| Source attribute | Uses the email and mobile number attributes configured under **Settings** > **Channels**. | Email and SMS campaigns use the attribute selected on the campaign page, which can be a different attribute. |
## Why Reachable User Counts Differ Across Pages
Several pages on the MoEngage dashboard show a reachable or sent count. Each page counts something different, so the numbers for the same audience do not always match. The following table lists what each page measures and why its count can differ from the others.
| Page | What the count measures | Why it can differ |
| - | - | - |
| **Create segment** (Reachability card) | Unique users in the segment who are reachable on each channel, and on at least one channel, when you run the query. | Reflects the time you ran the query. Uses the email and mobile number attributes configured under **Settings** > **Channels**. |
| **Custom segment** details page | Unique users and reachable users in the saved segment as of the last refreshed time shown on the page. | Stays at the last refreshed value until you run the segment again. For more information, see [Manage Segments](/docs/user-guide/segment/create-segments/manage-segments). |
| **Campaign** audience step | Unique users in the target audience who are reachable on the campaign's channel. | Excludes control group users, validates email addresses and mobile numbers, and uses the attribute selected on the campaign page. For more information, see [Differences Between Segmentation and Campaign Reachability](#differences-between-segmentation-and-campaign-reachability). |
| **Campaign stats** (Sent) | Notifications sent. For push, MoEngage sends to every active device token of a user. | Can be higher than the reachable user count because a user with several devices receives the push on each device. For more information, see [Why Is Push Campaign Sent Count Greater Than Reachable Users in Segment?](/docs/user-guide/campaigns-and-channels/web-push/faqs-web-push/why-is-push-campaign-sent-count-greater-than-reachable-users-in-segment). |
| **Reachability dashboard** | Daily push reachability trends for Android, iOS, and Web over a date range. | Covers the push channel only. **Push reachable users** counts reachability codes 200 and 201, while **Push eligible users** also counts opted-out users (202). For more information, see [Reachability Dashboard](/docs/user-guide/analyze/dashboards/reachability). |
| **User Profile** | Reachability of one user on each channel and platform. | Shows a single user, so use it to check why a specific user is or is not counted elsewhere. |
### Which Count to Use
| If you want to | Use |
| - | - |
| Estimate how many users in a segment you can reach on each channel | The Reachability card on the **Create segment** page. |
| Know how many users a specific campaign will target | The reachable user count on the campaign's audience step. |
| Know how many notifications a campaign sent | The **Sent** count in campaign stats. |
| Track push opt-in and opt-out trends over time | The [Reachability dashboard](/docs/user-guide/analyze/dashboards/reachability). |
| Check why a specific user did not receive a message | The reachability card on the user's [User Profile](/docs/user-guide/data/user-data/user-profile). |
For count differences between Analytics, Segmentation, campaign stats, and Flows that are not about reachability, see [Different Count in Analytics, Segmentation, Campaigns Stats and Flows](/docs/user-guide/analyze/analytics-how-to/different-count-in-analytics-segmentation-campaigns-stats-and-flows).
## Open Analytics
Reachability can be calculated directly using the data present in the MoEngage warehouse. Using Open Analytics, you can derive reachability and get the required data around it. To learn about [reachability using open analytics, click here](/docs/user-guide/analyze/analytics-how-to/reachability-queries-for-open-analytics).
# Reachability Calculation
## Push
Push reachability is derived by the given parameters -
1. Users should have at least one active device.
* In the case of iOS, the app should be installed on the device.
* In the case of Android, the app should be installed on the device, and the device should not be opt-out for push notifications.
* In the case of the Web, the user should have visited the website once and must Opt-in to the browser permission
2. Push token for this device should exist.
3. For reachability on the different iOS & Android, at least one active device for the respective platform should exist, and the device should have the app installed.
4. MoEngage also updates users' reachability based on feedback from silent Push (run periodically if the setting is ON) or Push notifications.
Based on the above parameters system generates reliability codes for all platforms. The reachability codes are stored in User Properties '*Reachability Push Android*', '*Reachability Push iOS*', and '*Reachability Push Web*'. The user is considered to be reachable on the respective platform if the attribute value (reachability code) in these attributes is 200.
### User Opt-in preferences and Push Reachability
Users are explicitly asked for permission to be sent push notifications during the app's installation on iOS, Android (13 and above), and Web. They can opt in and opt out of receiving push notifications by navigating to the device's app settings and selecting their preference.
The table below showcases the reachability and Opt-in states that are tracked using the following user properties, as seen in the segmentation section of the MoEngage Dashboard:
* Reachability Push Android
* Reachability Push iOS
* Reachability Push Web
Reachability Push Code (All devices)
Legacy Reachability Description
New Reachability Description (Recommended)
202
**Reachable but Opted-out.**This is the reachability value for any user who has opted out of receiving push notifications on all of their mobile devices.These users are considered reachable but will not receive notifications on their devices.
**Not reachable due to Opt-out.**This is the reachability value for any user who has opted out of receiving push notifications on all of their devices.These users are no longer considered reachable and will not be targeted for campaigns.*To exclude opted-out users and thereby have more accurate delivery reporting, please reach out to your Customer Success Account Manager.*
201
**Reachable and opted in**This is the reachability value for any user who has opted in to receive push notifications on at least one of their devices.These users are considered reachable.
200
**Reachable and opt-in status unknown**This is the reachability value for users whose opt-in or opt-out preferences are not being tracked by MoEngage yet because these users are on the older SDK version. These users are considered reachable and are attempted for sending push notifications, but some of these users may be opted-out and will not be able to see notifications.**Note:** Opt-in or opt-out tracking is supported on MoEngage Core SDK version 12.3.01 and above.
300
**No device found**User will not be reachable if the device is not found for the user. The reason for device not found is when just the user creation has happened but any device is not present for that user. Such type of user can be created in following ways:
If the user is created using user import using a file
If the user is created using S2S API call
403
**Not reachable due to App uninstalled**Any user who is not reachable due to app being uninstalled
404
**Not reachable due to Push ID not found for the app**Any user who is not reachable due to Push ID not found
409
**Not reachable due to invalid push ID**Any user who is not reachable due to invalid push ID
> [!NOTE]
>
> To enable Android push notification opt-in or opt-out tracking, upgrade to MoEngage Core SDK version 12.3.01 and above.
## Email
The given parameters derive email reachability -
1. User email should exist
2. User property **Hard Bounce** should be false
3. User property **Spam** should be false
4. User property **Unsubscribe** should be false
5. User email contains '@'
> [!NOTE]
>
> Email campaign considers all of the above-mentioned parameters for email reachability.\
> Segmentation and User profile consider the first four parameters to calculate email reachability.
For all users by default Hard Bounce, Spam, and Unsubscribe are false. If a user unsubscribes from an email or marks any email as spam, then unsubscribe and Unsubscribe and Spam are updated as true, respectively. If the user's email is bounced, then Hard Bounce is updated as true.
## SMS
The given parameters derive SMS reachability -
Mobile Number should exist for the user to be reachable. There is no mobile number format validation used for reachability calculation.
> [!WARNING]
>
> The Mobile Number attribute must be stored as a **string** data type. If it is tracked as another type (for example, `double`), the affected users are not counted as SMS-reachable, and the segment can show 0 SMS-reachable users. To fix this, pin the Mobile Number data type to String on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard and re-send the corrected data. Track Mobile Number in [E.164 format](/docs/user-guide/settings/advanced-settings/e164-phone-number-format).
The system also validates the mobile number, the country code, and the format before sending the actual SMS campaign.
## WhatsApp
The given parameters derive WhatsApp reachability -
1. A mobile number should exist in MoEngage for the user to be reachable.
2. The mobile number should have a valid account on WhatsApp.
3. WhatsApp Opt-In status should be True
> [!NOTE]
>
> Mobile Number attribute should be stored as a string data type for proper functioning
The system also validates the mobile number, the country code, and the format before sending the actual WhatsApp campaign.
# WhatsApp Reachability
Source: https://moengage.com/docs/user-guide/segment/reachability/whatsapp-reachability
Learn how MoEngage determines WhatsApp reachability, review the parameters that affect it, and find solutions to convert unreachable users to reachable.
WhatsApp reachability provides the number of reachable users via the WhatsApp channel in a segment. WhatsApp reachability number is required to decide whether to choose WhatsApp channel for sending a campaign if your goal is to reach users via the best performing channels.
This article explains how the reachability of the WhatsApp channel is derived. This article also lists the parameters considered to calculate reachability for users reachable via WhatsApp. There is a list of reasons why the users could not be reachable via WhatsApp channel and potential solutions to convert the non-reachable users to reachable users.
## **User reachability - WhatsApp Campaign**
WhatsApp campaign allows marketers to reach users via WhatsApp and the reachable users count shows the number of users that are eligible to receive WhatsApp on their registered phone number.

## **How is user reachability calculated for WhatsApp campaigns?**
WhatsApp reachability calculation is derived based on below conditions:
Mobile Number (String) should exist for the user to be reachable. There is no mobile number format validation used for reachability calculation in Segmentation/Recent queries. In addition to Mobile number presence, the WhatsApp subscription status should be True. Both of these conditions will be used to derive user reachability for WhatsApp channel.
> [!NOTE]
>
> Mobile Number attribute should be stored as a string data type for proper functioning
But before sending the WhatsApp campaign, the system validates the mobile number, the country code, and the format.
Here is how you can look at the Mobile number presence in the user profile:

If WhatsApp subscription status is True, then the user will be considered reachable otherwise the user will be considered non-reachable. You can find the WhatsApp subscription status in the user profile as show below:

> [!NOTE]
>
> There could be a difference in the reachable user count on the "Create segment" page and "WhatsApp campaign" page because segmentation only checks if user data and user permission to receive campaign is present, it does not do mobile number validation and consider control group while calculating reachable users.
## **How to analyse and find reasons for users' non-reachability?**
Step 1: Go to Analyse and select "Users" to do the user analysis
Step 2: Select the user property present in the User Properties section (Mobile number (Standard) or WhatsApp Subscription Status)
Step 3: Below in the User Analysis Options select Analysis type as "Distribution" and click Apply button
Step 4: Analyse the generated graph and look at the reasons for non-reachability for WhatsApp channel along with the user count

## **Potential solutions to solve users' non-reachability problems**
| **Non-reachability reasons** | **What could be a potential solution to solve this?** |
| - | - |
| **Incorrect user data/mobile number not present** Denotes if the user's mobile number in MoEngage is incorrect/mobile number not present *(Incorrect mobile number validation does not happen while calculating reachable users in segmentation, the check happens just before sending the WhatsApp campaign)* | You can create a segment of these users and run a campaign using outbound or inbound channels like InApps, Push, Email, etc. Here, using the CTA you can redirect them to their user profile on your app or a landing page and ask them to correctly input their mobile number. |
| **Subscription status** Denotes the WhatsApp subscription status of users. *(This will be applicable if user has opted out from receiving WhatsApp messages by typing keywords like stop, opt-out, etc)* | Users not reachable because of opt-out WhatsApp subscription cannot opt-in back by typing "Start, Resume" similar to SMS channel. Targeting the users via any outbound or inbound channel will not lead to users opt-in to WhatsApp communication. Client needs to use the appropriate WhatsApp subscription API/use file upload to change the WhatsApp subscription status manually for the specific users. |
**Note**: Above solutions are some of the potential solutions, which may or may not result in the expected result/success.
## **Example:**
If you want to target the non-reachable users via WhatsApp channel due to mobile number not present, you can do it in this way:
Step 1: Select the reason on the chart, for example: Mobile number - Empty
Step 2: Create a segment or take action by choosing a Specific channel and Delivery type to target the email unsubscribed users
Step 3: Configure the content in the campaigns page
## 
Similarly, you can target users with more conditions e.g. users who have the mobile number present in the user profile but opted out of WhatsApp subscription.
# Different count in Analytics & Segmentation
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/different-count-in-analytics-and-segmentation
Understand why user counts differ between MoEngage Analytics and Segmentation pages. Learn how unique users are calculated in behavior vs. segment views.
In MoEngage, user count can be analyzed on two different pages - The analytics page and the Segmentation page.
The Segmentation page provides user count and sample users for a segment and Analytics Pages (Behavior, Funnel, etc) provide, event count, event frequency, revenue, retention & funnel information along with the unique user count.
## Behavior & Segmentation Users
To analyze users on Behavior Page, select Plot For as Total Users. This option shows unique users for the selected granularity in the line/area chart or overall unique users in the bar chart.

Whereas the Segmentation page shows the overall unique user count.

## User Merging
A few times these two user counts from the segmentation page and behavior page do not match. This may happen due to user merging. In MoEngage engagement Module, the user who is coming from different devices is merged when the user logs in. [User Merging is explained in detail here.](/docs/user-guide/data/user-data/user-profile)
The user merging is available in MoEngage Analytics Module as well. However, it is not enabled by default. Hence there are some leftover anonymous users present in the system.
A normal person may have 2 kinds of events in analytics when the user was anonymous and when the user was logged in and hence identified as two different users.
To overcome this scenario, you can enable user merging. This will help you to merge the anonymous user IDs with registered user IDs and show those uses as One.
To enable user merging follow the path:
*Settings -> General Settings -> Analytics Settings -> Enable User Merging*

## Funnel and Segmentation Users
There can be a difference in funnel user count and segmentation user count. This is primarily due to how funnel and segmentation work.
The funnel considers the order of the event. For a user funnel of events E1 and E2, the final number is users who have done event E1 and after that E2. Users who have performed E2 before E1 are not considered.
Segmentation does not consider the order of the event. For a user segment of events E1 and E2, the final number is users who have done both events, E1 and E2. It doesn't matter which is the first and which is the second event.
## First-Time Event Filters
When you filter users with the **for the first time** operator, Behavior and Segmentation can return different user counts for the same event and date range. This is expected behavior because each page checks a different event history:
* **Segmentation** checks whether the user's first-ever occurrence of the event falls inside the selected date range. Users who performed the event before the start of the range are excluded. The check covers only the events data retention period of your workspace. For more information, refer to [Filters in Segmentation](/docs/user-guide/segment/advanced-concepts/filters-in-segmentation).
* **Behavior** looks for each user's first occurrence of the event within the selected date range. Occurrences before the start of the range are not checked.
As a result, Segmentation returns an equal or lower count than Behavior for the same **for the first time** condition. For example, a user who viewed a product in May and again on June 3 qualifies for "Viewed Product for the first time between June 1 and June 7" in Behavior, but not in Segmentation.
# Different count in Analytics, Segmentation, Campaigns stats & Flows
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/different-count-in-analytics-segmentation-campaigns-stats-and-flows
Learn why user counts differ between MoEngage Analytics, Segmentation, Campaign stats, and Flows, and how each module calculates them.
## The Difference in Campaign Counts
On the MoEngage dashboard, user behavior analysis can be analyzed on different pages - Analyze, Segmentation, and Campaign stats section.
## Segmentation Counts
The **Create Segments** page always provides "unique users" count.
For differences in reachable user counts between segments, campaigns, and the Reachability dashboard, see [Why Reachable User Counts Differ Across Pages](/docs/user-guide/segment/reachability/user-reachability#why-reachable-user-counts-differ-across-pages).
## Analyze Counts
Analyze section pages - Behavior, Funnel, Retention, etc. pages provide two different kinds of counts
* Total event count - This is the count of the action/event done by the user. The total event count is available for hourly, daily, weekly, and monthly granularity.
* Unique user count - Unique user count is the count of distinctive/individual users performing the events, a user can perform a specific event multiple times. Unique user count is available for hourly, daily, weekly, and monthly granularity.
The following Analysis types: Total Event and Unique users counts can be seen in Behavior & Funnels. While Retention always provides a unique user count.

## Campaign counts
Here we have taken an example of the Push campaign -

* **Impressions** represent the number of user **devices** that have received the notification sent by the marketer. It can also be seen as the total event count of impressions.
* **Clicks** represent the total number of notifications clicked by the users once the notification is delivered. It can also be seen as the total event count of Clicks.
* **Conversion** **Events** represent the total number of primary conversion goal events that happened within the attribution period from the time the user received the notification.
**Conversions**
* For campaigns having only one recurrence, conversion represents unique users who have accomplished the primary conversion goal event at least once within the attribution period.
* For campaigns having multiple recurrences, conversion represents unique users who have accomplished the primary conversion goal event at least once within the attribution period for each recurrence. For example, If a user receives one Campaign Instance on Day X and another on Day Y and converts once on both days, the conversions will be counted as 2.
### Difference in count
* Event count for Impression, Clicks, and Conversion Event should be the same in both Campaign stats and *Total Event* analysis of the Behavior page.\
As these metrics are event counts, they can not be compared with Unique Users.
* Conversions in campaign stats provide the unique user count per campaign recurrence, and Behavior analytics *Unique Users* provide the unique user count across the hour, day, week, or month.\
For example, a user who receives two campaigns and converts two times Monday & Wednesday (within the attribution window) - this user will have campaign conversion as 2 (one for each campaign). In contrast, in Behavior analytics, *Unique Users* for daily granularity provide 2 users and weekly granularity provides 1 user.
* Campaign stats are calculated in UTC and all the analyses provided in the analyze section run on the app time zone.
**Note:** In Funnel analysis, Funnel - Unique User analysis with *Holding attribute constant* on campaign id attribute across all steps, provide unique converted user for each campaign for the selected granularity. Read more about it [here](/docs/user-guide/analyze/analytics/funnels/advanced-funnel-analysis).
## Funnels and Flow Stats Counts
The disparities in the results of Funnel Unique Users Analysis and Flow Metrics stem from their different methodologies. While the Funnel displays unique user-level conversion counts, the Flow Metrics are calculated at the Unique Trips level.
* As an example, if a user enters the Flow on two separate occasions, such as on the 1st and 5th of a month, and completes a conversion once in each trip, the Entry count and Converted Trips will register as 2 in both cases. Conversely, the Funnel analysis of Unique Users will reflect a count of 1 for this user. This discrepancy arises from the Funnel's emphasis on unique user activity, rather than the number of trips undertaken.
Upon comparing the results of Funnel - All Occurrences with the Flows Trip metrics, the count of User Entered Flows remains consistent.
**Note:** To simplify the querying process, we recommend using
"User Entered Flow" and "Flow Trip Conversion" events. This ensures that
only users who have entered and engaged with the flow are considered when
generating the funnel view. You can use attributes such as "Flow ID" and
"Version Name/ID" to filter for specific flow versions. To differentiate
between user types, you can utilize the "With Control Group" attribute in
these events.
# Explore the Number of Notifications Received by Users
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/explore-the-number-of-notifications-received-by-users
Analyze how many notifications your users receive to find the right sending frequency that drives engagement without causing uninstalls.
Growth teams are always on top of the communication that they send to their customers. They need to know if they are sending too few or too many push notifications or emails.
You know the importance of push notifications in marketing. And you know how important it is that users get the notifications you send. So it’s super critical to keep an eye on the number of notifications received by them. The right number of notifications can boost engagement for your app, but too many of them can drive users to uninstall the app. You should analyze notification frequency regularly to prevent this from happening.
Using MoEngage Analytics, you can easily find out how many of your users are receiving notifications and how many notifications. Here’s how:
## Overall Distribution
1. Go to **Analytics** **>** **Behaviour**.
2. Select **Notification Received Android** as an event.
3. Select **Total events per user** as the *Analysis type* and **Distribution** as *Aggregation type* in *Behavior Options* and click on **Apply** button.

This analysis plots percentile users against the number of times they have received the notification. E.g. bottom 10 percentile users receive 1 notification, 50th percentile users receive 7 notifications and 90th percentile users receive 15 notifications in the last 7 days.
## Custom Distribution
You can modify the distribution bucket based on your desired analysis and see how many users are receiving too many notifications or a specific number of notifications.
You can see the user count for the selected bucket at the hourly, daily, weekly, or monthly level or you can see the user count for the selected bucket for the entire time duration.

The ideal number of notifications to be sent to users varies with the industry and also for the app content/services. Growth marketers would want to analyze:
1. Users receive more notifications and whether they are uninstalling.
2. Users receive fewer notifications and whether they are engaging enough.
3. Users receive an average number of notifications and whether they are converting.
With this analysis, you can take the necessary steps to control the number of notifications and optimize for these metrics and the overall user experience.
Similarly, you can analyze the frequency to answer other questions like:
1. How many times do users open the app?
2. How many users are repeat buyers?
3. How many users open the app or buy too infrequently?
4. What was the highest number of purchases per user for last month?
# How to Optimize Your Analytics Queries
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/how-to-optimize-your-analytics-queries
Best practices to keep MoEngage Analytics queries fast and within your monthly scan allowance.
## Overview
MoEngage Analytics is powered by a query engine that runs directly on your event data stored in a data warehouse. Every analysis you run, whether it's a **Funnel**, **Behavior** analysis, **Retention** report, **RFM**, or a **Custom Dashboard**, translates into one or more queries that read your data.
To ensure that every customer on the platform gets consistently fast and reliable analytics, we enforce a Fair Usage Policy (FUP) on query data scans. This policy is based on your Monthly Tracked Users (MTUs) and ensures that the shared infrastructure remains healthy for everyone.
This article explains how MoEngage's scan-based model works, what happens when you approach your FUP limit, and what you can do to keep your queries fast and well within limits.
## How MoEngage Analytics queries work
MoEngage charges based on the volume of data scanned per query, not the number of queries you run. This means:
* A broad query that touches many events and attributes scans more data.
* A narrow, well-scoped query scans significantly less data and returns results faster.
* The structure and format of your underlying data have a direct impact on how much is scanned.
MoEngage manages all infrastructure and the cost of running queries on your behalf. However, each workspace has a monthly scan allowance based on your MTUs. Queries that consistently scan large volumes of data can exhaust this allowance earlier in the month, which may affect your ability to run additional analyses.
## Fair Usage Policy (FUP) on analytics queries
> [!NOTE]
>
> MoEngage Analytics' data-scan FUP limits are generous for all-around usage. 99.9% of MoEngage customers never reach them.
To ensure fair access to analytics resources for all MoEngage customers, a monthly data scan limit applies to each workspace. This limit is tied to your MTU count.
> [!NOTE]
>
> Your monthly query scan allowance is calculated based on your MTUs and your plan. To check your current usage or request an increase, contact your Customer Success Manager (CSM).
When your workspace approaches or exceeds the monthly scan limit:
* A warning notification appears on the Analytics dashboard.
* Queries might be throttled or restricted until the next billing cycle.
* You can contact your CSM to increase your limit based on your usage needs.
## Query optimization tips
The following best practices help you get faster query results and make the most efficient use of your scan allowance. Implementing these tips benefits every analysis you run: **Funnels**, **Behavior**, **Retention**, **RFM**, and **Custom Dashboards**.
### 1. Narrow your date range
Date range is the single most impactful parameter in any query. The wider the range, the more data MoEngage has to scan. The maximum date range you can select for any analysis is 365 days.
* Use the shortest date range that answers your question.
* Avoid defaulting to 12-month windows unless you specifically need them.
* For recurring dashboards, use rolling windows (Last 7 days, Last 30 days) instead of fixed long ranges.
The granularity you choose narrows this range further:
* Hourly granularity is available for date ranges of up to 31 days in **Behavior**, **Funnels**, and **Session & Source** analyses.
* **Retention** has its own per-granularity durations. For more information, refer to [Retention Analysis](/docs/user-guide/analyze/analytics/retention/retention-analysis#granularity).
> [!TIP]
>
> A 7-day funnel analysis scans roughly four times less data than a 30-day analysis of the same events. Use shorter windows for exploratory work, and only expand when validating a trend.
### 2. Filter by specific events to avoid broad event selection
Each additional event you add to an analysis increases the volume of data scanned. Be intentional about which events you include.
* Select only the events that are directly relevant to your analysis.
* Avoid adding events "just in case". You can always run a follow-up query.
* In **Funnel** and **Behavior** analyses, each step adds to the total scan volume.
### 3. Apply user filters (segments) upfront
Filtering by a segment or user property early in your query reduces the user population Athena needs to evaluate, which reduces the data scanned.
* Apply segment filters at the start of your analysis rather than relying on post-query filtering.
* Use specific user properties (for example, country, platform, or user type) to scope your analysis to a relevant subset.
### 4. Limit the number of event properties you analyze
When you break down an analysis by event properties (for example, splitting a purchase event by product category, payment method, and region simultaneously), each additional dimension increases the data scanned.
* Use one or two breakdowns per analysis rather than stacking multiple unnecessary attribute splits.
* Run separate analyses for separate questions, rather than one wide analysis that tries to answer everything at once.
### 5. Avoid stacking multiple custom dashboard widgets simultaneously
**Custom Dashboards** allow you to visualize multiple metrics on one screen. Each widget executes its own query. If your dashboard has many widgets with broad date ranges and event coverage, opening it triggers a large number of simultaneous scans.
* Group related widgets into focused dashboards rather than one all-encompassing dashboard.
* Use narrower date ranges for dashboard widgets. They refresh faster and scan less.
* Remove widgets you no longer actively use.
## Quick reference: optimization checklist
| Optimization | What to do | Impact |
| - | - | - |
| Narrow date range | Use the shortest range that answers your question | High |
| Fewer events per analysis | Select only relevant events; avoid adding extra steps | High |
| Apply segment filters early | Scope to a specific user cohort upfront | High |
| Limit attribute breakdowns | Use 1-2 attribute splits per analysis | Medium |
| Use saved segments | Avoid rebuilding the same audience filter repeatedly | Medium |
| Optimize dashboard widgets | Fewer widgets, narrower ranges, remove unused widgets | Medium |
## Need a higher query limit?
If your team's analytics needs regularly exceed your current FUP allowance, you can request an increase. Contact your Customer Success Manager (CSM) to discuss your usage patterns and get your limits adjusted.
In addition to raising limits, your CSM can advise on query patterns specific to your integration and suggest workspace-level optimizations based on your event schema.
## Related articles
* [Fair Usage Policy (FUP)](/docs/user-guide/data/key-concepts/fair-usage-policy-fup)
* [Custom Dashboards](/docs/user-guide/analyze/dashboards/custom-dashboards)
* [Funnel Analysis](/docs/user-guide/analyze/analytics/funnels/funnels-overview)
* [Behavior Analysis](/docs/user-guide/analyze/analytics/behavior/behavior-overview)
* [Retention Analysis](/docs/user-guide/analyze/analytics/retention/retention-overview)
* [RFM Segments](/docs/user-guide/segment/create-segments/rfm-segments)
# Key Metrics Queries for Open Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/key-metrics-queries-for-open-analytics
Ready-to-use SQL queries for key metrics like DAU, MAU, new users, and retention in MoEngage Open Analytics to replicate dashboard data.
MoEngage Open Analytics provides capabilities to directly access data from the MoEngage data warehouse. Using SQL queries any data which is present in MoEngage can be accessed.
This document provides all queries for the key metrics provided in the MoEngage dashboard. These queries can be used to get all the data using Open Analytics.
Know more about [dashboard Key Metrics here](/docs/user-guide/analyze/dashboards/key-metrics). Know detail about [MoEngage Open Analytics here.](/docs/user-guide/analyze/custom-analysis/open-analytics)
## Daily Active Users
To calculate daily active users, the table and attributes required are -
* Event used - App/Site Opened. Table name for this event is - moe_app_opened_828.
* Attribute for Platform in App/Site Opened - os
* Time Attribute in App/Site Opened - server_time
* Change **day** for the required date selection.
### Query to get the *Daily Active Users* count
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.moe_app_opened_828
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
### Query to get the *Daily Active Users* count for each platform
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
os AS Platform,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.moe_app_opened_828
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1, 2
ORDER BY
1
```
## Monthly Active Users
To calculate monthly active users, the table and attributes required are -
* Event used - App/Site Opened. Table name for this event is - moe_app_opened_828.
* Attribute for Platform in App/Site Opened -
* Time Attribute in App/Site Opened - server_time
* Change **day** for the required date selection.
### Query to get the *Monthly Active Users* count
```sql SQL wrap theme={null}
SELECT
FORMAT_DATE("%B, %Y", DATE(server_time)) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.moe_app_opened_828
WHERE
day >= "2020-01-01"
AND day <= "2020-12-31"
GROUP BY
1
ORDER BY
1
```
### Query to get the *Monthly Active Users* count for each platform
```text SQL wrap theme={null}
SELECT
FORMAT_DATE("%B, %Y", DATE(server_time)) AS Date,
os AS Platform,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.moe_app_opened_828
WHERE
day >= "2020-01-01"
AND day <= "2020-12-31"
GROUP BY
1, 2
ORDER BY
1
```
## New Users
To calculate daily new users, the table and attributes required are -
* Table for all the latest user properties (This table gets updated every day) - users_base_table
* MoEngage defined ID for app/site users in usertable - user_id
* User Created Date in user table - datetime_cr_t_469
* Change *datetime_cr_t_469* for the required date selection
### Query to get the daily *New Users* count
```sql SQL wrap theme={null}
SELECT
DATE(datetime_cr_t_469) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.users_base_table WHERE
datetime_cr_t_469
>= "2020-01-01"
AND datetime_cr_t_469 <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
## Uninstalled Users
To calculate daily uninstalled users table and attributes required are -
User table checks the fine install status of the user.
* Table for all the latest user properties (This table gets updated everyday) - users_base_table
* MoEngage defined ID for app/site users in usertabel - user_id
* Install Status - bool_installed_178
Device uninstall event to get uninstall action and date time -
* Event used - Device Uninstalled - device_uninstall_985
* Attribute for Platform in Device Uninstalled - os
* Time Attribute in App/Site Opened - server_time
* Change **day** for the required date selection.
### Query to get the daily *Uninstalled Users* count
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.
device_uninstall_985
WHERE
day >= "2019-09-26 00:00:00"
AND day <= "2019-09-27 00:00:00"
AND user_id IN (
SELECT
DISTINCT(user_id)
FROM
account_name.users_base_table
WHERE
bool_installed_178
= "false" )
GROUP BY
1
ORDER BY
1
```
### Query to get the daily *Uninstalled Users* count for each platform
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
o
s
as Platform,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.
device_uninstall_985
WHERE
day >= "2019-09-26 00:00:00"
AND day <= "2019-09-27 00:00:00"
AND user_id IN (
SELECT
DISTINCT(user_id)
FROM
account_name.user_base_table
WHERE
bool_installed_178
= "false" )
GROUP BY
1, 2
ORDER BY
1
```
## New Web Push Subscribers
To calculate daily active users, table and attributes required are -
* Event used -Subscribed to Web Push. Table name -MOE_USER_SUBSCRIBED
* Time Attribute in Subscribed to Web Push - server_time
* Change **day** for the required date selection.
### Query to get the *New Web Push Subscribers*
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.
MOE_USER_SUBSCRIBED
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
## Aggregate Web Push Subscribers
To calculate Aggregate Web Push Subscribers, table and attributes required are -
* Table for all the latest user properties (This table gets updated everyday) - user_base_table
* MoEngage defined ID for app/site users in usertabel - user_id
* Web Subscription Status in usertable- bool_moe_sub_w_106
### Query to get the *Aggregate Web Push Subscribers*
```sql SQL wrap theme={null}
SELECT
COUNT(user_id) AS TotalCount
FROM
account_name.user_base_table
WHERE
bool_moe_sub_w_106
= "true"
```
## Conversion Goal & Revenue
To calculate the total count of conversions and unique converted users, the table and attributes required are -
* Event used - Goal Event specified in [App Settings.](https://app.moengage.com/v3/#/settings/app/general)
* Attribute for Revenue - Revenue attribute specified in [App Settings.](https://app.moengage.com/v3/#/settings/app/general)
* Attribute for Platform in Goal Event - os
* Time Attribute in Goal Event - server_time
* Change **day** for the required date selection.
### Query to get the daily *Conversion Count*
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
COUNT(server_time) AS Conversioncount
FROM
account_name.goal_event
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
### Query to get the daily *Unique Converted Users*
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
COUNT(DISTINCT(user_id)) AS Usercount
FROM
account_name.goal_event
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
### Query to get the daily *Revenue*
```sql SQL wrap theme={null}
SELECT
DATE(server_time) AS Date,
SUM(revenue_attribute) AS Revenue
FROM
account_name.goal_event
WHERE
day >= "2020-01-01"
AND day <= "2020-01-31"
GROUP BY
1
ORDER BY
1
```
# Reachability Queries for Open Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/reachability-queries-for-open-analytics
SQL queries to calculate user reachability across push, email, and SMS channels in MoEngage Open Analytics using the users base table.
MoEngage Open Analytics provides capabilities to directly access data from the MoEngage data warehouse. Using SQL queries any data which is present in MoEngage can be accessed.
This document provides the reachability queries, which are used to derive the reachable users on the platform.
Table and attributed to be used here -
* `users_base_table` - This table has all the latest user properties. This table gets updated every day.
* `string_uid_125` - Client-defined ID for app or site users in the user table.
* `user_id` - MoEngage defined ID for app or site users in the user table.
Know more about [Reachability here](/docs/user-guide/segment/reachability/user-reachability). Know in detail about [MoEngage Open Analytics here.](/docs/user-guide/analyze/custom-analysis/open-analytics)
## Push Reachability
User properties to be used for push reachability -
* Android - `double_moe_rsp_android_144`
* iOS - `double_moe_rsp_ios_157`
* Web - `double_moe_rsp_web_107`
If these flags have the value '200' that particular user is considered as reachable.
Query to get the count of users who are reachable for push notifications.
```sql SQL wrap theme={null}
SELECT
COUNT(user_id) AS Usercount
FROM
account_name.users_base_table
WHERE
(double_moe_rsp_android_144 = 200 OR double_moe_rsp_ios_157 = 200 OR double_moe_rsp_web_107 = 200)
```
Query to get the ID, MoEngage id, and email for Push reachable users on iOS.
```sql SQL wrap theme={null}
SELECT
string_uid_125 AS ID,
user_id AS MoEID,
string_u_em_157 AS email
FROM
account_name.users_base_table
WHERE
double_moe_rsp_ios_157 = 200
```
Query to get the ID, MoEngage id, and email for users who are reachable on both iOS and Web for push notification.
```sql SQL wrap theme={null}
SELECT
string_uid_125 AS ID,
user_id AS MoEID,
string_u_em_157 AS email
FROM
account_name.users_base_table
WHERE
double_moe_rsp_ios_157 = 200 AND double_moe_rsp_ios_157 = 200
```
The above query provides the common users who are reachable on both iOS and Web platforms. Replace **OR** with **AND**to get users who are reachable on at least one of the iOS and Web platforms.
## Email Reachability
User properties to be used for email reachability -
* `string_u_em_157` - Email address of the user
* `bool_moe_hard_bounce_200` - Hard bounce
* `bool_moe_spam_104` - Spam
* `bool_moe_unsubscribe_128` - Unsubscribe
For a user to be reachable via email -
* The email id should be present & valid (should have '@' in the email address)
* Hard bounce, Spam, and Unsubscribe should be false.
Query to get the count of users who are reachable via email.
```sql SQL wrap theme={null}
SELECT
COUNT(user_id) AS Usercount
FROM
account_name.users_base_table
WHERE
string_u_em_157 LIKE '%@%'
AND
bool_moe_hard_bounce_200 = 'false' AND bool_moe_spam_104 = 'false' AND bool_moe_unsubscribe_128 = 'false'
```
Query to get the ID, MoEngage id, and email for reachable users on email.
```sql SQL wrap theme={null}
SELECT
uid_M03C_0_s AS ID,
user_id AS MoEID,
string_u_em_157 AS email
FROM
account_name.users_base_table
WHERE
string_uid_125 LIKE '%@%'
AND bool_moe_hard_bounce_200 = 'false' AND bool_moe_spam_104 = 'false' AND bool_moe_unsubscribe_128 = 'false'
```
If need be, more checks can be used to validate the email address. Here we are only checking if the email id has '@' present in it.
## SMS Reachability
User properties to be used for SMS reachability -
* `string_u_mb_971` - Mobile Number of user
For a user to be reachable on SMS, the mobile number should be present and valid.
Query to get the count of users who are reachable on SMS.
```sql SQL wrap theme={null}
SELECT
COUNT(doc_id) AS Usercount
FROM
account_name.usertable
WHERE
string_u_mb_971 IS NOT NULL
```
Query to get the ID, MoEngage id, and mobile number for reachable users on SMS.
```sql SQL wrap theme={null}
SELECT
string_uid_125 AS ID,
user_id AS MoEID,
string_u_mb_971 AS MobileNumber
FROM
account_name.usertable
WHERE
string_u_mb_971 IS NOT NULL
```
If need be, more checks can be used to validate the mobile number. Here we are only checking if the mobile number value is present for the user.
# Split Analysis on Attributes
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/split-analysis-on-attributes
Split your Behavior, Funnel, and Retention analyses by event or user properties in MoEngage to compare results across different dimensions.
[Behavior](/docs/user-guide/analyze/analytics/behavior/behavior-overview), [Funnel](/docs/user-guide/analyze/analytics/funnels/funnels-overview), and [Retention](/docs/user-guide/analyze/analytics/retention/retention-overview) analysis can be compared or split on the values of the event property and the user properties. Using the split functionality, the analysis can be compared to the values present in the selected attributes.
For Example - From which city users are opening the app, comparing different campaigns for the Funnel analysis, or Comparing retention driven by the different user programs.
Analysis can be performed on event properties or user properties. In MoEngage analytics, user actions are events and events have event properties. User properties are user properties.
# Perform Split Analysis
## Split Analysis on Behavior
To perform the split analysis, add **Split by** attribute to the event in the Behavior Page and click Apply button.

To perform the split analysis on the user properties, add **Group by user property** attributes in the setting options of the Behavior Page and click Apply button.

You can add up to a total of 10 **Split by** and **Group by user property** options in behavior analysis.
## Split Analysis on Funnel
Add the **Split Funnel** attribute to the Funnel Page and click Apply button to get a split analysis. This dropdown has both user and event properties. You can select a maximum of 3 attributes for the analysis.

## Split Analysis on Retention
Add the **Split Cohort** attribute to the Retention Page to get a split analysis. This dropdown has both user and event properties. You can add a maximum of 10 attributes.

## User Property Freshness
All the user properties, which are selected for the **Split by** or **Group by user property** analysis, are the latest value of the user properties available in MoEngage. MoEngage does not provide the split-by analysis of the historical value of user properties.
# Understanding Count Differences in Behavior and Funnel Analyses
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/understanding-count-differences-in-behavior-and-funnel-analyses
Why Total Events in Behavior Analysis and All Occurrences in Funnel Analysis return different counts, explained with practical examples.
Behavior Analysis and Funnel Analysis are two distinct types of analyses; thus, it is not ideal to compare them. This article explains the differences between these analyses with examples to illustrate why there is a difference in the count when we compare the Total Events in Behavior Analysis to that of All Occurrences in Funnel Analysis.
## Behavior Analysis
Behavior Analysis offers insights into specific user actions or events within your application or platform. **Total Events analysis in Behavior shows the count of the number of times users perform a selected event.** This could be ideal for understanding the usage of certain features within your platform.

## Funnel Analysis
Funnel Analysis offers a view of the user's journey through a series of steps or stages, often towards a conversion goal such as a purchase or sign-up. **Funnel - All Occurrences analysis counts all funnels performed by all users. This means each occurrence of a funnel step is counted as a separate funnel.**
For example, if Step 1 initiates a funnel, every time a user completes the funnel, the analysis will record each completion, even if the user completes it multiple times. This could be ideal for visualizing and optimizing user pathways toward specific goals, such as purchasing a product or signing up for a newsletter.

In essence, the two methods serve different purposes. To address your requirements adequately, it is essential to comprehend the distinct objectives of these analyses and choose the right one.
# Understanding Data Differences between Google Analytics and MoEngage
Source: https://moengage.com/docs/user-guide/analyze/analytics-how-to/understanding-data-differences-between-google-analytics-and-moengage
Common reasons for data differences between Google Analytics and MoEngage, covering user identification, session tracking, and attribution.
When comparing data between two analytics platforms, it's essential to understand how the number of users and the metrics are calculated. Most of the analytics platforms have their way of creating, identifying, and merging the user. This article explains why there could be data differences between MoEngage and Google Analytics and lists the common reasons for the differences and possible ways to identify the issues.
For most of our clients, Google Analytics (GA) and MoEngage numbers match, and the difference noticed is marginal(less than 2%). User creation and user identification are the same between MoEngage and GA. Both platforms create a user identifier in their system when a new user visits the App/Website. Both identify users based on the ID provided by the client.
## User creation and merging in GA and MoEngage
| Action | MoEngage | Google Analytics |
| - | - | - |
| Session Unification / User Merging | MoEngage provides universal user merging; all the sessions done by the user are merged into the identified user. For more information, refer to [User Merging](/docs/user-guide/data/user-data/anonymous-to-registered-user-merge). | GA provides session unification/merging. All events/hits done in the session are assigned to the identified user. Previous sessions are not assigned to identified users. For more information, refer to [Session Unification](https://support.google.com/analytics/answer/4574780#zippy=%2Cin-this-article). |
| User Creation after Logout | After logout, if a user visits the App/Site again, MoEngage creates a new user for the device/browser as MoEngage does not know if it is the same user visiting again. (If the user logs in again, they are merged with the identified user.) | After logout, if the user visits the App/Site again, Google Analytics doesn’t create a new user. GA continues with the same user created when the user visited the App/Site for the first time. |
## Common reasons for discrepancies in analytics numbers
The following are the common reasons for differences in the analytics numbers between Google Analytics and MoEngage.
* **Bot Traffic** - Bot traffic comes to your website from search engine crawlers, price-tracing websites, and others trackers. If this traffic is not blocked from MoEngage tracking, it creates unnecessary extra users.
* **Tracking in a subdomain** - For login or checkout flow, sometimes users are directed to a different domain/subdomain. This may lead to new user creation on that page if the integrations are not handled properly.
* **Forced logout** - If users are forced to log out due to any reason, such as an app update, this would result in having many extra users in MoEngage. The logout creates a new user (if the user visits the app/site). If logout is forced in bulk from the client system, many unnecessary users are created in the system, and any user who does not log in again will have two identities in MoEngage.
* **User merging** - If user identification is not implemented properly at MoEngage or GA’s end, the user count may be inflated.
There could be other reasons than those mentioned above, and they are:
* All platforms (Android, iOS, Web) are not integrated with MoEngage/GA.
* Duplicate traffic flowing into MoEngage/GA from SDKs Apps vs. CDPs or from Native Apps vs. Web Apps.
* The Timezone setting on both of the platforms is set for different times.
## Identifying the issue
If there are differences in the data, a basic user analysis and metric comparison between MoEngage and GA can provide insight into why there is a difference. We recommend that you do the following in case of data discrepancies:
* Compare the session count, session duration, and average session per user between MoEngage and GA. If the difference is very high, there could be an integration issue.
* Compare the count of unique users across the platforms (Android, iOS, Web) to identify if the issue is with one of the platforms.
* Compare the count of unique users across the App Versions, OS Versions, and SDK versions to identify if the issue is with a specific App version, OS, or SDK version.
* Verify if there is a higher number of logout performed in MoEngage data. This could create unnecessary users.
* Verify the count of identified vs. non-identified users in MoEngage to check if the user identification has been implemented properly. Also, verify if user merging is happening at MoEngage. If user merging isn't happening, extra users will remain in the system.
* Compare traffic coming from different IP addresses and sources. Check further if you see if many users are created from specific IPs or the specific source
* Take a custom event and compare the counts between GA and MoEngage. If the event count is close (less than 2% difference) and the user count difference is huge, there is a user identification and merging issue.
# Acquisition
Source: https://moengage.com/docs/user-guide/analyze/analytics/acquisition
Measure user acquisition campaign performance in MoEngage by attributing campaigns and publishers to acquired users and lifetime value.
Acquisition analytics enables you to understand the user acquisition campaign performance. User acquisition campaign performance is calculated by attributing acquisition campaigns and publishers to the number of acquired users and their lifetime value metrics.
> [!TIP]
>
> For more information about integrating your acquisition metrics with MoEngage, go through the [Install Attribution page](/docs/partner-guide/data-and-analytics/install-attribution/adjust/adjust).
To access the Acquisition page:
1. Navigate to the MoEngage Dashboard.
2. From the left navigation, select **Analyze** **>** **Acquisition**.

The Acquisition page is displayed.

## Filters
The Acquisition page provides the following filters:
### Report Type
You can perform the Acquisition analysis for the:
* Campaign Name
* Publisher Name
This data is coming into [Install Attribution Partners](/docs/partner-guide/data-and-analytics/install-attribution/adjust/adjust) of MoEngage such as Branch, Applsflyer, and so on.
### Platforms
Acquisition analysis can be filtered for Android, iOS, Windows, or All platforms.
### Time Period
You can perform the Acquisition analysis for a specific time period. This time range filters out the users who are *First Seen* (visited your app for the first time) in the selected time period.
Here the time range filters work in the UTC time zone and not in the App Time Zone. Hence there can be some difference in number between Segmentation and Acquisition.
## Metrics
The Acquisition page provides the following metrics:
### Source
Name of the campaign or publisher. If there is no campaign or publisher found, it is called *Organic* source.
### Users
Count of the user acquired from the respective campaign or publisher.
### Uninstalls
Number of users uninstalled from the respective campaign or publisher.
### Uninstalls/User
Ratio of unistalls to the acquired users. It shows how many users who came from the specific campaign or publisher have uninstalled the app.
### Conversions/User
Ratio of conversion count to the acquired users. It shows how many times an average user who came from a specific campaign or publisher has converted.\
The conversion is counted according to the **Conversion goal** defined at **Settings** > **Account > General settings**.
### Sessions/User
Ratio of session count to the acquired users. It shows how many sessions an average user performs who comes from a specific campaign or publisher.\
This is aggregated according to the user by the definition of a Session—a group of interactions that take place on the app. A session ends after 30 minutes of inactivity and a new session is created if there is an activity after 30 minutes.
### Revenue/User
Ratio of revenue to the acquired users. It shows how much revenue an average user generates who comes from a specific campaign or publisher.\
This is aggregated according to the **Revenue attribute** defined at **Settings** > **Account > General settings**.
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Actionable Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics/actionable-analytics
Turn MoEngage analysis into action — create segments, launch campaigns, export users, or drill into data directly from any chart data point.
# Overview
Every analysis you perform is transformed from being just informative to actionable through actionable analytics. The insights generated can be saved as custom segments, which allows you to take various actions on these segments.
> [!NOTE]
>
> This feature is only available in the Product Analytics package of MoEngage Analytics. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
On any of the chart views, click a data point (such as a bar on a bar chart or a point on a line chart) to open a menu with the following actions directly from the analysis:
* [View sample users](/docs/user-guide/analyze/analytics/actionable-analytics#view-sample-users)
* [Create segment](/docs/user-guide/analyze/analytics/actionable-analytics#create-segment)
* [Create campaign](/docs/user-guide/analyze/analytics/actionable-analytics#create-campaign)
* [Analyze users](/docs/user-guide/analyze/analytics/actionable-analytics#analyze-users)
* [Export users](/docs/user-guide/analyze/analytics/actionable-analytics#export-users)

## View Sample Users
*View sample users* allows you to view a list of up to 50 sample users who are part of the selected data point, helping you validate the data. When you click **View sample users**, a window appears displaying the list of users. Click any user to view their **User Profile**.

## Create Segment
You can save the selected users as a custom segment to take action on them later. Follow these steps:
1. Click **Create segment**. The **Create segment for Analytics** dialog box appears.
2. In the **Segment name** box, enter a name.
3. Click **Create**.

## Create Campaign
You can create a campaign directly for these users. Follow these steps:
1. Click **Create campaign**. The **Create a campaign for Analytics** dialog box appears.
2. In the **Segment name** box, enter a name.
3. Choose the **Campaign channel** and **Delivery type**.
4. Click **Create**. For more information on creating a campaign, refer to [Campaigns and Channels](/docs/user-guide/campaigns-and-channels/getting-started/introduction/moengage-channels).

## Analyze Users
You can analyze the group of users further. Follow these steps:
1. Click **Analyze users**. The **Analyze users for Analytics** dialog box appears.
2. In the **Segment name** box, enter a name.
3. Choose your analysis type from the **Analysis types** list.
4. Click **Analyze**. For more information, refer [here](/docs/user-guide/analyze/analytics).

## Export Users
This allows you to export the user data for the selected data point. For more information, refer [here](/docs/user-guide/analyze/analytics/user-data-exports).
# Next Steps
* [Dashboards](/docs/user-guide/analyze/dashboards)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# Alerts in Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics/alerts-in-analytics
Set up analytics alerts in MoEngage to get notified when metrics in Behavior, Retention, Funnels, or Session and source cross your defined thresholds.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
Alerts let you monitor your analysis data without manually checking dashboards. You define a condition on a saved analysis, and MoEngage emails you when that condition is met — so you can respond to anomalies, drops, and spikes as soon as they happen.
You can create alerts on the following analysis types:
* [Behavior](/docs/user-guide/analyze/analytics/behavior/behavior-analysis)
* [Retention](/docs/user-guide/analyze/analytics/retention/retention-analysis)
* [Funnels](/docs/user-guide/analyze/analytics/funnels/funnel-analysis)
* [Session and source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-analysis)
[Loom video player](https://www.loom.com/embed/3ba77bae60e74b6592cb120f0928af3f)
# Applications
With alerts, you can:
* **Track behavior trends** — get notified when total events, unique users, or unique sessions for a tracked event change significantly.
* **Monitor retention** — watch a specific retention day, such as D7, and get notified when retention moves up or down.
* **Catch funnel drop-offs** — alert on the number of users converting between any two steps of a funnel to spot regressions in the customer journey.
* **Watch session and acquisition health** — track session count, bounce rate, or revenue across sources and get notified when a key metric shifts.
# Who Can Create Alerts
Users with the **Admin**, **Manager**, **Marketer**, or **Analyst** role can create and manage alerts. **Developers** can't create or manage alerts.
You can configure alert access for each role under **Settings > Account > Team Management > Roles > OOB Alerts Management**.
# Create an Alert
Creating an alert is a two-step process:
**Step 1**: [Create Analysis](/docs/user-guide/analyze/analytics/alerts-in-analytics#create-analysis)
**Step 2**: [Create a New Alert](/docs/user-guide/analyze/analytics/alerts-in-analytics#create-a-new-alert)
## Create Analysis
You can set an alert on any saved Behavior, Retention, Funnel, or Session and source analysis. The high-level flow is the same across analysis types:
**1. Build your analysis**
From the left sidebar, go to **Analyze** and choose the analysis type you want to alert on — [Behavior](/docs/user-guide/analyze/analytics/behavior/behavior-analysis), [Retention](/docs/user-guide/analyze/analytics/retention/retention-analysis), [Funnels](/docs/user-guide/analyze/analytics/funnels/funnel-analysis), or [Session and source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-analysis). Configure events, filters, and options, then click **Apply** to view the chart.
**2. Save to My Studio**
Click the **Save** dropdown and select **Save to My Studio**.
> [!NOTE]
>
> You must save the analysis to My Studio before you can set an alert on it.
### Example: Behavior Analysis
This walkthrough builds a Behavior analysis on the *App/Site Opened* event so you can alert when the app or site is opened more than 50 times.
1. In the left sidebar of your MoEngage dashboard, go to **Analyze > Behavior**.
2. In the **Events & Filters** section, click the dropdown and then select **App/Site Opened**.

> [accordion] Optional
>
> You can add the following filters to your event:
>
> * Add multiple attributes — Combine attributes on your event using the **AND** or **OR** logical operators. The analysis applies all attributes and displays the result.
>
> 
> * Split events — Use the **Split by** option to compare the selected attribute with another from the dropdown. To learn more, see [Comparing Properties](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).
>
> 
> * Add multiple events — Use the **+ Add Event** button to add up to 10 events. The analysis runs all events and displays the result.
>
> 
3. Choose which users this analysis applies to. By default, the analysis runs on all users in the workspace. To narrow it down, use the **Filter by users** option.\
To learn more, see [Filter Users](/docs/user-guide/analyze/analytics/behavior/behavior-analysis).

4. In the **Behavior Options** section, select an analysis type to calculate. You can create alerts on these analysis types:
* Total Events
* Unique Users
* Unique Sessions
* Aggregation
* Total Events Per User

5. Click **Apply**.
6. When the **Behavior Chart** appears, click the **Save** dropdown and select **Save to My Studio**.

## Create a New Alert
After you create your analysis, set an alert for it from My Studio.
To create an alert,
1. In the left sidebar of your MoEngage dashboard, go to **Analyze > My Studio**.
2. Select your analysis from the list of **Saved analysis**.

3. Click **Apply** to view the analysis chart, then select your chart type and granularity. See [Alert Subscription Details](/docs/user-guide/analyze/analytics/alerts-in-analytics#alert-subscription-details) for supported chart and granularity combinations.
> [!NOTE]
>
> * Alerts aren't supported on hourly chart granularity.
> * Alerts aren't supported when time-series or segment comparison is applied.
> * The timezone defaults to your app timezone.
4. Click **Set alert** to create a new alert for the selected analysis.

5. On the **Create alert** pop-up, enter the following details:
* **Alert Name** — a unique name for the alert.
* **Alert Criteria** — the trigger condition. The available conditions depend on the analysis type. See [Alert Criteria by Analysis Type](/docs/user-guide/analyze/analytics/alerts-in-analytics#alert-criteria-by-analysis-type).
* **Alert Recipients** — the email addresses of subscribers who should receive the alert. Recipients must have access to the workspace.
* **Alert evaluation time** — when the alert is evaluated and the email is sent.
6. Click **Create**.
# Alert Criteria by Analysis Type
The conditions you can set on an alert depend on the analysis type.
## Behavior
Trigger an alert based on event counts or aggregated values. Available conditions:
* **Above** — triggers when the count for the selected analysis goes above the threshold value.
* **Below** — triggers when the count goes below the threshold value.
* **Increased by percentage (%) or value (#)** — triggers when the count increases relative to the previous period, either by a percentage or by a fixed value.
* **Decreased by percentage (%) or value (#)** — triggers when the count decreases relative to the previous period, either by a percentage or by a fixed value.
You can also refine the criteria using:
* **Select event** — the event you chose during analysis creation.
* **Select Split by** — an event property and value. For example, on the *App/Site Opened* event, split by *Platform* where Platform is *Android*.
* **Select Group by user property** — a user property and value. For example, on the *App/Site Opened* event, group by *last known country* where country is *USA*.
## Retention
Trigger an alert on retention for a specific day in your cohort, such as **D7**.
* Supports **Increased by** or **Decreased by** percentage (%) or value (#).
* **Above** and **Below** thresholds aren't applicable for Retention.
Retention alerts query a rolling window of recent data — up to 365 days for monthly retention. Data older than the window can't be evaluated for alerts, even if it's stored in your workspace.
## Funnel
Trigger an alert on the number of users who convert between any two steps of the funnel.
* The first step is the fixed starting point. You select a second step, and the alert tracks conversions between the two.
* Funnel alerts evaluate the **count of converted users** between the two steps — not the conversion rate. The condition you set is compared against the number of users who completed the second step, regardless of how many users entered the first step.
* **Split by** attributes are supported.
Available conditions:
* **Above** — triggers when the count of converted users goes above the threshold value. For example, with a threshold of 60, the alert fires when 61 users convert.
* **Below** — triggers when the count of converted users falls below the threshold value. For example, with a threshold of 50, the alert fires when fewer than 50 users convert.
* **Increased by percentage (%) or value (#)** — triggers when the count of converted users increases relative to the previous period, either by a percentage or by a fixed number of users.
* **Decreased by percentage (%) or value (#)** — triggers when the count of converted users decreases relative to the previous period, either by a percentage or by a fixed number of users.
> [!NOTE]
>
> Funnel alerts measure the count of converted users, not the conversion rate. A change in traffic volume can trigger or suppress an alert even when the conversion rate between the two steps hasn't changed.
## Session and Source
Trigger an alert on session-level metrics across sources, such as session count, bounce rate, or revenue.
* Most metrics support **Above**, **Below**, **Increased by**, or **Decreased by**. You can set these as a fixed value, or as a percentage (%) or value (#) compared to a baseline.
* **Bounce rate** only supports **Increased by** or **Decreased by** percentage (%).
## Comparison Periods
For **Increased by** and **Decreased by** conditions, the comparison periods you can choose depend on the chart granularity:
| Chart granularity | Available comparison periods |
| - | - |
| Daily | Previous Day, Previous Week, Previous Month |
| Weekly | Previous Week, Previous Month |
| Monthly | Previous Month |
Previous Quarter and Custom Range aren't supported.
# View the Email Alert
After you set up an alert, you receive an email when the specified conditions are met. The email includes a visualization and details about the alert: the change in the metric, the percentage change, and the timestamp when the data was evaluated.

> [!NOTE]
>
> Allow at least 10 minutes of inactivity between creating and scheduling an alert. Otherwise, the alert is scheduled for the next day.
# Unsubscribe, Subscribe, and Delete Alerts
Follow the steps below to view and manage your alerts in your MoEngage dashboard:
1. Click the Settings icon on the left sidebar of your MoEngage dashboard.
2. Scroll down to **Reports and Alerts** and then select **Alert management** from the dropdown.

3. Select the **Analytics alerts** tab and then search for the alert that you want to view or manage.\
Use these options to narrow down your search:
* Use the search bar to find your alert.
* Use the **Created by** dropdown to filter alerts by who created them.
* Use the **Subscribed by** dropdown to filter alerts by their recipients.

4. Once you locate your alert, click the vertical ellipsis icon under the **Actions** column at the right end of the table.
5. You can take the following actions:
* **Unsubscribe**: Remove users from the alert so they no longer receive it for the chosen analysis.
* **Subscribe Others**: Add other users to the alert by selecting their email addresses from the dropdown.
* **Delete**: Permanently remove the alert.

# Alert Subscription Details
This section explains how alerts behave for different chart types and granularities.
| Subscription Frequency | Chart | |
| - | - | - |
| | Line | Bar and Column |
| Daily | You receive the alert at a set time each day.  | You receive the alert at a set time each day.  |
| Weekly | You receive the alert every Monday at a set time.  | You receive the alert on the day and time you select.  |
| Monthly | You receive the alert on the 1st of every month at a set time.  | You receive the alert on the date and time you select.  |
# Limitations
* A workspace can have a maximum of **10 alerts**. To increase this limit, reach out to your CSM or account manager.
* Alerts are delivered by **email only**.
# Advanced Behavior Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/behavior/advanced-behavior-analysis
Advanced Behavior Analysis in MoEngage — use aggregation distributions, formula-based metrics, and custom bucketing for deeper event insights.
# Advanced Behavior Options
For analysis requirements involving complex user behavior data, MoEngage provides advanced analysis options. These features enable elaborate computations and structuring compared to standard count-based reports, yielding detailed results.
* **Aggregation distribution**: This option lets you distribute users into buckets of aggregated event properties. For example, you can get the distribution of users based on the minutes of songs played.

You can also configure **Custom** **Distribution bucketing**. With custom distribution, you will enter the boundaries in the **From** and **to** fields (the lower and upper limits) and an interval size to divide each distribution. This option is available only for numerical properties. Choose boundaries and an interval that produce a maximum of 10 buckets.

* **Total events per user**: This option provides an aggregated count of the total events per individual user. For example, you can get the average number of songs played per user. The aggregation types available are shown below:

* **Attribute aggregation per user**: This is a two-fold aggregation where:

* The attribute is aggregated per user.
* The attribute is aggregated again with data operations.\
The result obtained will provide the arithmetic value of the attribute aggregated per user.\
For example, you can know how long the least active listener played. (**Minimum** of the **Sum** of minutes)
# When to Use Advanced Behavior Options
While standard behavioral reports are excellent for understanding counts and frequencies (For example, "How many users performed 'Song Played'?"), the **Advanced Behavior Options** unlock deeper, more nuanced insights when simple counts aren't enough.
Use these advanced features when your analysis requires:
* **Understanding Distributions:** You need to segment or understand users based on the *magnitude* or *range* of their actions, not just whether they performed an action.
* **Calculating Per-User Aggregates:** You need to know the average, sum, minimum, or maximum value related to an event or attribute *for each individual user*.
* **Complex, Multi-Level Aggregations:** Your question involves calculating a metric for each user first, and *then* performing another calculation (like finding the minimum or average) on those per-user results.
Here’s how each specific option helps solve different analytical challenges:
## Aggregation Distribution
* **What it does:** Groups users into defined buckets based on an aggregated numerical event property (for example, total minutes played, total purchase value). You can use predefined or custom ranges.
* **When to use it:**
* When you need to segment users based on their level of engagement or value (for example, low, medium, and high spenders).
* When you want to visualize how users are spread across different levels of activity for a specific metric.
* When understanding the distribution is more important than just the overall average or sum.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **E-commerce:** Identify user segments based on total spending over the last 30 days (for example, buckets of $0-$50, $51-$200, \$201+).
* **Media/Streaming:** Understand content consumption patterns by distributing users based on *Total Watch Time* or *Total Songs Played* within a period (For example, 0-10 mins, 11-30 mins, 31+ mins).
* **Gaming:** Group players based on *Total Levels Completed* or *Total In-App Purchases Value*.
* **Content Platforms:** Segment users by *Number of Articles Read* or *Total Time Spent Reading*.
## Total Events Per User
* **What it does:** Calculates an aggregate (Sum, Average, Min, Max, etc.) of the number of times an event occurred for each individual user.
* **When to use it:**
* When you need to understand the frequency or volume of actions per user.
* When you want to find the average, minimum, or maximum number of times users perform a key action.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Engagement:** Calculate the *Average Number of App Opens per User* per week.
* **Feature Usage:** Find the *Maximum Number of Searches performed by any single User* last month.
* **Activity Level:** Determine the *Average Number of Orders Placed per User*.
* **Content Interaction:** Get the *Average Number of Videos Watched per User* daily.
## Attribute Aggregation Per User
* **What it does:** Performs a two-step aggregation. First, it aggregates a numerical attribute for *each user* individually (for example, the Sum of *Purchase Amount* per user). Second, it applies another aggregation across *those per-user results* (for example, Minimum of the per-user sums).
* **When to use it:**
* When you need insights derived from comparing individual user aggregates.
* When you want to find the extremes (for example, the user who spent the least *in total*, the user with the highest *average* session length).
* When you need to understand overall patterns based on metrics calculated at the individual user level.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Identify Least Active Users:** Find the *Minimum of the Sum of 'Session Duration'* across all users to see the lowest total engagement time. (Example: "How long did the least active listener play?")
* **Understand Power User Behavior:** Calculate the Maximum of the Sum of *Levels Completed* to find the highest total level progression achieved by any single user.
* **Analyze Spending Patterns:** Determine the Average of the Maximum *Single Transaction Value* per user to understand the typical highest purchase amount across your user base.
* **Content Consumption Insights:** Find the Average of the Sum of *Watch Time* per user to understand the typical total viewing duration for users.
By leveraging these advanced options, you can move beyond simple event counts to uncover sophisticated patterns in user behavior, enabling more precise segmentation, targeted campaigns, and informed product decisions.
# Next Steps
* [Dashboards](/docs/user-guide/analyze/dashboards)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# Compare Mode in Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics/compare-mode-in-analytics
Compare analyses across time periods and user segments with MoEngage Compare Mode to draw multi-perspective insights from a single query.
Compare Mode in MoEngage Analytics enables you to compare your analyses with different elements, such as Time Series and multiple Segments. Rather than performing separate analyses for each insight, this mode allows users to utilize a single analysis to gain insights from multiple perspectives.
By leveraging the Compare Mode, you can gain a more comprehensive understanding of your data and draw actionable insights to improve your operations. This approach promotes efficiency, reduces redundancies, and ultimately drives better decision-making.
# Time Series Comparison
Time Series Comparison allows the juxtaposition of critical metrics from past time duration. In contrast to examining performance indicators from a single period, this approach enables the comparison of data across multiple time intervals, providing a more comprehensive, contextual view of trends and performance. By gaining a deeper understanding of how metrics change over time, you can make informed decisions based on historical data, which, in turn, can lead to improved business outcomes.
When analyzing user engagement metrics for a product feature, comparing data from June to May can reveal patterns, growth trajectories, or emerging concerns. Hence, time-series comparison can offer:
1. **Contextual Analysis:** Understanding metrics in the context of time adds depth to data. A spike in user activity might look impressive, but compared to previous months, it might reveal a declining trend.
2. **Swift Pattern Recognition:** Comparing time series data can prove useful in identifying recurring patterns, particularly in relation to seasonal fluctuations in sales or user engagement. You can rapidly detect these patterns and gain valuable insights into the performance and behavior of your systems. It can help you to make informed decisions and optimize your operations.
3. **Data-Driven Forecasting:** Data-driven forecasting enables proactive strategy adjustments by predicting future performance based on past trends.
[Loom video player](https://www.loom.com/embed/6376d9deab6549dca0293f032eefd683)
## Time Comparison on Behavior, Funnels, Retention, and Session & Source
After performing an analysis, click on the **Compare to Past** button at the top of your chart and select the duration you wish to compare to. You can also select a custom date range starting with or ending with to do a custom comparison equal to the baseline duration.

Let's look at an example...
After performing a Behavior Analysis, you want to compare the Total Events of App/Site Opened of the current week to last week.
Select on chart: *Compare to Past -> Previous week*
Line Chart:


Bar Chart:


In the case of Funnels, you will be able to visualize the conversion of the events for both the Current duration and Previous duration


The Retention Tables come with a default Comparative Overall Retention view. To access the Retention table for both the Current and Previous duration, just click the **_Expand table_** option.


**Note**: Time comparison is available only on line, bar, and column charts. It is not available on area and pie charts.
## Actionable analytics in time compare mode
Actionable Analytics can be performed **_only on the current duration_**.
When analyzing behavior and funnel analysis, simply click on the data point of the current duration line or bar to use actionable analytics. For retention analysis, use the retention table of the current duration and apply actionable analytics.

# Segment Comparison
Segment Comparison enables you to perform a comprehensive analysis of multiple user segments concurrently on MoEngage Analytics. This feature lets you juxtapose and scrutinize data for different segments, leading to more comprehensive insights. Rather than analyzing data for one segment in isolation, you can compare and contrast metrics across various segments, leading to a more exhaustive understanding of the data. Segment comparison is also an efficient way to analyze data and helps you to gain a more nuanced interpretation.
For instance, consider you're evaluating the behavior of two distinct user groups: those who made a purchase in the last month versus those who didn't. The Segment Comparison feature will allow you to analyze the differences and similarities between these two segments side by side. Furthermore, it offers:
1. **Holistic Understanding:** You can gain a comprehensive understanding of patterns and anomalies by comparing different segments, a practice that can reveal insights that are often missed when analyzing a single segment. This 360-degree view is invaluable in making informed decisions.
2. **Optimization of Marketing Efforts:** As a growth marketer, you can leverage this approach to optimize your marketing efforts by swiftly identifying underperforming segments, and directing resources and campaigns more effectively.
3. **Enhanced User Experience:** As a product manager, you can utilize segment comparison to tailor product features for specific user groups, leading to an elevated user experience and enhanced user satisfaction.
[Loom video player](https://www.loom.com/embed/4dcb9ce204ee4cc3967d359d8ebf7fab)
## Segment Comparison on Behavior, Funnels, Retention, and Session & Source
After selecting the events, click on the **Add segment to compare** in the Filter users section and select the segment based on User Property, User Behavior, User Affinity, or a Custom Segment.
You can select a maximum of five segments for comparison.

Let's look at an example...
After performing a Behavior Analysis with multiple segments, here's an example of output chart and table:


In the case of Funnels, you will be able to visualize the conversion of the events for all the segments selected for the analysis


The Retention Tables come with a default Comparative Overall Retention view. To access the Retention table for both the Current and Previous duration, just click on the **_Expand table_** option.


**Note**: Segment comparison visualization is not present on Area and Pie charts.
## Actionable analytics in segment compare mode
Actionable Analytics can be performed **_on all segments selected during the analysis._**
When analyzing behavior and funnel analysis, simply click on the data point of the current duration line or bar to use actionable analytics. For retention analysis, use the retention table of the current duration and apply actionable analytics.

> [!NOTE]
>
> You cannot use time comparison and segment comparison together in the same analysis. Segment comparison starts when you add a second segment, so time comparison stays unavailable until you remove the extra segments.
# Compare mode on custom dashboards
The Compare Mode functionality integrated within the Custom Dashboards of MoEngage Analytics offers the ability to juxtapose two distinct datasets, enabling you to compare Time Series or Segment data with ease. This feature eliminates the need to create separate reports for each dataset, thus streamlining the process and saving valuable time. By using a single report to gain insights from multiple angles, you can enhance your decision-making capabilities and expedite the process of generating actionable insights.
[Loom video player](https://www.loom.com/embed/814502a52bd640d69f27ed74a76ea015)
The custom dashboard contains charts and tables of Behavior, Funnels, Session and Source, and Retention.
* To perform a **time series comparison** on the custom dashboard, please perform the following steps:\
*Dashboard Filters -> Select Duration -> Select Previous Duration -> Apply*

* To perform a **segment comparison** on the custom dashboard, please perform the following steps:\
*Dashboard Filters -> Click Filter users -> Select Segments -> Apply*

### Use-cases of Comparative custom dashboards:
1. **Campaign Optimization:** When evaluating the impact of two different campaigns, the Time Series comparison offers a side-by-side view of their performance metrics. This direct comparison helps in identifying which campaign strategies are yielding better results.
2. **Audience Understanding:** Segment Comparison is a boon when trying to understand audience behaviors. For instance, by comparing metrics of users acquired through organic search against those from paid campaigns, you can make informed decisions on budget allocation and strategy tweaks.
3. **Feature Adoption Analysis:** With new feature rollouts, as a product manager, you can use Time Series comparison to analyze user engagement before and after the rollout, thus gauging the feature's success.
4. **User Behavior Insights:** By comparing how different user segments interact with the platform, as a product manager, you can tailor experiences based on distinct user needs. For instance, if one user segment uses a specific feature more than another, those insights can be employed to optimize the product experience for that segment.
5. **Iterative Product Development:** Segment Comparison in the Custom dashboard offers a dynamic view of how different user groups are reacting to changes. This continual feedback loop ensures that product enhancements align with real user needs.
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Customizing Chart Labels
Source: https://moengage.com/docs/user-guide/analyze/analytics/customizing-chart-labels
Rename legend labels and axis ticks in MoEngage Analytics charts to replace technical event names with business-friendly terms for reports.
To provide better clarity and context for your data visualizations, MoEngage allows you to customize legend names and axis ticks within MoEngage Analytics. This ensures that your charts are intuitive and tailored to your specific business terminology when you share dashboards or save queries.
Renaming legends and ticks allows you to replace technical event names or system-generated labels with user-friendly titles. This is particularly useful for executive reporting or cross-functional sharing where stakeholders might not be familiar with backend event naming conventions.
## **Use Cases**
* **Humanize Technical Names**: Rename developer-coded events (for example, 'btn_clk_01') to readable titles such as "Home Button Clicks" for instant stakeholder clarity.
* **Contextualize Time Axes**: Replace standard ticks with business milestones (for example, "Holiday Sale") to highlight the impact of specific campaigns directly.
* **Translate Abstract IDs:** Swap technical identifiers, such as Location IDs, for descriptive labels (for example, "London") to remove the friction of using lookup tables.
## **Renaming Chart Legends**
You can edit legend names directly from the chart visualization. After you modify them, these names are preserved when the query is saved or when a chart is added to a dashboard.
Legend and tick renaming are available in the following analysis types:
* **User Analysis**
* **Behavior**
* **Funnel**
* **Retention**
* **Session & Source**
> [!NOTE]
>
> **Information**
>
> This feature is **not supported** for **User Paths**, **Acquisition**, or **Uninstall** analyses. Legend renaming is unavailable for Custom Distribution charts because the distribution buckets are manually defined by the user.
### **How to Rename a Legend**
To rename a legend, perform the following steps:
1. Navigate to a supported Analytics module (such as Behavior).
2. Execute your query to generate the visualization.
3. In the legend area (typically located below the chart), click the **Edit** (pencil) iconnext to the **Legend text** you want to change.
4. Type the new name and press **Enter** or click away to save.

Saved names will appear in the table. If a data point is represented by multiple cells (such as in **Split By** scenarios), all corresponding cells are updated with the provided name.

## **Renaming Axis Ticks**
In specific visualization types, you can rename "ticks" (the labels on the x-axis). This functionality is available exclusively for **Column Charts** in the following scenarios:
* **Time Comparisons:** When comparing data across different time periods (for example, "This Week" vs. "Last Week").
* **Segment Comparisons:** When comparing data across different segments (for example, "New Users" vs. "Returning Users").
### **How to Rename Ticks**
To rename ticks, perform the following steps:
1. Switch your chart view to **Column Chart**.
2. In the tick area (typically located below the chart), click the **Edit** (pencil) icon next to the **Legend text** you want to change.
3. Type the new name and press **Enter** or click away to save.

To restore the original name, click the **Edit** (pencil) icon next to the Legend text you want to restore. Delete the existing name and press **Enter** or click away to save.

# Advanced Funnel Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/funnels/advanced-funnel-analysis
Explore advanced funnel options in MoEngage — analyze time to convert, frequency distributions, and detailed step-by-step conversion data.
# Advanced Funnel Options
Advanced funnel options let you answer deeper questions about your funnels. Instead of just seeing who converted, you can explore how quickly users tend to move between key steps and how often they perform certain actions before moving forward in the funnel.
* **Time to convert - Unique Users**: This option distributes the time users take to complete the specified steps. For a single user, MoEngage considers the best time to convert (least time) between the specified steps. This analysis can be performed between two defined steps:

* **Auto:** This displays the time taken for each percentile of users who completed the selected steps. For instance, it shows how much time is required for 50% of the users to convert. The X-axis represents user percentiles (from 1 to 100), while the Y-axis indicates the corresponding time to convert.
* **Custom**: Using custom distribution, you can customize time buckets. This will provide the number of users converted for the selected step within the time bucket. You can analyze a maximum of 25 buckets. Distribution buckets include the lower boundary point and exclude the upper boundary point.
* **Time to convert - All Occurrences**: This option provides the distribution of time taken by all occurrences of conversion for the defined steps. For a single user, MoEngage considers the best conversion time out of all the conversions between the defined steps if the user has completed the steps multiple times. You can perform this analysis between two defined steps. This funnel type has **Distribution bucketing** options similar to those of **Time to convert - Unique Users**.
* **Frequency - Unique Users**: This option provides the distribution of the number of times (frequency) a step has been performed before the succeeding (next) step. For a single user, MoEngage considers the lowest frequency count for the analysis. This analysis can be performed between two consecutive defined steps:

* **Auto**: This provides the frequency of performing a step before the next step for each percentile of users. For example, how many times users have viewed the product before purchasing it for 50% of the users. Here, the X-axis provides the user percentile (1 to 100), and the Y-axis provides the respective frequency count.
* **Custom**: Using custom distribution, you can customize the frequency buckets. This will provide the number of users for the selected frequency bucket. You can analyze a maximum of 25 frequency buckets in a single analysis. Distribution buckets include the lower boundary point and exclude the upper boundary point.
* **Frequency - All Occurrences**: This option provides the distribution of the number of times (frequency) a step has been performed before the succeeding (next) step. For a single user, MoEngage considers all frequencies for the analysis. You can perform this analysis between two consecutive steps. This funnel type has **Distribution bucketing** options similar to those of **Frequency - Unique Users**.
# When to Use Advanced Funnel Options
Standard funnel analysis illustrates who converted between steps and at what rate. **Advanced Funnel Options** go further, allowing you to explore the dynamics of how users progress through your funnels, specifically, how quickly they move and how often they perform steps before advancing.
Use these advanced options when your analysis requires understanding:
* **Conversion Velocity:** You need to know how much time typically passes between key funnel steps.
* **Action Repetition:** You want to understand how many times users perform a specific action before moving to the next step in the funnel.
* **Behavior Across Attempts:** You need to differentiate between analyzing a user's first/fastest path versus analyzing all their attempts through the funnel steps.
Here’s how each specific option helps solve different analytical challenges:
## Time to Convert - Unique Users
* **What it does:** Measures and distributes the time taken for users to complete a sequence between two defined steps for the first time or their fastest time if they've done it multiple times. It offers *Auto* (percentile distribution) and *Custom* (user-defined time buckets) views.
* **When to use it:**
* When you need to understand the typical speed of initial conversion between two key milestones.
* To measure the effectiveness of time-sensitive campaigns or promotions.
* To identify bottlenecks where users take an unusually long time on their first successful attempt.
* When focusing on the optimal or initial user journey between two points.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Campaign Urgency:** Analyze the time between *Campaign Email Clicked* and *Purchase Completed* to see if limited-time offers drive faster conversions (for example, using Custom buckets like 0-1 hr, 1-6 hrs, 6+ hrs). The Auto view can show the median time (50th percentile).
* **Onboarding Efficiency:** Measure the time taken from *Account Created* to *First Key Action Completed*.
* **Feature Adoption Speed:** Track how quickly users move from *Feature Discovery Event* to *First Feature Use Event*.
## Time to Convert - All Occurrences
* **What it does:** Measures and distributes the time taken for all occurrences of conversion between two defined steps, considering users might complete the sequence multiple times. It also offers *Auto* and *Custom* distribution.
* **When to use it:**
* When users can repeat the funnel sequence, and you want to analyze the time dynamics across *all* their successful attempts.
* To understand conversion speed for recurring behaviors or processes.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Repeat Purchase Velocity:** Analyze the typical time between *Added to Cart* and *Purchase Completed* across all purchase journeys for repeat buyers.
* **Recurring Task Duration:** Measure the time taken from *Task Started* to *Task Completed* for processes users might perform repeatedly (for example, submitting expense reports, completing lessons).
## Frequency - Unique Users
* **What it does:** Measures and distributes the number of times users perform a specific step *before* successfully moving to the *next consecutive* step for the *first time* (or the instance with the *lowest* frequency count). It offers *Auto* (percentile distribution) and *Custom* (user-defined frequency buckets) views.
* **When to use it:**
* To understand how much hesitation, exploration, or repetition occurs before a user commits to the next step in their initial journey.
* To identify friction points where users repeat an action many times before proceeding.
* When focusing on the efficiency of the initial or most direct path between two consecutive steps.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Product Consideration:** Analyze how many times users perform *Product Page Viewed* before *Add to Cart* (lowest frequency) to understand initial browsing behavior.
* **Search Effectiveness:** Measure the number of *Search Performed* events before a *SearchResult Clicked* event.
* **Form Completion:** Track how many times *Help Tooltip Viewed* occurs before *Form Field Completed* for a complex field.
## Frequency - All Occurrences
* **What it does:** Measures and distributes how many times users perform a specific step *before* successfully moving to the next consecutive step, considering all instances where the user completes this transition. It also offers *Auto* and *Custom* distribution.
* **When to use it:**
* When users can repeat a sequence of steps, you want to understand the repetition behavior across all their journeys through those steps.
* To analyze prerequisite actions or exploration behavior in recurring processes.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Cross-sell/Upsell Exploration:** Across all purchase journeys, how many times do users trigger *View Recommended Product* before *Add to Cart*?
* **Learning Patterns:** For users completing multiple modules, how many times do they typically perform *View Lesson Video* before *Complete Quiz* across all modules?
* **Support Interaction:** Analyze the frequency of *View FAQ Article* before *Submit Support Ticket* across all instances of users submitting tickets.
By leveraging these advanced funnel options, you gain deeper insights into user momentum and behavior within your funnels. This enables better optimization of conversion speed, identification of friction points, and a more nuanced understanding of user journeys.
# Next Steps
* [Dashboards](/docs/user-guide/analyze/dashboards)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# Funnel Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/funnels/funnel-analysis
Set up funnel steps in MoEngage Analytics — configure event sequences with attribute filters and track conversion rates at every stage.
# Step 1: Define Funnel Steps
A funnel is a sequence of events and needs at least two steps. Consider an example of a product purchase flow with four steps on your app or website. Using this example, we can define an event for each step of the funnel in the order of *App Opened*, *Product Viewed*, *Added to Cart*, and *Order Successful*.

Each event can be further filtered using **+ Attributes**. Add event filters for specific user actions, such as Platform, App Version, and so on.

You can combine multiple events for a given step in a funnel. For example, in addition to the above flow of product purchase, consider a flow where the second step of the funnel is *Product Searched*. You can use **OR** to add this event. Users who perform either of the events on the second step will be qualified for funnel calculation.

To remove an event sequence from the analysis, turn the **Exclude events from funnel** toggle on. Excluding events enables users to move to the next step in the funnel only if they do not perform the specified events between the specified steps. If the users perform the excluded event in between the selected steps, the funnel for the user will end there. For example, if you want to exclude the event *Coupon Applied*, you will add this as an excluded event between the applicable steps. The flow will look something like App/Site Opened > Product Viewed > Add to Cart > Exclude *Coupon Used* > Order Successful.

# Step 2: Filter Users
By default, you can perform this analysis on all users. However, you can also query for a group of users filtered using User Properties, User Activity, User Affinity, Custom Segments, or any such combination. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
To compare results across segments instead, use Compare Mode. You can select a maximum of five segments. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 3: Choose Funnel Option
You have the following options to measure the funnel:

* **Funnel - Unique Users**: This option counts the number of unique users who have completed the specified steps. In this funnel type, each user is counted only once. If the user completes the entire funnel multiple times, the completion count is one.
* **Funnel - All Occurrences**: This option counts the total number of funnel step completions. If a user has completed the entire funnel multiple times, all instances of completion are included in the analysis.
For information on advanced Funnel options, refer to [Advanced](/docs/user-guide/analyze/analytics/funnels/advanced-funnel-analysis).
# Step 4: Configure Funnel
After choosing your funnel type, you have the following options to configure your funnel:

* **Duration**: Here, you can select a duration for your funnel analysis. By default, it is performed for the last 7 days.

* **Funnel split**: The funnel split enables comparison of funnels based on the event property values. The analysis can be compared to any of the defined step's event properties. The funnel analysis is divided into values of the event property, and the analysis will be presented in a table and chart. You can select a maximum of three attributes for split analysis. There are three options to perform a funnel split:

* **All Steps**: Here, an event property must exist across all specified events of the funnel across all steps (including OR and exclude events). All funnel events are first filtered by a specific attribute value, after which funnel analysis is performed on them.
* **First N Steps**: Here, an event property must exist in the first N steps of the funnel (including OR and excluding events). Funnel analysis is performed for each value of the attribute up to the selected Nth steps. MoEngage uses a forward-filling method to complete the funnel analysis for events occurring after the Nth step. With forward filling, a single event can be attributed to multiple funnels.
* **Nth Step**: Here, the event properties of the selected Nth step are available for analysis. Ensure that the event property is present in all **OR** events of the defined step. MoEngage performs backward filling, forward filling, or both as required (depending on the step selection).
* **Holding Attribute**: When an attribute, such as product ID, is carried through multiple steps of the funnel, holding the attribute becomes crucial. The holding attribute constant considers the user and holding attributes as a pair that completes the funnel. You can select a maximum of three attributes.
* **Funnel window**: The funnel window can be used to analyze whether all the defined steps were completed in a specific amount of time. For instance, if you would like to see how many users opened the app (first step) and then made a purchase (last step) within 5 minutes, you can set this limit as the funnel window.
* **Order**: Turning the **Strict** toggle on considers user events or activities based on the sequence defined in the funnel steps. A *Strict Order* funnel displays the number of users who have completed all steps in the specified order without performing any steps out of sequence.
# Step 5: Choose Charts
After your chart is generated, depending on the type of data, you can switch the chart view for better visualization. You can choose between a line chart or a bar chart to view progress, compare volumes over a time period, or compare absolute numbers.

Charts show a maximum of 20 different entities. The remaining entities are available in tabular format. By default, Funnels is shown in a bar chart for the selected time period.
You can also break down the report into **Hourly**, **Daily**, **Weekly**, or **Monthly** granularities and switch between percentage and absolute values for easy visualization. Funnel users will be displayed based on the selected granularity. Hourly granularity is available for date ranges of up to 31 days.
You can compare the funnel with a past period or across segments, but not both in the same analysis. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 6: Tables
In addition to charts, the data is also available for analysis in a tabular format. You can sort the table or change its view using the transpose feature. Additionally, you can download the data in CSV format. For more information, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
# Save to My Studio or Custom Dashboard
Your analysis is now ready. To access this later, you can save the analysis.
To save:
1. Click the icon in the upper-right corner and click **Save to My Studio.**
2. Additionally, you can save the analysis to a custom dashboard. Choose the required option from the list:

3. Select the dashboard where you want to save the analysis. You can choose an existing dashboard or create a new one.

4. Enter a name for your analysis to help you identify.
5. Enter a brief description of the analysis.
6. Click **Save**.
You can access the analysis by navigating to **Analyze** > **My Studio**. To access the custom dashboard, navigate to **Dashboards**.
# Next Steps
* [Advanced](/docs/user-guide/analyze/analytics/funnels/advanced-funnel-analysis)
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [Retention](/docs/user-guide/analyze/analytics/retention/retention-overview)
# Funnels - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/funnels/funnels-overview
Track user conversion across web and mobile with MoEngage Funnels — measure drop-offs at each funnel stage and optimize engagement strategy.

**Funnel Analytics**
E-Learning Course
[Open](https://academy.moengage.com/student/activity/3387982-funnel-analytics)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
MoEngage Funnels provides detailed insights into user conversion across web and mobile applications. Funnels help you understand user interactions at various stages of the customer journey, offering valuable data for optimizing engagement strategies.
A funnel represents a series of events that guide towards a defined event. It is used to calculate conversion rates based on certain user actions. The charts obtained help evaluate conversion rates at each stage of the funnel and assess the overall performance of your product.
# Use Cases
Funnels help answer questions like:
* How many users searched for a hotel on my travel application and booked one?
* How many times did users view a notification, click it, and then get converted?
* What percentage of users who visited a particular product on my e-commerce app bought it?
* How many times do users play a game before moving to the next level?
* How much time do users take to purchase a product?
* At what stage of the buying process are most users dropping off?
# Getting Started
[YouTube video player](https://www.youtube.com/embed/A5YASqd701M)
We will begin with performing Funnel Analysis in the next section.
# Next Steps
* [Analysis](/docs/user-guide/analyze/analytics/funnels/funnel-analysis)
* [Advanced](/docs/user-guide/analyze/analytics/funnels/advanced-funnel-analysis)
# Object Data in Analytics
Source: https://moengage.com/docs/user-guide/analyze/analytics/object-data-in-analytics
Query nested object data attributes in MoEngage Analytics to analyze complex event properties like trip details without flattening your schema.
# Overview
Object data allows you to get deeper insights into user interactions. By querying attributes within an object, you can perform more effective analysis based on the specific characteristics of the events you track.
This approach allows you to query complex, related data points in their natural structure (like a 'trip' object containing 'source' and 'destination' details) without needing to flatten all possible variations into separate, top-level event properties.
# Create Analytics Queries with Object Data
You can leverage object data within Analytics to build powerful queries. The attributes of an object can be of any primitive data type, such as string, numeric, or date. The following example shows how to create a Behavior Analysis query using an event that contains object data.
For data structures where an array of objects is nested within another array of objects, you can perform analysis by creating queries that span across both levels. This allows you to analyze events based on a combination of attributes from the parent array and the nested array within the same object element.
Consider a *SEARCH_BUS* event, where the event property **trip** is a single object that contains details like its *source*, *destination*, and *journey_date*.
```json Example Event Data theme={null}
{
"SEARCH_BUS": {
"trip": {
"source": {
"city": "Bengaluru",
"state": "KA"
},
"destination": {
"city": "Chennai",
"state": "TN"
},
"journey_date": "2025-11-20",
"passenger_count": 2
}
}
}
```
Now, let's create an analysis. Say you want to query for *SEARCH_BUS* events where the *trip* object has a *journey_date* that exists, AND the *destination.city* within that same *trip* object is *Chennai*.
1. On the **Behavior Analysis** page, select the event. For our example, we will select *SEARCH_BUS*.
2. Click **+ Attributes** and start by filtering for the attribute: `trip.journey_date`.
3. Click the **+ With** operator that appears indented. This allows you to add more conditions that must be true for the same *trip* object.
4. Add the condition: `trip.destination.city` is *Chennai*.
5. Follow the rest of the steps to create your analysis. For more information, refer [here](/docs/user-guide/analyze/analytics/behavior/behavior-analysis).

This query uses the **With** operator to ensure all conditions are met within the same *trip* object. It will find *SEARCH_BUS* events that have a trip where the `journey_date` exists AND the `destination.city` is *Chennai*.
For more information on the functionality of operators such as "With" and "And/Or" for querying object data, refer to [Object Data Type in Segmentation](/docs/user-guide/segment/advanced-concepts/object-data-type-in-segmentation).
# Current Analytics Functionality
Support for using object data attributes in the following Analytics functionalities is planned in the next phase:
* All analytics features
* Split by
* Group by user property
* User Analysis
* Distribution
* Date/Timestamp Attributes
For scenarios requiring these capabilities in the meantime, consider transforming your data into simpler, primitive types before ingestion.
# Next Steps
* Learn more about the various analysis types [here](/docs/user-guide/analyze/moengage-analytics/overview).
* Learn more about defining user groups in [Create Segments](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
* Understand how to use the "With" and "And/Or" operators in [Object Data Type in Segmentation](/docs/user-guide/segment/advanced-concepts/object-data-type-in-segmentation).
# Advanced Retention Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/retention/advanced-retention-analysis
Go beyond standard retention cohorts with MoEngage advanced options — first occurrence analysis, cumulative return rates, and granular views.
MoEngage provides advanced analysis to help you gain a deeper understanding of user retention beyond standard cohort charts. This will allow you to explore the nuances of user return behavior and engagement patterns over time.
# First Occurrence
First Occurrence shows the percentage of users who perform the return event for the first time (after the first event) on a specific day. It is the percentage of users who haven't performed the return event until the selected day. The First Occurrence is how long the users take to perform the return event. For a higher level of granularity, choose hour, week, or month instead of day.\
For example, the user installed the app (first event) on Day 0. The user did not perform the purchase (return event) on Day 1 and Day 2, so the user is counted as inactive on those days. On Day 3, when the user purchases for the very first time, the user is counted as a returned user. We do not consider what happens after Day 3 because this analysis only provides how long the user was away from the app before they came back and performed the returned event.


# When to Use First Occurrence
Standard retention analysis typically shows the percentage of users who return and perform an action on specific days, weeks, or months after an initial event. **First Occurrence** allows for a more specific analysis focused on the timing of initial re-engagement.
Use this advanced feature when your analysis requires understanding:
* **Time to Initial Re-engagement:** You need to know how long it takes for users to perform a specific return action for the very first time after their initial interaction.
* **Activation Timelines:** You want to measure the latency between an initial event (like an install or sign-up) and the first instance of a key follow-up action (like a purchase or core feature usage).
Here’s how the First Occurrence option helps solve specific analytical challenges:
* **What it does:** Measures and shows the percentage of users who perform a specific *return event* for the very first time on a particular day, week, month, or even hour after performing the *first event*. It specifically tracks how long users take to perform that return event once, ignoring any subsequent performances of the return event.
* **When to use it:**
* When the critical insight is understanding the time lag until the initial activation or key action, not just general repeat behavior.
* To measure how quickly users reach a specific milestone for the first time after starting their journey.
* To analyze the effectiveness of onboarding or initial engagement campaigns in driving a specific first action.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Time-to-First Purchase:** After an *App Install* (first event), track daily/weekly/monthly cohorts to see when users make their *Purchase* (return event) for the first time. This helps you understand how long it takes to convert new users into buyers.
* **Core feature adoption lag:** Following *Account Signup* (first event), determine how many days/weeks it takes for users to perform *Used Core Feature X* (return event) initially. This indicates how quickly users discover and engage with key functionality.
* **Onboarding completion time:** After *Started Onboarding Flow* (first event), analyze how long it takes users to trigger *Completed Onboarding Step 5* (return event) for the first time.
By leveraging the First Occurrence option, you can gain precise insights into the critical time it takes for users to perform key actions for the first time after an initial event, helping you optimize onboarding flows, activation strategies, and initial engagement campaigns.
# Next Steps
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [Session and Source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview)
# Retention Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/retention/retention-analysis
Step-by-step guide to Retention Analysis in MoEngage — define first and return events, apply filters, and choose your visualization options.
# Step 1: Define Events
An event is any action a user performs on your app that is tracked. Retention is when a user performs an event and then returns to do another event. Select the **First Event** and **Return Event** from the list for your analysis. A retention analysis uses two events: one first event and one return event.

Each event can be further filtered using **+ Attributes**. Add event filters for specific user actions, such as *Platform* and *App Version*.

Use **+ Attributes** again and combine multiple attributes using **AND**/**OR** for each event. For example, use the **OR** filter to combine data across two platforms. If you want to get data for a specific platform and look at the visits to a specific website, use the **AND** filter.

You can add multiple first events and return events using the **OR** function if you want to perform the retention analysis for multiple events. Events that you combine with **OR** still count as a single first event or return event, so they do not count as additional events.

# Step 2: Filter Users
By default, you can perform behavior analysis on all users. However, you can also query for a group of users filtered using **User property**, **User behavior**, **User affinity**, or **Custom segments**. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
To compare results across segments instead, use Compare Mode. You can select a maximum of five segments. Segment comparison and time comparison are mutually exclusive, so you can use only one of them in a single analysis. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 3: Retention Options
## Retention Type
After defining your events, you can choose how to calculate the data. The following options are available:

* **Unbounded**: Unbounded retention provides the percentage of users who were retained until the selected day or later. This metric includes users who performed the return event on or after that day. Here, the user is marked retained on all days until the user performs the return event for the last time. For a higher level of granularity, choose hour, week, or month instead of day.\
For example, the user installed the app (first event) in Week 0. The user opened the app (return event) on Day 0, Day 1, and Day 3 but did not open the app on Day 2. The user is counted as retained for Day 0, Day 1, Day 2, and Day 3. The user will be counted as retained for Day 2 as the user was active on the platform for the later period on Day 3.

* **N-Day**: N-Day retention provides the percentage of users retained on the selected day. It also includes the users who performed the return event on the selected day. For a higher level of granularity, choose hour, week, or month instead of day.\
For example, the user installed the app (first event) on Day 0. The user opened the app (return event) at least once on Day 0, Day 2, and Day 4 but did not open the app anytime on Day 1 and Day 3. The user will be counted as retained only for Day 0, Day 2, and Day 4. The user will not be counted as retained for Day 1 and Day 3 because the user was not active on these days.


> [!NOTE]
>
> In the case of **N-Day retention**, a strict order for the first event and the return event is not required. A user will be counted as retained if they perform the return event either before or after the first event. Additionally, if a return event occurs before the first event within the selected granularity (day, week, or month), the user will still be counted as retained for the Nth day.
>
> However, for **Unbounded retention**, a user is counted as retained only if the first event occurs before the return event. Therefore, if a user performs the return event before the first event, they will not be counted as retained under Unbounded retention metrics.
For information on the advanced retention type, refer to [Advanced](/docs/user-guide/analyze/analytics/retention/advanced-retention-analysis).
## Split By
With **Split by**, you can compare the data using a specific attribute. Add the desired attributes from the list with which you wish to compare. You can add a maximum of ten attributes.

## Duration
By default, retention analysis is performed for seven days. You can select your desired duration from the **Duration** list.

# Step 4: Chart
The visualization type for retention analysis is a line chart. The chart is created as a weighted average of the percentage of retained users for the selected day or selected granularity. This calculation applies to all retention types.

### Granularity
You can break down the chart into **Hourly**, **Daily**, **Weekly**, or **Monthly** granularities for easy visualization. The retention users are displayed based on the selected granularity.
Each granularity supports a different maximum duration:
| Granularity | Maximum duration |
| - | - |
| Hourly | 1 day (24 hours) |
| Daily | 90 days |
| Weekly | 180 days |
| Monthly | No limit |
### Compare to Past
The *Compare Mode* enables you to compare your analyses with data from a specific time period. Rather than performing separate analyses for each insight, this mode allows you to utilize a single analysis to gain insights from multiple perspectives. Click **Compare to Past** at the top of your chart and select the duration you wish to compare to. You can also select a custom date range starting with or ending with to do a custom comparison equal to the baseline duration. You cannot use time comparison and segment comparison together, so remove any additional comparison segments before you compare to the past. For more information, refer [here](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 5: Tables
Along with the chart, the data is available in a tabular format.
The **Users** column shows the number of users who performed the first event on a specific day. The **Day 0**, **Day 1**,...**Day n** columns provide the percentage of users according to *Unbounded Retention*, *N-Day Retention*, and *First Occurrence*.

The day granularity can be replaced with any granularity, such as hours, weeks, or months. The percentage numbers are color-graded for a better holistic view.
### Transpose Table
You can transpose the table. This allows you to view and download the table in your preferred format by shifting its vertical and horizontal orientation.

### Download
After viewing the information, you can download the chart or table. The charts are downloaded in PNG format, and the table is exported in CSV format.
# Save to My Studio or Custom Dashboard
Your analysis is now ready. To access it later, you can save the analysis.
To save:
1. Click the icon in the upper-right corner and click **Save to My Studio.**
2. Additionally, you can save the analysis to a custom dashboard. Choose the required option from the list.

3. Select the dashboard where you want to save the analysis. You can choose an existing dashboard or create a new one.

4. Enter a name for your analysis to help you identify.
5. Enter a brief description of the analysis.
6. Click **Save**.
You can access the analysis by navigating to **Analyze** > **My Studio**. To access the custom dashboard, navigate to **Dashboards**.
# Next Steps
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [Session and Source](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview)
# Retention - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/retention/retention-overview
Measure user loyalty with MoEngage Retention Analysis — track cohort-based return rates, visualize trends, and download detailed reports.

**Retention Analytics**
E-Learning Course
[Open](https://academy.moengage.com/student/activity/3355145-retention-analytics)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Retention in MoEngage Analytics provides insights into user retention, a critical aspect for assessing users' loyalty and measuring your product's recurring user base.
Retention charts provide graphical representations for various cohorts, enabling intuitive understanding. Additionally, tabular reports are available for download to allow for detailed analysis. These comprehensive reports will help you assess retention trends across different cohorts over time.
A cohort is a group of users who share similar behaviors. In the context of web and app analytics, a cohort refers to users who have completed the same events within a specific time frame. For example, a cohort might consist of new users on a music streaming app who actively listen to music for 15 consecutive days.
# Use Cases
Retention helps you answer questions such as:
* How many users are using my platform after signing up?
* What percentage of users visited a particular product on the e-commerce app, returned to the app, and bought the product?
* How many users who abandoned a cart were targeted with a reminder campaign and then returned to complete a purchase within the next three days?
* What is the quality of users of paid channels compared to others?
* In a gaming app, what is the retention rate (returning to play the next day) for users who reached Level 5 compared to those who only reached Level 1?
# Getting Started
[YouTube video player](https://www.youtube.com/embed/MtDHOD-wDMQ)
# Next Steps
* [Analysis](/docs/user-guide/analyze/analytics/retention/retention-analysis)
# Advanced Session and Source Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/session-and-source/advanced-session-and-source-analysis
Evaluate traffic quality by source with advanced session metrics — average sessions per user, bounce rate, conversion tracking, and revenue.
# Advanced Session and Source Options
Beyond just tracking traffic volume from various sources, it's crucial to assess the quality of that traffic. The advanced Session and Source options provide metrics to help you evaluate how users from different sources engage with your platform, how effectively their sessions lead to conversions, and their contribution to revenue.
* **Average sessions/user**: Average sessions per user gives you the mean number of times a single user visits a website or app within a given period across the selected source properties. It is determined by dividing the total session count by the number of unique users. This report type helps you analyze user loyalty and engagement frequency.
* **Average conversions/session**: Average conversions per session provides information on the efficiency of your website or app in achieving desired actions. It is calculated by dividing the total number of conversions by the total number of sessions across the selected source properties. This metric reveals how effectively each user visit contributes to your conversion goals.
* **Revenue**: Revenue report shows the total revenue for the selected source properties. For the Revenue report calculation, MoEngage takes Conversion activity/event and Revenue attribute present in the MoEngage dashboard in **Settings** > **Account** > **General settings**.
# When to Use Advanced Session and Source Options
While standard source analysis often focuses on the volume of traffic from different channels (for example, "How many users came from Facebook?"), the **Advanced Session and Source Options** allow you to delve deeper into the *quality* and *effectiveness* of that traffic.
Use these advanced features when your analysis requires understanding:
* **Engagement Levels by Source:** You need to know how frequently users acquired from different sources return and engage with your platform.
* **Conversion Efficiency by Source:** You want to measure how effectively sessions originating from specific sources lead to desired conversion events.
* **Revenue Contribution by Source:** You need to attribute monetary value directly to your acquisition channels or campaigns to understand their financial impact.
Here’s how each specific option helps evaluate the quality of your traffic sources:
## Average Sessions/User
* **What it does:** Calculates the mean number of sessions per unique user within a specific period, segmented by source properties (like source, medium, campaign). It essentially measures repeat visit frequency based on origin.
* **When to use it:**
* When you need to compare user loyalty and engagement frequency across different acquisition channels or campaigns.
* To identify sources that drive more habitual usage or repeat visits versus those driving primarily one-off visits.
* To assess the "stickiness" of users acquired from various sources.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Channel Loyalty:** Compare the average sessions per user for traffic acquired via *Organic Search* versus *Paid Social Media* over a month to see which channel brings back users more often.
* **Campaign Engagement:** Analyze if users acquired through *Email Campaign A* have a higher average session count than those from *Email Campaign B*.
* **Referral Quality:** Evaluate different referral partners by comparing the average sessions per user for traffic originating from each partner.
## Average Conversions/Session
* **What it does:** Measures the efficiency of sessions by calculating the total number of specified conversion events divided by the total number of sessions, segmented by source properties. It shows how likely a session from a particular source is to result in a conversion.
* **When to use it:**
* When you need to evaluate how effectively different traffic sources convert visitors within their sessions.
* To identify high-intent sources that drive efficient conversions versus sources that generate volume but low conversion rates per session.
* To optimize marketing spend towards channels delivering sessions that are more likely to convert.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Campaign Efficiency:** Compare the *Average Purchases per Session* for users coming from *Google Ads Campaign X* vs. *Google Ads Campaign Y*.
* **Content Marketing ROI:** Assess if sessions originating from specific blog posts (tracked via UTM parameters) have a higher *Average Newsletter Signups per Session*.
* **Channel Performance:** Determine which source (for example, *Direct*, *Organic Search*, *Referral*) yields the highest *Average Demo Requests per Session*.
## Revenue
* **What it does:** Reports the total revenue generated, attributed to specific source properties.
* **When to use it:**
* When you need to directly measure the monetary value driven by different acquisition channels, campaigns, or sources.
* To calculate Return on Investment (ROI) for marketing activities.
* To make budget allocation decisions based on the revenue contribution of various sources.
### Example Use Cases
Some of the use cases that you can solve using this option:
* **Marketing ROI:** Track the total revenue generated from users whose first touchpoint was *Paid Search Campaign Z* to evaluate its profitability.
* **Channel Value:** Compare the total revenue attributed to users acquired via *Affiliate Marketing* versus *Email Marketing* over a quarter.
* **Content Contribution:** If tracking revenue events, determine the revenue generated by users who initially landed on a specific product marketing page (using source tracking).
By utilizing these options, you can move beyond simple traffic counts to assess the true quality, engagement, efficiency, and financial contribution of your various acquisition channels and campaigns.
# Next Steps
* [Dashboards](/docs/user-guide/analyze/dashboards)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# Session and Source Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/session-and-source/session-and-source-analysis
Configure Session and Source Analysis in MoEngage — select report types, choose source properties, apply filters, and analyze your traffic.
# Step 1: Select Report Type
The first step involves selecting the type of report you want to generate. You have the following options.

* **Session count**: Session count represents the total number of sessions within a specified timeframe. Each session tracks a user's interaction, starting when they arrive and ending after a period of inactivity. This is measured across the selected source properties, such as *Source* or *Medium*. You will learn about the source properties later in this article. For example, you can use this analysis to measure the adoption of a feature.
* **Average session duration**: Average session duration is the total time users spend across the source properties, divided by the number of sessions. It measures user engagement, indicating how long visitors interact with your website or features. Higher average durations often suggest more engaging experiences.
* **Conversion count**: Conversion count gives the total number of desired actions completed by users on a website or app across the selected source properties. For conversion report calculation, MoEngage takes the conversion activity/event present in the MoEngage Dashboard in **Settings** > **Account** > **General settings**. It directly measures the success of your conversion strategy.
* **Bounce rate**: All sessions with a duration of less than 10 seconds are defined as Bounced Sessions. Bounce rate is the percentage of bounced sessions relative to the total number of sessions. This report is available across the selected source properties. A high bounce rate indicates that visitors aren't finding what they expect or aren't engaging with the content.
For more information on advanced Session and Source types, refer to [Advanced](/docs/user-guide/analyze/analytics/session-and-source/advanced-session-and-source-analysis).
After selecting the report type, you can apply filters by clicking **Add Filters**. You can filter reports based on one source property. For example, filter reports on a medium like an email.

# Step 2: Filter Users
By default, you can perform this analysis on all users. However, you can also query for a group of users filtered using **User property**, **User activity**, **User affinity**, or **Custom segments**. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).
To compare results across segments instead, use Compare Mode. You can select a maximum of five segments. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).

# Step 3: Choose the Source Property and Duration
All reports are analyzed based on the source properties. Select a maximum of two properties for the analysis. By default, reports are not split by any property. For more information on source properties, refer [here](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview).
After selecting the properties, specify the duration for your analysis and click **APPLY**.

# Step 4: Charts
After your query is generated, choose your preferred visualization type. By default, the report is shown in a Line chart, sorted by the highest count. You can change between **Line**, **Area**, **Bar**, **Column**, and **Pie** charts. Every chart has its own significance.
* Line charts are widely used for analyzing data trends, changes, or patterns. They are frequently used to display and compare data over time.

* Area charts combine a line chart and a bar chart to show how data changes over time. They show how one or more groups' numeric values change over time. They are often used to show trends in data.

* A bar or column chart is a graph used to compare different measures across various data categories or series.
> [tab] Bar Chart
>
> 
> [tab] Column Chart
>
> 
* Pie charts are commonly used to visualize categorical data that can be divided into distinct parts. They display the relative proportions or contributions of various categories within a whole.

Line, area, column, and bar charts are scaled relative to percentages using an absolute number or a percentage. You can switch between numerical and percentage views for line, area, bar, and column charts.

### Granularity
You can also break down the report into Hourly, Daily, Weekly, or Monthly granularities for easy visualization. Based on the granularity you select, unique users will be displayed. Hourly granularity is available for date ranges of up to 31 days.


### Compare to Past
This will allow you to compare the current chart with past trends. You can compare any data point over a period of time with the corresponding data point from the previous period.

You can compare the chart for the following periods:
* Previous Day
* Previous Week
* Previous Month
* Previous Quarter
* Previous Year
* Custom Range
Time comparison is available only on line, bar, and column charts. You cannot use time comparison and segment comparison together. Segment comparison starts when you add a second segment, so keep a single segment if you want to compare to the past. For more information, refer to [Compare Mode in Analytics](/docs/user-guide/analyze/analytics/compare-mode-in-analytics).
### Sorting
When viewing a bar and column chart, you have the following options to sort the charts:
* Descending (High to low)
* Ascending (Low to high)
* Alphabetical (A to Z)
* Reverse Alphabetical (Z to A)
* Sort by date (Chronological sort)

# Step 5: Tables
In addition to charts, the data is also available for analysis in a tabular format. You can sort the table or change its view using the transpose feature. Additionally, you can download the data in CSV format. For more information, refer [here](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview).
When your analysis has a source property selected, you can turn on **Pivot mode** in the table header to see sessions by source property and date side by side. For more information, see [Pivot Tables](/docs/user-guide/analyze/analytics/getting-started-with-analytics/overview#pivot-tables).
# Save to My Studio or Custom Dashboard
Your analysis is now ready. To access this later, you can save the analysis.
To save:
1. Click the icon in the upper-right corner and click **Save to My Studio.**
2. Additionally, you can save the analysis to a custom dashboard. Choose the required option from the list.

3. Select the dashboard where you want to save the analysis. You can choose an existing dashboard or create a new one.

4. Enter a name for your analysis to help you identify.
5. Enter a brief description of the analysis.
6. Click **Save**.
You can access the analysis by navigating to **Analyze** > **My Studio**. To access the custom dashboard, navigate to **Dashboards**.
# Next Steps
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [Advanced](/docs/user-guide/analyze/analytics/session-and-source/advanced-session-and-source-analysis)
* [User Paths](/docs/user-guide/analyze/analytics/user-paths)
# Session and Source - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview
Learn how MoEngage tracks user sessions and traffic sources across web and mobile apps, including session definitions and source attribution.

**Session and Source**
E-Learning Course
[Open](https://academy.moengage.com/student/activity/3355151-session-and-source)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Session
Session Analysis helps you understand how users interact with your web and mobile apps, enabling you to improve your product and design. By analyzing sessions, you can see the quality of user experiences on your app and website.
## What Is a Session?
A session represents a user's series of interactions on your website or app within a specific timeframe. These sessions are primarily tracked by recording the events and activities users perform on their devices.
Sessions are specific to individual devices. User activity or events that occur on the server side are not included within a session.
## How Is It Calculated?
A session begins with the first event or activity a user performs on a device. The timestamp of this initial action marks the session's start time.
A session ends under the following circumstances:
* **Logout**: The user logs out of the application.
* **Source change**: The user enters the session from a different traffic source while the current session is active. All sessions are associated with source information. This source data, derived from UTM parameters, includes properties such as the traffic source, medium, and campaign. The source can be organic or paid. A source is considered different only if one or more of its properties are not identical to the existing session's source properties.
* **Inactivity**: The user remains inactive for longer than the specified inactivity period (default: 30 minutes).
Each session has a defined start and end time. All events and activities performed between these times are considered part of that session. Session duration is calculated as the difference between the session's start and end times.
### Interaction vs. Non-Interaction Events
User events within a session are considered interactive when they:
* Start a new session, even if the app or website is in the background.
* Extend the current session, even if the app or website is in the background.
* Contain source and session information.
Events required for internal use or technical purposes, or not directly generated by user actions, are considered non-interaction events. These events do not affect session calculations and:
* Do not start a new session, even when the app/site is in the foreground.
* Do not extend the session.
* Do not contain source and session information.
For example, the *Notification Received* event is a non-interaction event. It does not increase session time and is not counted as a session event.
For more information on specifying non-interactive events, refer to the MoEngage developer documentation: [Android SDK](/docs/developer-guide/android-sdk/data-tracking/basic/track-events), [iOS SDK,](/docs/developer-guide/ios-sdk/data-tracking/advanced/session-and-source-tracking) and [Web SDK](/docs/developer-guide/web-sdk/data-tracking/web-sdk-events-tracking).
UTM parameter is mandatory for session analysis. For more information, refer to [Source Analysis](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-overview#utm-parameters).
# Source
User source is a key element in measuring the ROI of marketing efforts. By analyzing sources, you can evaluate traffic quality and engagement to identify the most effective sources, mediums, and campaigns.
## Source Properties
### UTM Parameters
UTM parameters are used to analyze the performance of different traffic sources. By default, the MoEngage SDK automatically captures UTM parameters from the URL for web traffic and from deep links for mobile apps.
MoEngage supports the following UTM parameters:
* **utm_source**: Identifies the source of the traffic, such as a specific website, app, or link. (Examples: YouTube, Instagram, Google)
* **utm_medium**: Identifies the type of channel used. (Examples: push notification, banner ad, email)
* **utm_campaign**: Identifies the name of a specific marketing campaign. (Examples: Newyear, Bigbillionday)
* **utm_term**: Identifies the search terms used for paid advertising traffic. (Example: Mobile+sale)
* **utm_content**: Identifies the specific content used within an ad or campaign. (Examples: banner, video, product image)
In the following URL, *utm_source* and *utm_medium* are the parameter names, and *MoEngage* and *email* are their respective values:
[*https://www.testdomain.com/?utm_source=MoEngage\&utm_medium=email\&utm_campaign=Newyear \&utm_term=mobile+sale\&utm_content=image*](https://www.testdomain.com/?utm_source=MoEngage\&utm_medium=email\&utm_campaign=Newyear)
### User-Defined Parameters
> [!TIP]
>
> To utilize Source Analysis effectively, UTM parameters or custom user-defined parameters are required. Without these, information about the source, campaign, medium, content, term, and any custom user-defined parameters will be unavailable. Ensure that all marketing links, referral links, and key-value pairs include UTM or custom parameter information. To enable user-defined parameters, contact the MoEngage support team.
Many marketers use custom source parameters that are specific to their business needs. MoEngage also supports these custom parameters. In addition to the standard UTM parameters, you can define up to five custom parameters for your apps and websites. The MoEngage SDKs will recognize these new parameters in the URL as source properties and automatically include them with all events.
In push notifications, if a deep link is absent or does not contain source information, the SDKs will search for source properties within the key-value pairs.
### Attribution
MoEngage employs a last-click attribution model. This means all user activity and events are attributed to the source of the user's most recent click. The session duration defines the attribution window.
For example, if a user arrives via Google Ads, remains active for a session lasting five minutes, and triggers 15 events, the source property value for all 15 events will be *Google Ads*. If, during the next session, the user arrives organically, the events in that session will not have any source information attributed to them.
# Use Cases
As a marketer or a product owner, you can answer the following questions with Session and Source Analysis:
* How do total session counts and the number of sessions per user trend over time?
* What is the typical depth of a user session in terms of total events and unique event types triggered?
* How many sessions include a specific conversion event (for example, purchase and signup)
* What is the average time elapsed between consecutive sessions for a given user?
* How do user activity and key event occurrences differ based on the source, campaign, or medium through which the user arrived?
* What is the performance of traffic sources?
* Which MoEngage campaign types are driving the best outcomes, engagement, and retention?
* How much conversion and revenue is driven from traffic sources?
* How well is a particular channel performing?
# Getting Started
[YouTube video player](https://www.youtube.com/embed/4qvGXUSnIaU)
# Next Steps
* [Analysis](/docs/user-guide/analyze/analytics/session-and-source/session-and-source-analysis)
# Uninstall
Source: https://moengage.com/docs/user-guide/analyze/analytics/uninstall
Visualize app and website uninstall trends in MoEngage — compare device-level uninstall events against unique user-level uninstall counts.

**Uninstall Analytics**
E-Learning Course
[Open](https://academy.moengage.com/student/activity/3387985-uninstall-analytics)
Uninstalls analytics visualizes the uninstalls event or users who uninstall the app or website.
To view the uninstalls analytics, navigate to MoEngage Dashboard > Analyze > Uninstalls

Two types of uninstall analytics are enabled:
**Uninstall Events**: Focuses on the device uninstall events.
**User Uninstalls**: Focuses on unique users who uninstalled the app.

Ensure that you have configured the Uninstall Settings for your app for the uninstall analytics to be available. For more information, refer to [Uninstall Settings](/docs/user-guide/settings/analytics-and-segmentation/uninstall-tracking).
# User Uninstalls and Uninstall Events Difference
The User Uninstalls provide the number of unique users who uninstalled the app. If a user has the app on multiple devices, then the user is counted in User Uninstalls only when the user uninstalls the app from all the devices. As the analytics is at the user level, the filter on user properties like city, country, number of sessions, and so on is possible.
Uninstall Events provides the number of times the app is uninstalled. If a user uninstalls, re-installs, and uninstalls the app again, both the uninstall actions are displayed in the Uninstall Events tab. As the analytics is based on user actions on a device, the filter on device attributes like OS version, device model, and so on is possible.
# User Uninstalls
User Uninstalls analytics provides deeper insights into which users are uninstalling your app with day-level accuracy.
Two types of user uninstall visualization are available:
* User Uninstalls By Time
* User Uninstalls By Attribute
You can filter these statistics by:
**Platform Type**

**Date Range**
You can select a maximum of 60-day period at a time.

**Export the chart data**
Export the chart data in various format including CSV, PDF, and image files.

## User Uninstalls By Time
User uninstalls by time provide day-level accuracy such as:
* You can view daily, weekly, or monthly uninstalls for a time range and platform.
* The chart also shows total uninstalls for a set time.

## User Uninstalls By Attribute
User uninstalls by attributes provide analytics for various ranges or categories by a user property grouped together.
* Group uninstalls by any **string, numeric, or boolean type user property**.
* The Sum of all uninstalls displayed in the chart is also shown at the top.
* For **string attributes**, by default, the graph displays at most top 10 attribute values by uninstall count.
* For example, the top 10 Last Known Cities are displayed by uninstall count
* If you wish to see uninstalls for any other value, **enter the Attribute values in the input box** and click **APPLY**.

* For **numeric attributes**, the graph displays uninstalls for various ranges of attribute values.
* For example, for No. of Sessions, by default you will see uninstalls grouped into ranges 1-1, 2-5, 6-10 11-50, and 51-199.
* If you wish to modify these ranges, **move the knobs on the slider to the required position** and click on “APPLY”.
* You can also modify the upper limit of the slider. Minimum value for the upper limit is 10.

> [!NOTE]
>
> Uninstall counts are based on the most recent data available. It is possible that past uninstall figures changed due to below listed reasons -
>
> * Users uninstall and reinstall the app
> * User merging or user deletion
# Uninstall Events
Two types of uninstall events visualization for devices are available:
* Uninstall Events By Time
* Uninstall Events By Attribute
## Uninstall Events By Time

## Uninstall Events by Attribute

The graphs provide:
1. Filtered based on the platform and date range (up to the **last 60 days**)
2. Downloaded in CSV, jpeg, png, pdf, SVG vector image formats.
3. Display the **sum of all uninstalls** at the top.
4. Support **customizable ranges and modification of upper limit** for numeric attributes.
5. Have a **minimum upper limit of 10** for numeric attributes.
6. Display **top 10 attribute values** by uninstalling events count.
In Lifetime Activity, you find attributes like Days since last active and Days till last active.
* **Days since last active** helps you visualize device uninstall data according to the number of days between uninstall time of the user on that device and the last active time of the user
* **Days till last active** helps you to visualize device uninstall data according to the number of days between the last active time of the user and when the user was detected first on the MoEngage platform using that device (User created time in MoEngage)
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# User Data Exports
Source: https://moengage.com/docs/user-guide/analyze/analytics/user-data-exports
Export filtered user properties like email IDs and phone numbers from MoEngage segments to run re-engagement campaigns on external channels.
On the MoEngage dashboard, you can export user properties. You can filter the desired user segment and export user properties.
For example:
* Export the Email ID of users, who were engaged but uninstalled, and run re-engagement campaigns on Facebook.
* Export phone numbers of inactive users and send them an SMS to reactivate them.
## Run Export
1. Navigate to the MoEngage Dashboard and select **Segment** > **Create segment** from the left navigation. The Create segment page is displayed.
2. Build and run a query for the segment you wish to export. The query is displayed in the Query Results section.

3. In the **Query Results** section, click a specific query and then click **Export users**.

The Export users data pop-up window is displayed. Your Email ID is preselected.

4. In the **File name** field, enter a file name.
5. From the **User property** drop-down list, select the user properties you wish to extract.
6. Click **Export**.
> [!NOTE]
>
> * Date and time attributes in the exported file are always provided in UTC, regardless of your dashboard timezone.
> * The export of Personally Identifiable Information (PII) marked user properties is restricted on the MoEngage dashboard. [Know more](/docs/user-guide/data/privacy/personal-data-or-personally-identifiable-information-pii/pii-masking).
> * User data exports fair usage limits:\
> The number of data points (number of rows x number of columns) that can be exported is a maximum of 20 million, beyond which the export has a high chance of failure. For example, exports could be:
> * 20 million rows with 1 column or
> * 4 million rows with 5 columns or
> * 1 million rows with 20 columns\
> To change these limits, contact your CSM.
## Export Security
User export is a private export service. Users with access to the MoEngage dashboard can access the export file, provided the user is logged in to the designated account. The export is not available to users who are not logged in to the MoEngage dashboard or the designated account.
User export email and link to download the file is sent only to the email address of the user generating the export. Other dashboard users can access this file from the MoEngage dashboard on the Data Export page in the User Export tab.
# User Path Analysis
Source: https://moengage.com/docs/user-guide/analyze/analytics/user-paths/user-path-analysis
Analyze forward and reverse user paths in MoEngage to see how users navigate before and after key events on your website or mobile app.
# Step 1: Choose Event
An event refers to any action that a user completes on your website or app that is tracked. It’s important to understand how users navigate after completing their first event and to know the path they take to reach a specific event. You have two options to analyze:
* **Forward user paths**: This option displays all user paths that begin with the selected event. To use this feature, select the **Path type** as *Starting with* and select the desired **Event**. For example, you can analyze the user paths that start with the event *App/Site Opened*.
* **Reverse user paths**: This option shows all user paths that lead up to the selected event. To use this feature, select the **Path type** as *Ending with* and select the desired **Event**\*.\* For example, you can analyze the user paths that end with the event *Checkout Completed*.

The event can be further filtered. To do so, click **+ Attributes** and select event properties for specific user actions, such as *Platform*, *App Version*, and so on.

Click **+ Attributes** again and combine multiple attributes using **AND**/**OR** for each event. For example, use the **OR** filter to combine data across two platforms. If you want to get data for a specific platform and look at the visits to a specific website, use the **AND** filter.

# Step 2: Filter Users
By default, you can obtain the user paths for all users. However, you can also query for a group of users filtered using **User property**, **User activity**, **User affinity**, or **Custom segments**. Filtering users is similar to creating a segment. For more information, refer to [Create Segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments).

# Step 3: User Paths Options

### User Path Window
Select the desired time window to analyze user paths within a specific duration. This option considers the events that occur within the specified time after the starting event or before the ending event.
The window is set to four hours by default. You can choose units of *Days*, *Hours*, or *Minutes*.
For example, to analyze user paths that occur after the *App/Site Opened* event within a span of 10 hours, you can set the user path window accordingly.
### User Path Steps
By default, the user paths chart shows the first five steps taken by the users after the selected event. For some user events, you might want to analyze the path for a specific number of steps. You can have up to 15 steps in user paths.
For example, analyze the first three actions of the user after they receive a push notification by setting the **User path steps** to three.
### Date Range
After defining the user path window and user path steps, select the time frame for which you want to perform the user path analysis. You can choose from:

* Today
* Yesterday
* This Month
* Last Month
* Since
* Before
* Custom range
By default, the date range selected is *Yesterday*. User paths cannot be analyzed for more than 30 days at a time. After selecting the date range, click **APPLY**. Your chart is now generated.
# Step 4: Chart
User paths are illustrated using a Sankey Chart analysis, which displays paths and steps flowing from left to right. Each **Node** represents a specific event, while a vertical arrangement of nodes signifies a step. The area or cord connecting two nodes indicates the path taken.

You can analyze user paths by examining consecutive nodes and paths. The forward user path begins at an event and then branches out into multiple paths taken by different users following that initial event. In contrast, reverse user paths involve the merging of different paths into one event.
## Chart for the Forward User Paths
When you hover over a node, the total number of users for that event is shown, as well as a percentage. You can also see the percentage of users who went to the next step and the percentage of users who did nothing after the current step and dropped off. In this scenario, the end nodes do not display any information about the drop-off or the next step because no information is available.
**Drop off node**: A dedicated node showing the total number of users who dropped off after the previous step, shown as a percentage of the total users at the starting node.
**Paths** represent the number of times users went from one node to another, along with the origin and destination node names, and the percentage for the origin node.

## Chart for Reverse User Paths
When you hover over a node, you see the total number of users at that event, along with a percentage relative to the total users who reached the final (anchor) event you selected. For each node, you can also see:
* **From previous step**: The percentage of users who reached this node by completing a tracked event at the step before it.
* **Entry**: The percentage of users who reached this node with no tracked event before it in the path window. These users enter the path directly at this step.
The leftmost (start) nodes have no earlier step to reference, so they don't show a "from previous step" percentage. Every user at a start node counts as an entry.
**Entry node**: A dedicated node showing the total number of users who entered the path at that step, meaning no prior event was tracked for them within the user path window. This is shown as a percentage of the total users who reached the next event. It's the reverse-path equivalent of the Drop off node in forward paths: Drop off counts users exiting a path early, Entry counts users joining a path partway through without an earlier tracked step.
**Paths** represent the number of users who moved from one node to another, along with the origin and destination node names, and that count as a percentage of the origin node's total.

## Chart Settings

### Repeated Events
Repeated events are a series of the same events performed multiple times by users in succession. Click **Hide** to merge the sequence into one event, and click **Show** to view the entire sequence.
### Exclude Events
To hide certain events from appearing in your User Paths chart, select the desired events from the **Excluded events** list and click **Apply Filters**.
Alternatively, you can add the events to be excluded directly to the chart. To do so, perform the following steps:
1. On the user paths chart, click a desired node. The Perform action dialog box appears.
2. Under **Actions**, select **Exclude this event**.
3. Click **Apply**.
### Resolution
Resolution sets a minimum percentage threshold for a node to appear on its own in the chart. At any given step, events that fall below the threshold are grouped into a single node labeled **Others** instead of appearing individually. Raise the resolution to simplify the chart to major paths only; lower it to see more detail.
### Split By
Split By breaks a node into separate branches based on an event or user property you choose. For example, splitting the *App Opened* event by *Platform* creates separate branches for iOS and Android. When applied to an event, every node where that event appears is split by the selected attribute.
> [!NOTE]
>
> You can select a maximum of five split by attributes for any step.

Alternatively, you can add the split by attributes directly on the nodes. To do so, perform the following steps:
1. On the user paths chart, click a desired node. The Perform action dialog box appears.
2. Under **Actions**, select **Split by**.
3. From the **Select attributes** list, select the desired split by attributes. You can split an event by up to five attributes.
4. Click **Apply**.

### Zoom Chart
While analyzing user paths with a higher number of steps, you can use the **Zoom chart** functionality to zoom in on a specific step or node and view the details clearly. Similarly, zoom out shall zoom out the chart, and reset zoom shall reset the zoom level of the chart.
### Add and Remove Steps
Apart from the Zoom functionality, you can click **Add Step** or **Remove Step** to control the number of visible steps in the chart. These buttons are available on the right side of the chart in the forward user path and the left side of the chart in the reverse user path.

## Why Results Can Vary Between Runs
Running the same User Path analysis twice — same events, path window, steps, and date range — can return slightly different numbers each time.
This happens when a user has multiple events ingested with an identical timestamp. MoEngage Analytics reads event data from the warehouse as it was ingested, and events that share the same timestamp have no deterministic relative order. The path computation can resolve that order differently on each run.
This is expected behavior rather than a defect or a sign of missing data. The variance comes from the event data itself, not from the analysis.
To reduce it, space out the timestamps of events that your app or server sends in quick succession, so that each event carries a distinct time. For how same-timestamp events are drawn on the chart, refer to [What causes unexpected event sequences in user paths?](/docs/user-guide/analyze/faqs-analyze/what-causes-unexpected-event-sequences-in-user-paths).
## Download
After you view the chart, you might need to share it with your team. Click **Download Chart** in the upper-right corner to download it. The chart will be saved in PNG format.

# Save to My Studio
Your analysis is now ready. To access this later, you can save the analysis.
Perform the following steps to save your analysis:
1. Click the icon in the upper-right corner.
2. Click **Save to My Studio.**
3. Enter a name and description for your analysis.
4. Click **Save**.

You can access the analysis by navigating to **Analyze** > **My Studio**.
# Next Steps
* [MoEngage Dashboards](/docs/user-guide/analyze/dashboards/overview)
* [My Studio](/docs/user-guide/analyze/dashboards/my-studio)
# User Paths - Overview
Source: https://moengage.com/docs/user-guide/analyze/analytics/user-paths/user-paths-overview
Visualize user navigation patterns with MoEngage User Paths — discover popular routes, identify bottlenecks, and reduce journey friction.

**User Paths**
E-Learning Course
[Open](https://academy.moengage.com/student/activity/3355148-user-paths)
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
User Paths visualize user interaction and navigation within websites and apps by analyzing event trails. This analysis focuses on events performed before or after a specific target event, revealing user behavior patterns. You can identify popular navigation routes and pinpoint potential bottlenecks or friction points in the user experience. These paths consist of event sequences originating from or converging on a desired event within a defined time frame.
# Use Cases
As a marketer or product owner, you can answer the following questions with User Paths:
* What are my users doing right after installing or opening the app?
* What do users do right before making a purchase or uninstalling the app?
* What paths do users follow between clicking a notification and completing a purchase?
* How can we analyze and optimize the user onboarding journeys?
# Getting Started
[YouTube video player](https://www.youtube.com/embed/-rAkQN8SvF4)
# Next Steps
* [Analysis](/docs/user-guide/analyze/analytics/user-paths/user-path-analysis)
# Open Analytics
Source: https://moengage.com/docs/user-guide/analyze/custom-analysis/open-analytics
Query your MoEngage data warehouse directly with Open Analytics — run SQL queries, build visualizations, and export data via API or console.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Growth teams need to perform a lot of data analysis for their daily operations. For this analysis, they need the correct data access at the right time. MoEngage Open Analytics enables growth teams to access the latest data on the MoEngage platform in real time directly from the data storage. MoEngage allows customers to directly query the data warehouse and get desired data.
## Capabilities of Open Analytics
MoEngage open analytics can help with -
1. Read and Query data using SQL queries through a console or Programmatically via API
2. Visualize the data on the Open Analytics console through in-build visualization methods available
> [!NOTE]
>
> MoEngage open analytics is not suitable for data exports. For data export, please use [MoEngage Streams](https://www.moengage.com/docs/api/data/moengage-streams) or [S3 exports](/docs/user-guide/data/exports/events/data-warehouse/s3-exports).
## Enable Open Analytics
MoEngage requires 2 sets of information to enable open analytics -
1. Email ids of users
2. The static IP address. (This can be your VPN IP as well. Make sure you provide the static IP, IPs provided by your network provider will not work)
> [!NOTE]
>
> **Access deactivation:** MoEngage deactivates Open Analytics access for users who have been inactive for 30 or more consecutive days. To restore access, contact your MoEngage Customer Success Manager (CSM) or the Support team.
## Data Categories
All data received at the MoEngage system can be categorized into 3 kinds –
1. Device data
2. User Data
3. Event data
The data is collected using the SDK and S2S events and processed and stored with events.
## Data Schema
MoEngage processes and stores all the device attributes and event properties in separate event tables for each event.
Table Name - account_name.event_name
| attribute 1 | attribute 2 | attribute 3 | -- | attribute n-1 | attribute n |
| - | - | - | - | - | - |
| ... | ... | ... | ... | ... | ... |
| ... | ... | ... | ... | ... | ... |
The time window for analysis can be selected using the attribute - **day.** This partition time works for all tables. **Must always use this in your queries to limit the costs.**
For Example
```sql SQL theme={null}
SELECT server_time, COUNT(server_time) as metric
FROM
"account_name"."moe_app_opened_828"
WHERE
day >= '2022-01-01'
GROUP BY 1
ORDER BY 1
```
Event Tables can be joined using common keys/attributes such as - **user_id**
```sql SQL wrap theme={null}
SELECT user1
FROM
(SELECT user_id AS user1 FROM "account_name"."uptete_spa") table1
INNER JOIN
(SELECT user_id AS user2 FROM "account_name"."moe_user_merge") table2
ON table1.user1 = table2.user2
```
### Event & Attribute Naming Convention
Event names have structure as ‘EventName_XXX’, for example - moe_app_opened_828\
Event Property names have a structure as ‘Datatype_AttributeName_XXX’, for example - string_activity_name_880
### User Properties
User properties are stored in the user table, and the table refreshes one time every day.\
Table Name - **users_base_table** **Column for MoEngage generated User Id - user_id**
| attribute 1 | attribute 2 | attribute ... | attribute n |
| - | - | - | - |
| ... | ... | ... | ... |
| ... | ... | ... | ... |
## Important Attribute Information
(These attributes should be present in all of the events)
1. **day** - Time-window for analysis can be selected using this attribute\*\*.\*\* This partition time works for all tables. This should be considered as the date attribute for Tables.
2. **server_time** - UTC at which events reach MoEngage servers.
3. **user_id** - This is a MoEngage-generated User Id.
4. **string_uid_125** - This is the User Id generated by your App/Site.
5. **original_event_name** - Event Name
6. **user_time** - Event time in the local time zone
## Open analytics Usage Best Practices
1. Use **day** in your queries to optimize query performance. Otherwise, MoEngage will scan the entire table, and scanning costs will be higher.
2. MoEngage works on a columnar database, so you can use only the columns ( attributes ) you need for analysis. If unnecessary columns are used, cost increases, and query performance decreases.
3. To optimize queries, refer to [best practices](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/).
4. A general guide to writing Athena SQL queries -\
[https://docs.aws.amazon.com/athena/latest/ug/querying-athena-tables.html](https://docs.aws.amazon.com/athena/latest/ug/querying-athena-tables.html)
## Programmatic Access to Data
To read data using python or java code, Open Analytics makes APIs available to generate the report utilizing existing queries. For more information, refer to [using APIs](https://redash.io/help/user-guide/integrations-and-api/api).
## Sample Queries
1. [Key Metrics Queries](/docs/user-guide/analyze/analytics-how-to/key-metrics-queries-for-open-analytics)
2. [Reachability Queries](/docs/user-guide/analyze/analytics-how-to/reachability-queries-for-open-analytics)
For further assistance, please contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Best Time Analysis
Source: https://moengage.com/docs/user-guide/analyze/dashboards/best-time-analysis
Identify the best time to send campaigns per channel using hourly user activity data from the MoEngage Best Time Analysis dashboard.
This dashboard provides an analysis for each channel and showcases detailed hourly user activity over the past 24 hours. The charts help you identify the most preferred time slots for sending campaigns to your users rather than sending communications to all users at a fixed time.\
For each channel, you can find the best time slot to send a campaign to users to increase the chances of interaction or response.
 To know more, refer to [Best Time to Send](/docs/user-guide/ai-and-intelligence/timing/best-time-to-send).
# Campaign Metrics
Source: https://moengage.com/docs/user-guide/analyze/dashboards/campaign-metrics
Metric descriptions and formulas for every MoEngage channel, organized in tabs by channel.
> [tab] Email
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign and for whom MoEngage tried sending the message. | Count of users attempted |
> | Sent | Total emails sent to users. Excludes duplicate/invalid emails, bounces, unsubscribed or complained users, and emails dropped by Frequency Capping or Personalization failures. | Count of emails sent |
> | Sent Rate | Percentage of attempted sends that were sent. | (Sent / Attempted) × 100 |
> | Delivered | Total emails delivered, as reported by the delivery partner (e.g. SendGrid). | Count of emails delivered |
> | Delivery Rate | Percentage of sent emails that were delivered. Applies to campaigns sent via SendGrid. | (Delivered / Sent) × 100 |
> | Failed To Send | Users to whom the email was not sent. | Count of failed sends |
> | Failed Rate | Percentage of attempted sends that failed. | (Failed To Send / Attempted) × 100 |
> | Bounced | Emails that bounced due to incorrect addresses or mail-server rejection — includes both hard and soft bounces. Soft-bounced addresses are not quarantined and are retried on the next send. | Count of bounced emails |
> | Bounce Rate | Percentage of sent emails that bounced. | ((Hard Bounces + Soft Bounces) / Sent) × 100 |
> | Opened | Total times users opened the email, tracked via a 1px invisible tracking image. | Count of opens |
> | Open Rate | Percentage of delivered emails opened (unique). | (Unique Opens / Total Delivered) × 100 |
> | Adjusted Open Rate | Percentage of authentic users who have opened the delivered emails. | (Unique Adjusted Opens / Total Delivered) × 100 |
> | Clicked | Total clicks on any link in the email after delivery. | Count of clicks |
> | Click Through Rate (CTR) | Percentage of clicks received from the delivered emails. | (Total Clicks / Total Delivered) × 100 |
> | Adjusted Click Through Rate (Adj. CTR) | Percentage of authentic user clicks from the delivered emails, with bot-driven clicks (e.g. automated link-checking scanners) excluded. | (Unique Adjusted Clicks / Total Delivered) × 100 |
> | Click to Open Rate (CTOR) | Percentage of unique clicks to unique opens. | (Unique Clicks / Unique Opens) × 100 |
> | Adjusted CTOR | Percentage of unique adjusted clicks to unique adjusted opens, once bot-driven opens and clicks are filtered out. | (Unique Adjusted Clicks / Unique Adjusted Opens) × 100 |
> | Spam | Users who marked the email as spam. Excludes Gmail, which reports spam separately via Google Postmaster Tools. | Count of spam reports |
> | Complaint Rate | Percentage of delivered emails marked as spam. | (Total Complaints / Total Delivered) × 100 |
> | Unsubscribed | Users who clicked unsubscribe after receiving the email. Includes users unsubscribed directly at SendGrid even before MoEngage has that information. | Count of unsubscribes |
> | Unsubscribed Rate | Percentage of delivered emails that led to an unsubscribe. | (Total Unsubscribes / Delivered) × 100 |
> | Converted Users | Unique users who completed the primary conversion goal at least once within the attribution window. | Count of unique converted users |
> | Event (Primary) | Total number of primary conversion goal events within the attribution window. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of users who performed the conversion event, tracked as Unique. | View-through: (Unique conversions / Unique opens) × 100 · Click-through & In-session: (Unique conversions / Unique clicks) × 100 · Total conversion: (Unique conversions / Total delivered) × 100 |
> | Total Campaign Revenue | Sum of total order value across all conversion events attributed to the campaign. Tracked across all attribution types. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of conversion events |
> | Average Revenue Per User | Average revenue generated per unique converting user. | Total Campaign Revenue / Number of unique conversions |
>
> > [!NOTE]
> >
> > **Total vs. Unique**: Total Opens counts every pixel load (a user opening the same email 5 times adds 5), while Unique Opens counts distinct users within an 11-day window. Same distinction for clicks — Total Clicks counts every click on every link, Unique Clicks counts per user-per-link. Rate formulas above use Unique counts.
>
> > [!NOTE]
> >
> > Whether Open Rate/CTR/CTOR or their Adjusted counterparts are shown depends on the account's Bot Detection → Post detection actions setting (Settings > Channels > Bot Detection Settings). Either both are shown, or only the adjusted version is shown — never both hidden.
>
> > [!NOTE]
> >
> > **CVR in uplift calculations (control group comparison)**: (Converted Users / Total Unique Opens) × 100, or (Converted Users / Total Clicks) × 100.
>
> For detailed information on Email analytics, refer to [Email Analytics and Info](/docs/user-guide/campaigns-and-channels/email/analyze/email-analytics-and-info).
> [tab] Mobile Push
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign and for whom MoEngage tried sending the message, derived from Active Device Token. Includes messages not sent due to Campaign Controls such as Frequency Capping and Minimum Delay. | Count of users attempted |
> | Sent | Users for whom the push was successfully sent. | Count of messages sent |
> | Sent Rate | Percentage of attempted sends that were sent. | (Sent / Attempted) × 100 |
> | Failed To Send | Sum of all failure reasons in the Error Breakdown section — Campaign Controls (Frequency Capping, Minimum Delay, DND) plus technical sending and content errors. | Count of failed sends |
> | Failed Rate | Percentage of attempted sends that failed. | (Failed To Send / Attempted) × 100 |
> | Impressions | User devices that received the notification. Counted per device, not per user — a user with 2 devices that both receive the notification counts as 2 impressions. | Count of impressions |
> | Clicks | Notifications clicked by recipients. | Count of clicks |
> | Click Through Rate (CTR) | Percentage of impressions that were clicked. Only available when **Total** (not Unique) is selected in the occurrences dropdown. | (Total Clicks / Total Impressions) × 100 |
> | Converted Users | Unique users who completed the primary conversion goal at least once within the attribution window. | Count of unique converted users |
> | Event (Primary) | Total number of primary conversion goal events within the attribution window. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of users who performed the conversion event, tracked as Unique. | View-through & Total conversion: (Unique conversions / Total impressions) × 100 · Click-through & In-session: (Unique conversions / Total clicks) × 100 |
> | Total Campaign Revenue | Sum of total order value across all conversion events attributed to the campaign. Tracked across all attribution types. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of conversion events |
> | Average Revenue Per User | Average revenue generated per unique converting user. | Total Campaign Revenue / Number of unique conversions |
>
> > [!NOTE]
> >
> > Delivery metrics always reconcile: Attempted = Sent + Failed To Send. Failed To Send includes internal drops such as Frequency Capping, Minimum Delay, and DND.
>
> > [!NOTE]
> >
> > For iOS, whether Sent equals Impressions depends on the **Show iOS Impressions Toggle**: off → Sent equals Impressions in Campaign stats; on → Impressions reflects the actual Notification Received iOS event count instead.
>
> > [!NOTE]
> >
> > **CVR in uplift calculations (control group comparison)**: (Unique Conversions / Total Impressions) × 100, or (Unique Conversions / Total Clicks) × 100.
>
> For detailed information on Mobile Push analytics, refer to [Push Analytics and Info](/docs/user-guide/campaigns-and-channels/mobile-push/analyze/push-analytics-and-info).
> [tab] SMS
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign and for whom MoEngage tried sending the message. | Count of users attempted |
> | Sent | Users for whom the SMS send request was successfully accepted by the SMS provider. | Count of messages sent |
> | Sent Rate | Percentage of attempted sends that were successfully sent. | (Sent / Attempted) × 100 |
> | Delivered | Users to whom the message was confirmed delivered, based on delivery receipts the SMS provider passes to MoEngage. For custom connectors, only captured when Delivery Tracking is enabled. | Count of messages delivered |
> | Delivered Rate | Percentage of sent messages that were delivered. | (Delivered / Sent) × 100 |
> | Failed To Send | Users to whom the message was not sent. | Count of failed sends |
> | Failed Rate | Percentage of attempted sends that failed. | (Failed To Send / Attempted) × 100 |
> | Clicked | Number of times the URL in the SMS was clicked by recipients. Only tracked if Click Tracking is enabled; tracked URLs expire 15 days after send. | Count of clicks |
> | CTR | Percentage of delivered messages that were clicked. | (Total Clicked / Delivered) × 100 — for custom connectors without Delivery Tracking configured, CTR = (Total Clicked / Sent) × 100 |
> | Converted Users | Unique users who executed the conversion event at least once within 36 hours of successful send/delivery. Conversions are attributed only to users with a received delivery receipt (or successful send, for custom connectors without Delivery Tracking). | Count of unique converted users |
> | Event (Primary) | Total number of primary conversion goal events within 36 hours of successful send/delivery. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of users who performed the conversion event. | (Number of conversions / Delivered) × 100 — for custom connectors without Delivery Tracking configured, CVR = (Number of Conversions / Sent) × 100 |
> | Total Campaign Revenue | Sum of total order value across all conversion events attributed to the campaign. Tracked only if Revenue Tracking is enabled for the primary goal. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of conversion events |
> | Average Revenue Per User | Average revenue generated per unique converting user. | Total Campaign Revenue / Number of unique conversions |
>
> > [!NOTE]
> >
> > **CVR in uplift calculations (control group comparison)**: (Unique Conversions / Total Sent) × 100. If delivery tracking is enabled, (Unique Conversions / Total Delivered) × 100.
>
> For detailed information on SMS analytics, refer to [Analyze SMS Campaigns](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/sms/analyze-sms-campaigns).
> [tab] MMS
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign and for whom MoEngage tried sending the message. | Count of users attempted |
> | Sent | Users for whom the MMS send request was successfully accepted by the MMS provider. | Count of messages sent |
> | Sent Rate | Percentage of attempted sends that were successfully sent. | (Sent / Attempted) × 100 |
> | Delivered | Users to whom the message was confirmed delivered, based on delivery receipts the MMS provider passes to MoEngage. | Count of messages delivered |
> | Delivered Rate | Percentage of sent messages that were delivered. | (Delivered / Sent) × 100 |
> | Failed To Send | Users to whom the message was not sent. | Count of failed sends |
> | Failed Rate | Percentage of attempted sends that failed. | (Failed To Send / Attempted) × 100 |
> | Clicked | Number of times the URL in the MMS was clicked by recipients. Only tracked if Click Tracking is enabled; tracked URLs expire 15 days after send. | Count of clicks |
> | CTR | Percentage of delivered messages that were clicked. | (Total Clicked / Delivered) × 100 — for custom connectors without Delivery Tracking configured, CTR = (Total Clicked / Sent) × 100 |
> | Converted Users | Unique users who executed the conversion event at least once within 36 hours of successful send/delivery. Conversions are attributed only to users with a received delivery receipt. | Count of unique converted users |
> | Event (Primary) | Total number of primary conversion goal events within 36 hours of successful send/delivery. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of users who performed the conversion event. | (Number of conversions / Delivered) × 100 — for custom connectors without Delivery Tracking configured, CVR = (Number of Conversions / Sent) × 100 |
> | Total Campaign Revenue | Sum of total order value across all conversion events attributed to the campaign. Tracked only if Revenue Tracking is enabled for the primary goal. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of conversion events |
> | Average Revenue Per User | Average revenue generated per unique converting user. | Total Campaign Revenue / Number of unique conversions |
>
> > [!NOTE]
> >
> > When an MMS is delivered as an SMS fallback, that delivery is not included in the Delivered count above — it shows up separately as "Sent as SMS" in the Error Breakdown table instead. For example, of 100 MMS sent with 90 delivered (80 as MMS, 10 as SMS fallback): Sent = 100, Delivered = 80, and the Error Breakdown's "Sent as SMS" row shows 10.
>
> For detailed information on MMS analytics, refer to [Analyze MMS Campaigns](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/mms/analyze-mms-campaigns).
> [tab] RCS
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who were eligible for the campaign and for whom MoEngage attempted RCS message delivery. | Count of users attempted |
> | Sent | Users for whom the RCS provider successfully accepted the message. | Count of messages sent |
> | Sent Rate | Percentage of attempted sends that were successfully sent. | (Sent / Attempted) × 100 |
> | Failed To Send | Users for whom the message could not be sent. | Count of failed sends |
> | Failure Rate | Percentage of attempted sends that failed. | (Failed To Send / Attempted) × 100 |
> | Delivered | Users who successfully received the message on their device. | Count of messages delivered |
> | Delivery Rate | Percentage of sent messages that were delivered. | (Delivered / Sent) × 100 |
> | Read | Users who opened and read the message. | Count of messages read |
> | Read Rate | Percentage of delivered messages that were read. | (Read / Delivered) × 100 |
> | Clicks | Users who clicked a link within the message. Only tracked if Click Tracking is enabled. | (Total Clicked / Delivered) × 100 — for custom connectors without Delivery Tracking configured, CTR = (Total Clicked / Sent) × 100 |
> | Converted Users | Unique users who completed a conversion action at least once within 36 hours. | Count of unique converted users |
> | Event (Primary) | Total count of primary conversion events within 36 hours of sending the connector instance. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of users who completed a conversion action out of those who received the message. | (Conversions / Delivered) × 100 |
>
> > [!NOTE]
> >
> > **CVR in uplift calculations (control group comparison)**: Same as SMS: (Unique Conversions / Total Sent) × 100. If delivery tracking is enabled, (Unique Conversions / Total Delivered) × 100.
>
> > [!NOTE]
> >
> > **RCS with SMS as fallback**: when a campaign falls back to SMS for users RCS can't reach, Attempted and Sent are each split into an RCS component and an SMS component (e.g., "RCS Attempted" + "SMS Attempted"), and the Consolidated Campaign stats view lets you hover a card to see that split. Failed To Send, Delivered, Read, Clicks, and the conversion metrics are unaffected — they roll up both channels the same way.
>
> For detailed information on RCS analytics, refer to [Analyze RCS Campaigns](/docs/user-guide/campaigns-and-channels/sms-mms-and-rcs/rcs/analyze-rcs-campaigns).
> [tab] WhatsApp
>
> | Metric | Description | Formula |
> | - | - | - |
> | Sent | Message requests sent by MoEngage that were accepted by the WhatsApp Business Solution Provider (BSP). | Count of messages sent |
> | Delivered | Users to whom the WhatsApp message was delivered. | Count of messages delivered |
> | Delivery Rate | Percentage of sent messages delivered, based on Delivery Receipts received by MoEngage. | (Delivered / Sent) × 100 |
> | Read | Messages read by users. Only captured for users with Read Receipt turned on in their WhatsApp settings — users without it are undercounted here, not absent from delivery. | Count of messages read |
> | Read Rate | Percentage of delivered messages that were read (unique). | (Unique Reads / Delivered) × 100 |
> | Total Clicks | Every button/link click on the message, counted per click — a user clicking 2 links once each, plus another user clicking 1 link twice, totals 4. | Count of clicks |
> | Unique Clicks | Distinct button/link + user combinations — same example above totals 3, not 4. | Count of unique clicks |
> | Click Through Rate (CTR) | Percentage of delivered messages clicked (unique). | (Unique Clicks / Delivered) × 100 |
> | Click Through Open Rate | Percentage of read messages that were also clicked (unique). | (Unique Clicks / Read) × 100 |
> | Conversions | Unique users who executed the primary conversion goal within the attribution window. | Count of unique converted users |
> | Conversion Events | Total number of primary conversion goal events within the attribution window. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of delivered messages that converted. | (Conversions / Delivered) × 100 |
> | Total Campaign Revenue | Aggregated order value across conversions attributed to the campaign. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of Conversion Events |
> | Average Revenue Per Converted User (ARPU) | Average revenue generated per unique converting user. | Total Campaign Revenue / Conversions |
>
> > [!NOTE]
> >
> > A user becoming eligible twice for an event-triggered or periodic campaign is counted twice in Read, Total Clicks, and Unique Clicks — these aren't necessarily distinct people, just distinct eligible instances.
>
> For detailed information on WhatsApp analytics, refer to [Analyze WhatsApp Campaign](/docs/user-guide/campaigns-and-channels/whatsapp/analyze/analyze-whatsapp-campaign).
> [tab] In-App Message
>
> | Metric | Description | Formula |
> | - | - | - |
> | Impressions | Number of times a message from this campaign was shown. | Count of impressions |
> | Clicks | Number of times a message from this campaign was clicked. | Count of clicks |
> | CTR | Click-through rate: the percentage of impressions of this campaign's message that were clicked. | (Clicks / Impressions) × 100 |
> | Close | Number of times a message from this campaign was closed. | Count of closes |
> | Conversion Events | Total number of times the conversion event was performed after viewing/clicking the message, within the attribution window. Varies by attribution type selected. | Count of conversion events |
> | Conversions | Total number of users who performed the conversion event after viewing/clicking a message of this campaign within the attribution window. Varies by attribution type selected. | Count of converted users (by attribution type) |
> | CVR | Conversion rate: the percentage of impressions of this campaign's message that led to a conversion. | (Conversions / Impressions) × 100 |
> | Total Campaign Revenue | Total revenue generated through this campaign. Only shown once a revenue attribute is enabled on the conversion event. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Total Conversion Events |
> | Average Revenue Per Converted User | Average revenue generated per user who converted. | Total Campaign Revenue / Total Conversions |
>
> For detailed information on In-App Message analytics, refer to [Analyze In-app Campaigns](/docs/user-guide/campaigns-and-channels/in-app-message/analyze/analyze-in-app-campaigns).
> [tab] On-Site Message
>
> | Metric | Description | Formula |
> | - | - | - |
> | Impressions | Number of times a message from this campaign was shown. | Count of impressions |
> | Clicks | Number of times a message from this campaign was clicked. | Count of clicks |
> | CTR | Click-through rate: the percentage of impressions of this campaign's message that were clicked. | (Clicks / Impressions) × 100 |
> | Close | Number of times a message from this campaign was closed. | Count of closes |
> | Conversion Events | Total number of conversion goal events executed by all converted users, within the attribution window. Varies by attribution type selected. | Count of conversion events |
> | Conversions | Total number of users who performed the conversion event after viewing/clicking a message of this campaign within the attribution window. Varies by attribution type selected. | Count of converted users (by attribution type) |
> | CVR | Conversion rate: the percentage of impressions of this campaign's message that led to a conversion. | (Conversions / Impressions) × 100 |
> | Total Campaign Revenue | Total revenue generated through this campaign. Only shown once a revenue attribute is enabled on the conversion event. | Sum of order value across conversion events |
> | Average Order Value | Average value of conversions through this campaign. | Total Campaign Revenue / Total Conversion Events |
> | Average Revenue Per Converted User (ARPCU) | Total revenue generated by each user who performed the conversion event. | Total Campaign Revenue / Total Conversions |
>
> For detailed information on On-Site Message analytics, refer to [Analyze On-site Messaging Campaigns](/docs/user-guide/campaigns-and-channels/on-site-message/analyze/analyze-on-site-messaging-campaigns).
> [tab] Web Personalization
>
> | Metric | Description | Formula |
> | - | - | - |
> | Impressions | Number of times a message from this campaign was shown. | Count of impressions |
> | Clicks | Number of times a message from this campaign was clicked. | Count of clicks |
> | CTR | Click-through rate. | (Clicks / Impressions) × 100 |
> | Close | Number of times a message from this campaign was closed. | Count of closes |
> | Conversion Events | Total number of times the primary conversion goal was performed after an impression/click of this campaign's message. Varies by attribution type selected. | Count of conversion events |
> | Conversions | Total number of times the primary conversion goal was performed after an impression/click of this campaign's message. Varies by attribution type selected. | Count of conversion events (by attribution type) |
> | CVR | Conversion rate. | (Conversions / Impressions) × 100 |
> | Total Campaign Revenue | Total revenue generated through this campaign. Only shown once a revenue attribute is enabled on the conversion event. | Sum of order value across conversion events |
> | Average Order Value | Average value of conversions through this campaign. | Total Campaign Revenue / Total Conversion Events |
> | Average Revenue Per Converted User (ARPCU) | Total revenue generated by each user who performed the conversion event. | Total Campaign Revenue / Total Conversions |
>
> > [!NOTE]
> >
> > Conversion Goals Statistics additionally breaks the primary goal into **Total Conversions** and **Unique Conversions** — a distinction not surfaced in Aggregate Campaign Statistics above, where "Conversions" is unqualified.
>
> For detailed information on Web Personalization analytics, refer to [Analyze Web Personalization Campaign](/docs/user-guide/campaigns-and-channels/web-personalization/analyze/analyze-web-personalization-campaign).
> [tab] Cards
>
> | Metric | Description | Formula |
> | - | - | - |
> | Total Sent | Tracked when the MoEngage server successfully sends the Card to the user, regardless of whether they've opened the App Inbox. For event-triggered campaigns, every trigger adds to this count. Not deduplicated. | Count of sends |
> | Unique Sent | Same trigger condition as Total Sent, but counted once per user. | Count of unique users sent to |
> | Unique Delivered | Tracked when the user opens the App Inbox and the Card is delivered to their device inside it. Deduplicated per user for 72 hours. | Count of unique users delivered to |
> | Impressions | Tracked when the user views the Card in the Inbox — as soon as it loads for a new Card, or when the user scrolls to it for an older one. Counted once per session regardless of how many times the user scrolls back to it, and deduplicated per user for 72 hours. Android can occasionally over-count by 2–3 due to how the OS pre-renders rows. | Count of unique impressions |
> | Click | Tracked when the user clicks anywhere on the Card or its CTA. Deduplicated per user for 72 hours. | Count of unique clicks |
> | Click Through Rate (CTR) | Percentage of delivered Cards that were clicked. | (Unique Clicks / Unique Delivered) × 100 |
> | Conversions | Users who performed the conversion event after clicking the Card. Deduplicated per user for 72 hours. | Count of unique conversions |
> | Conversion Rate (CVR) | Percentage of Card impressions that led to a conversion. | (Conversions / Impressions) × 100 |
>
> > [!NOTE]
> >
> > Total Sent is the only metric above that isn't a unique count — Unique Sent, Unique Delivered, Impressions, Click, and Conversions are all deduplicated per user for 72 hours. If a user opens the Inbox 5 times in a day and the Card is delivered every time, Delivered still shows 1 within that window; it only increments again once the same Card is delivered outside a fresh 72-hour window. All counts combine Android and iOS.
>
> > [!NOTE]
> >
> > Card Events (Card Campaign Clicked/Delivered/Dismissed/Sent/Viewed, App Inbox Icon Clicked) may not match the campaign stats above — MoEngage calculates the two using different methods, so treat event counts and campaign-stats counts as separate sources rather than cross-checking one against the other.
>
> For detailed information on Cards analytics, refer to [Analyze Card Campaigns](/docs/user-guide/campaigns-and-channels/cards/analyze/analyze-card-campaigns).
> [tab] Facebook Audience
>
> | Metric | Description | Formula |
> | - | - | - |
> | Eligible Users | Users who qualified for the campaign based on segmentation and trigger criteria. | Count of eligible users |
> | Attempted | Eligible users with at least one identifier the campaign can pass to Facebook (Device ID, Mobile Number, or Email). A user reachable on another channel (e.g. push) is still excluded here if they lack one of these identifiers. | Count of users attempted |
> | Successfully Synced | Attempted users added to the Facebook console. Confirmed at the batch level — Facebook may still drop individual users within a confirmed batch during its own processing without reporting it back, so this can overstate what actually lands in the Facebook audience. | Count of users synced |
> | Conversions | Unique successfully-synced users who performed the conversion event within the attribution window. Only tracked if a Conversion Goal was set at campaign creation — it's optional. | Count of unique converted users |
> | Conversion Events | Successfully-synced users who performed the conversion event within the attribution window. | Count of conversion events |
>
> > [!NOTE]
> >
> > No CTR/CVR-style rate formulas are published for this channel — it's a sync funnel (Eligible → Attempted → Synced → Conversions), not an impression/click channel. It takes 6–48 hours for a sync to actually appear in Facebook Ads Manager, so counts checked before that window may look inconsistent with what Facebook shows.
>
> For detailed information on Facebook Audience analytics, refer to [Facebook Audience Campaign Analytics](/docs/user-guide/campaigns-and-channels/facebook-audience/analyze/facebook-audience-campaign-analytics).
> [tab] Google Ads Audience
>
> | Metric | Description | Formula |
> | - | - | - |
> | Eligible Users | Users who qualify based on segmentation/trigger criteria and having a valid identifier (Device ID, Mobile Number, or Email) on their profile. | Count of eligible users |
> | Attempted | Users for whom MoEngage sent data to the Google Ads API. | Count of users attempted |
> | Successfully Synced | Attempted users successfully added to Google Ads audiences. MoEngage treats any 2xx response from the Google Ads API as success, even though Google's own audience sync happens asynchronously afterward. | Count of users synced |
> | Failed To Add | Attempted users whose data could not be added, for internal or external reasons (see Campaign Failure Breakdown). | Count of failed adds |
> | Conversions | Unique successfully-synced users who performed the conversion event within the attribution window. Only tracked if a Conversion Goal was set at campaign creation — it's optional. | Count of unique converted users |
> | Conversion Events | Total conversion events performed by successfully-synced users within the attribution window. | Count of conversion events |
>
> > [!NOTE]
> >
> > No CTR/CVR-style rate formulas are published for this channel either — same sync-funnel shape as Facebook Audience, but with an explicit Failed To Add count that Facebook Audience doesn't surface as its own metric.
>
> For detailed information on Google Ads Audience analytics, refer to [Google Ads Audience Campaign Analytics](/docs/user-guide/campaigns-and-channels/google-ads-audience/analyze/google-ads-audience-campaign-analytics).
> [tab] Connectors
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign, after removing users who breached Frequency Capping, for whom MoEngage attempted the connector request. | Count of users attempted |
> | Sent | Users for whom the connector request returned a 200 OK status. Requests are not retried. | Count of requests sent |
> | Sent Rate | Percentage of attempted requests that were sent. | (Sent / Attempted) × 100 |
> | Failed | Users for whom the request returned any status other than 200, or for whom no value was found against the user/event attributes used in the request. | Count of failed requests |
> | Failure Rate | Percentage of attempted requests that failed. | (Failed / Attempted) × 100 |
> | Converted Users | Unique users who executed the conversion event at least once within 36 hours of successfully sending the connector instance. | Count of unique converted users |
> | Event (Primary) | Total number of primary conversion goal events within the attribution window. | Count of conversion events |
> | Conversion Rate (CVR) | Percentage of sent requests that converted. | (Unique conversions / Total sent) × 100 |
> | Total Campaign Revenue | Sum of total order value across all conversion events attributed to the campaign. | Sum of order value across conversion events |
> | Average Order Value | Average revenue generated per conversion event. | Total Campaign Revenue / Number of conversion events |
> | Average Revenue Per User | Average revenue generated per unique converting user. | Total Campaign Revenue / Number of unique conversions |
>
> > [!NOTE]
> >
> > Campaign Delivery Stats shows a funnel with an extra stage not reflected in the metrics above: Users in Segment → Users after FC Removal → After Personalization Removal → Sent. Two named drop reasons (Frequency Capping, personalization failure) roll up into the Attempted/Sent numbers without being broken out as their own metric rows.
>
> For detailed information on Connectors analytics, refer to [Connector Analytics and Info](/docs/user-guide/campaigns-and-channels/connectors/analyze/connector-analytics-and-info).
> [tab] Connected Apps
>
> | Metric | Description | Formula |
> | - | - | - |
> | Attempted | Users who qualified for the campaign, after removing users who breached Frequency Capping, for whom MoEngage attempted the request. | Count of users attempted |
> | Successfully Sent | Users for whom the request returned a 200 OK status. | Count of requests sent |
> | Failed | Users for whom the request returned any status other than 200, or for whom no value was found against the user/event attributes used in the request. | Count of failed requests |
> | Success Rate | Percentage of attempted requests that succeeded. | (Successfully Sent / Attempted) × 100 |
> | Conversion Events | Number of conversion events executed by users within 36 hours of successfully sending the request. | Count of conversion events |
> | Conversions | Unique users who executed the conversion event at least once within 36 hours of successfully sending the request. | Count of unique converted users |
> | Conversion Rate | Percentage of sent requests that converted. | (Number of Conversions / Successfully Sent) × 100 |
>
> > [!NOTE]
> >
> > What counts as "Successfully Sent" or "Failed" can vary per Connected App's own requirements — these aren't necessarily a fixed 200-status rule across every integration, unlike generic Connectors.
>
> For detailed information on Connected Apps analytics, refer to [Connected Apps Campaign Analytics](/docs/user-guide/campaigns-and-channels/connected-apps/analyze/connected-apps-campaign-analytics).
## Control Group Metrics
These metrics apply to the control group in any channel that supports control groups.
| Metric | Description | Formula |
| - | - | - |
| Active Target | Users who are eligible for notifications but intentionally excluded from receiving them. | Count of eligible users held out |
| Impressions | Impressions for the control group, which is always zero because no notification is sent. | Always 0 |
| Conversions | Users in the control group who completed a conversion event. | Count of unique converted users |
| Conversion Rate (CVR) | Percentage of control group users who completed a conversion event. | (Conversions / Active Targets) × 100 |
| Target Uplift | Uplift percentage of the target group over the control group for a conversion goal. Can be positive or negative. | ((Target group CVR − Control group CVR) / Control group CVR) × 100 |
| Variation Uplift | Uplift percentage of a variation over the control group for a conversion goal. Can be positive or negative. | ((Variation CVR − Control group CVR) / Control group CVR) × 100 |
> [!NOTE]
>
> The target group and control group use different CVR baselines. The target group's CVR uses the channel's own denominator (for example, impressions for Push), while the control group's CVR uses Active Targets, because the control group receives no notification.
# Campaign Stats
Source: https://moengage.com/docs/user-guide/analyze/dashboards/campaign-stats
Get a comprehensive view of campaign performance across all channels in MoEngage with aggregated KPIs and detailed per-campaign breakdowns.
# Campaign Stats
This dashboard provides a comprehensive view of all your campaigns across various channels in MoEngage. It allows you to overview campaign performance and track essential metrics. You can access aggregated data for an overall perspective as well as specific metrics related to individual campaigns.
To get started, this dashboard displays a set of KPIs that are essential for your campaigns.

## Overall Performance
The **Overall performance** section displays data from all active channels combined into a single view. Here, you can compare different channels across various metrics. The data is available in both chart view and table view. The metrics presented may vary depending on the channel.

To see which metrics are available for each channel, refer to [Metric and channel types](/docs/user-guide/analyze/dashboards/key-metrics).
## Channel Performance
This section of the dashboard presents channel-specific analysis, allowing you to measure metrics relevant to each channel. The data is available in both chart and table formats.
Additionally, a **Campaign summary** card is on the right to enhance your visual analysis. This card provides a summary of the total number of campaigns within that channel, as well as the highest and lowest values for each associated metric.

### Metrics and Channel Types
Metrics shown for each channel are listed below:
| Channel | Metric |
| - | - |
| Push | Sent, Impression, Click, Conversion, Revenue, CTR, CVR, and Impression rate |
| Email | Sent, Delivered, Click, Conversion, Revenue, CTR, CVR, and Delivery rate |
| SMS | Sent, Delivered, Click, Conversion, Revenue, CTR, CVR, and Delivery rate |
| Cards | Sent, Impression, Delivered, Click, Conversion, Revenue, CTR, CVR, Impression rate, and Delivery rate |
| Flows | Total trips, Engaged trips, Converted trips, and CVR |
| In-App | Impression, Click, Conversion, Revenue, CTR, and CVR |
| On-Site | Impression, Click, Conversion, Revenue, CTR, and CVR |
| Connectors | Attempted, Sent, Conversion, Revenue, CVR, and Success rate |
| Web personalization | Impression, Click, Conversion, Revenue, CTR, and CVR |
| FB audience | Eligible, Attempted, Synced, Conversion, User attempted, and User synced |
To learn more about each metric, refer to the Analyze section in [Campaigns and Channels](/docs/user-guide/campaigns-and-channels). For the formula behind each metric and how it differs by channel, refer to [Campaign Metrics](/docs/user-guide/analyze/dashboards/campaign-metrics).
## Advanced
### Filters and Duration
On the **Campaign stats** dashboard, you can filter the data based on the attribution type and set a date range. To use filters, follow the steps outlined below:
1. Select the attribution type from the list provided. To learn more about attribution types, refer to the Analyze section in Campaigns and Channels.
2. Set your desired date range and click **Apply**. This will update the dashboard according to your selected filters and display the relevant data.

### Switch Views
In the **Overall performance** dashboard, you have the following options to visualize the dashboard:
* You can toggle between the chart and table views for a more detailed look at your data.

* In the table view, you can sort the table in ascending and descending order.

* For each channel, you can visualize the data in a line chart or column chart.

* These charts can be viewed with hourly, daily, weekly, and monthly granularity.

# Custom Dashboards
Source: https://moengage.com/docs/user-guide/analyze/dashboards/custom-dashboards
Build custom dashboards in MoEngage with tailored analysis charts and reports — set up private or workspace-level views for your team.
> [!NOTE]
>
> Availability of this feature depends on your MoEngage plan and may require a paid add-on. To check what's available for your plan, refer to [Plans and Pricing](https://www.moengage.com/plans-and-pricing/). To get this feature, contact your MoEngage Customer Success Manager (CSM) or the Support team.
# Overview
These dashboards allow you to add custom analysis charts and reports tailored to meet any product and marketing need. You can add multiple charts and reports to this dashboard and monitor them at the same time.
You can create custom dashboards in two ways:
* [Private dashboard](/docs/user-guide/analyze/dashboards/custom-dashboards#private-dashboard)
* [Workspace dashboard](/docs/user-guide/analyze/dashboards/custom-dashboards#workspace-dashboard)
## Private Dashboard
> [!NOTE]
>
> This feature is only available in the Product Analytics package of MoEngage Analytics. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Private dashboards have built-in access controls, which allow the dashboard owner and members with specific permissions to access the dashboard.
You should create a private dashboard whenever the information you intend to display requires restricted access or confidentiality. You should use Private Dashboards in the following scenarios:
* **Confidential data**: If the dashboard contains sensitive information, such as financial data, strategic plans, personal performance metrics, or client-specific details, a private dashboard ensures only authorized users can access it.
* **Work in progress**: When a dashboard is still under development or refinement, making it private prevents premature viewing or usage by a wider audience until it's finalized and approved.
* **Targeted collaboration**: If a dashboard is meant for a specific team, project group, or set of stakeholders, a private dashboard allows the owner to grant access only to relevant individuals, ensuring the information reaches the intended audience. You can assign different roles, such as *Editor* for collaborators who need to modify the dashboard or *Viewer* for those who only need read-only access.
* **Personal use**: For dashboards created for personal tracking, goal monitoring, or individual analysis, keeping them private ensures your personal data remains secure.
## Workspace Dashboard
Workspace dashboards are viewable by default to all users who have access to the workspace. The dashboard owner can also give everyone access to edit. In this case, everyone with access to the workspace can edit the dashboard.
The dashboard owner can also limit edit access for specific users. This would allow only those users to edit and add new charts to the dashboards.
You should create a workspace dashboard when the information presented is relevant and intended for sharing with all members of a specific workspace or collaborative group. Some of the scenarios where you can use workspace dashboards are:
* **Broad team/Group visibility**: Use this type of dashboard when the dashboard content (like performance, project updates, or shared resources) should be easily accessible to everyone within that workspace without needing individual invitations for viewing.
* **Default transparency**: This type of dashboard is the go-to option when you want the default permission to be viewing access for all workspace members.
* **Collaborative environment**: This is ideal for dashboards that support group efforts, or metrics where all members benefit from seeing the same information.
* **Flexible editing control**: While workspace members can view by default, the owner retains control over editing permissions.
User permission definitions for Workspace Dashboards are:
* **Default access**:
* Only the owner can make changes to a private dashboard by default.
* For a workspace dashboard, everyone added to the workspace will have view access by default.
* **Owner**: The person who has created the dashboard will have full control, including creation, modification, deletion, and user management. The dashboard owner can set the overall access permissions of the dashboard. This includes View for all, Edit for all, and Edit for specific users.
* **Editors**: After the dashboard owner invites another user(s) to collaborate or edit, the user will receive this access. Editors will have the ability to:
* Edit the dashboard.
* Invite new editors and viewers to the dashboards.
* Manage user permissions to change another editor’s permissions as a viewer or a viewer's permission to an editor.
* **Viewers**: Viewers will have read-only access to dashboards to which they are granted access. They can request edit access, and the request will be sent to the dashboard owner via email. They cannot invite new users to view or edit the dashboard.
> [!NOTE]
>
> Only the owner is permitted to delete the dashboard.
# Create Dashboards
A custom dashboard can be added in two different ways:
### From the Navigation bar
1. From the left navigation sidebar, click **+ Create New** and then click **Dashboard**. The **Create dashboard** window appears.
2. Enter the desired name for your dashboard in the **Dashboard name** field
3. Under the **Dashboard visibility** section, select how you want the dashboard to be accessed.

4. After selecting the visibility type, click **Create**.
### From the Analysis
All the analyses performed on the Users, Behavior, Funnels, Retention, and Session and Source sections of MoEngage Analytics can be added to the custom dashboard in the form of tables and charts.
1. To add charts or tables to the dashboard, click **Save** from the upper right corner of the analysis screen and then select **Save chart to the dashboard** or **Save table to the dashboard** as desired.
2. You can save the analysis to an existing dashboard from the list or create a new one. Select the desired option.
3. Enter the **Chart name** and **Description** in the respective fields.
4. If you select **Create new**, select the desired **Dashboard visibility** and access permissions.
5. Click **Save** to confirm.

You can create up to 10 custom dashboards on the Customer Journey Analytics (CJA) package and up to 300 on the Product Analytics (PA) package, with the option to incorporate up to 20 charts within each dashboard.
# Managing Dashboard
You have complete flexibility in managing your dashboard. MoEngage Analytics provides you with various features to enhance your dashboard experience.
## Share a Dashboard
To share a dashboard, perform the following steps:
1. Click the **Share** button in the upper-right corner.

2. Select the desired **Dashboard visibility** type. You can share both **Workspace** and **Private** dashboards.

3. Under the **Share access to** section, enter the email addresses of the users you want to share the dashboard with. You can enter up to 50 emails.

4. From the **Access type** drop-down, select the desired access permission for these users as **Viewer** or **Editor**.

5. Click **Share**. The dashboard will be shared with the selected users, who will then receive an email notification.
6. After sharing the dashboard, you can manage access for each user. You have the ability to:
* Change their permission level (Edit or View)
* Transfer ownership of the dashboard
* Remove their access completely

## Dashboard Filters
Follow the steps outlined to apply filters:
1. Click the **Dashboard Filter** section, and select the date range in the **Duration** box.
2. Click **+ Filter users** to filter out the desired custom segment or create a segment, and then click **Apply**.
\\

**Compare to past** allows you to perform a time series comparison.

The selected filters are applied to all the charts present in the dashboard.
## Refresh
When you open the dashboard, all charts will be refreshed automatically, and the results will be saved until the end of the day. You can refresh an individual chart and query new analysis at any time. By clicking the refresh button, the dashboard will re-run the chart queries and display the latest available data for analysis. Next to the refresh button, there is text indicating the time elapsed since the last refresh.

## Edit
You can modify the chart or tweak the query parameters for the desired analysis.
To edit any analysis report, click the chart area or click **View / Edit**. Edit analysis functionality directs you to the respective Behavior, Funnel, Retention, or Session and Source page, and it preloads all the analysis parameters.

Here, you can:
* Modify the chart name and chart description.
* Change query parameters (events and filters) and save the analysis.
* Save the same or modify the analysis to another dashboard using **Save as**.
* Move chart analysis from one dashboard to another dashboard.
* Share the analysis using **Copy link** or **Email link**.
## Resize and Reposition
The analysis display can be adjusted to two sizes: half-width and full-width. To do so, click **Resize** in the ellipsis menu.
You can also reposition the analysis by clicking and dragging the chart by its header bar and then dropping it in your preferred location on the dashboard. When you hover over the chart header, the cursor will change to indicate that you can grab and move the header.

## Chart and Table Display Modes
Dashboard charts include Key Performance Indicators (KPIs) that offer detailed insights into the data presented. These KPIs reflect various relevant information, such as data points for a specific day or week, the average of all data points, and the percentage change compared to both the previous data point and the first data point. Refer to the legends located below the KPIs to understand this information.

An individual analysis can have 5 different display modes if KPIs are available for a chart.

* **Chart**: This option offers visualization of the data for deeper insights.
* **Chart & KPI**: This option provides visual insights and quick analysis of the chart reports as comprehensive information.
* **KPI**: This option provides an overall analysis of the chart reports and comprehensive information calculated using the data available in the chart.
* **Table**: This option allows you to obtain a tabular view and also download the data into CSV format.
* **Table Transposed view**: This option allows you to view and share the table in the preferred format by shifting its vertical and horizontal orientation.
## Subscribe to the Dashboard
By subscribing to a dashboard, you can receive a snapshot of it via email. This feature allows you to share custom dashboards with users both within your organization and externally through dashboard subscriptions. You can also set the frequency of these email reports being received for the selected dashboard.
> [!NOTE]
>
> A workspace can create up to 25 dashboard subscriptions on the Product Analytics package, and up to 10 on the CJA package.
Follow the outlined steps to subscribe:
1. Click the Subscribe icon at the top and then click **Subscribe to the Dashboard**.
2. On the **Subscribe to the Dashboard** window, in the **Send report to field**, enter or paste the email address to which the email report is to be sent. A list of recipients is added as a comma-separated list. You can add a maximum of 50 email recipients to each subscription.\
The email domain needs to be whitelisted for non-registered users. For more information, refer to [Manage Subscription Domain Whitelisting](/docs/user-guide/analyze/dashboards/custom-dashboards#manage-subscription-domain-whitelisting).

3. Configure the **Frequency of sending** **reports** section to send the dashboard report at a specific time and date.

4. Click **Subscribe** to create a subscription.
## Manage Subscriptions
To manage existing subscriptions:
1. Navigate to **Settings** > **Reports and Alerts** >**Dashboard Subscriptions**. The list of all subscriptions to the dashboards is displayed.
2. Search for the subscriptions by emails or dashboard names.
3. View the list of subscribers and unsubscribers by expanding the subscription.
### Edit or Delete New Subscription
To edit or delete existing subscriptions, click to edit or delete the subscription.
### Unsubscribe from a Dashboard Subscription
There are three ways to unsubscribe from a dashboard:
* **Click the unsubscribe link embedded in the email**: This unsubscribes individual users.
* **Edit and remove the email ID from the subscription**: On the **Dashboard Subscriptions** page, you can remove single or multiple users to stop sending the subscription to them.
* **Delete the subscription**: On the **Dashboard Subscriptions** page, delete the subscription to stop all future emails.
### Subscription Access and Permissions
The following table describes the roles and permissions for managing subscriptions.
For more information about roles and permissions, refer to [Access Roles](/docs/user-guide/settings/account/team-management/access-roles).
| Action for managing subscription | Role and Access |
| - | - |
| Create Subscription | All user roles that have access to the dashboard can create subscriptions. |
| Edit or Delete Subscription | - All user roles can edit or delete their own created subscriptions. - Only Managers and Administrators can edit or delete subscriptions for other user roles. |
| Add Users to the Subscription List | - All user roles can add users as part of the MoEngage dashboard to the subscription list. - Only Managers and Administrators can add users who are not part of the MoEngage dashboard to the subscription list (the domain should be in the whitelist). |
## Manage Subscription Domain Whitelisting
Domain whitelisting helps protect data confidentiality. Administrators and Managers can whitelist domains used to subscribe to the dashboards.

To whitelist a domain:
1. Navigate to **Settings** > **Dashboard Subscriptions**
2. On the **Dashboard Subscriptions** page, click **Create/Manage** and select **Manage Domain Whitelist**.
3. In the **Select email domains to whitelist** field, type or paste the domains you want to whitelist. For example, abc.com.
4. Click **Update** to whitelist the domain names. You can whitelist up to five domains.
# Key Metrics
Source: https://moengage.com/docs/user-guide/analyze/dashboards/key-metrics
Monitor acquisition, engagement, and performance from the MoEngage Key Metrics dashboard — track DAU, MAU, retention, and conversion trends.

**Key Metrics**
E-Learning Course
[Open](https://academy.moengage.com/student/path/3387998-key-metrics)
This dashboard provides all the important and necessary information about your product's usage, engagement, and performance metrics. Some of these metrics, which are essential for day-to-day monitoring, are described below:
> [!NOTE]
>
> Data computation occurs from 01:00 in the App Timezone. Consequently, MoEngage does not backfill any events ingested by the client after 01:00 for prior days.
The metrics on this dashboard describe your product as a whole. For campaign-level metrics and their formulas by channel, refer to [Campaign Metrics](/docs/user-guide/analyze/dashboards/campaign-metrics).
## Acquisition
Acquisition serves as a key metric for measuring the growth of your platform. It's crucial to track this metric to assess the success of your campaigns and products, allowing you to take the necessary actions. You can address questions such as:
* How many new users are added?
* What platforms do they use?
* Where are the users coming from?

You can track the following metrics:
* **New users**: This chart shows the count of the new users acquired for the selected date range and platform.
* **New users by platform**: This chart shows the number of new users acquired on each platform for the selected date range. If you add a platform filter in the Key Metrics dashboard filter, you will not see this chart.
* **New users by source**: This chart shows the count of the new users acquired based on their source of acquisition for the selected date range and platform.
## Engagement
Engagement provides data on your active users and their sessions on your app or website. This metric helps you determine whether your app or website has the potential reach and exposure. This metric helps you in evaluating:
* How many users are actively engaging on a daily, weekly, and monthly basis?
* How many users have not engaged with your app or website?
* How often are users engaging?
* What is the average duration of a user session?
* What percent of users land on your page and leave without engaging?

You can track the following metrics:
* **Daily Active Users (DAU)**: This chart shows the number of new users acquired based on their source of acquisition for the selected date range and platform.
* **7-Day Active Users**: This chart shows the number of unique users who accessed your app or website on a specific week.
* **30-Day Active Users**: This chart shows the number of unique users who accessed your app or website for a specific 30-day period.
* **Dormant users**: This chart shows the number of users who have not opened your app or website in the past 30 days.
* **Stickiness**: This chart shows the number of Daily Active Users and Monthly Active Users. This ratio shows how often users interact with your app or website.
* **Average session duration**: This chart shows the average session duration for your users. It is calculated by dividing the sum of all session durations by the number of sessions.
* **Average session duration by platform**: This chart shows the session data and divides it by platform. If you select a particular platform using dashboard filters, you will not see this chart.
* **Bounce rate**: This chart shows the bounce rate for your users. It is calculated by dividing the number of single-page sessions by the total number of sessions.
## Conversion
Conversion provides you with data for users who successfully complete an event. It also gives revenue-specific data for your platform. This helps you measure the actual quality of your campaigns and products. With conversion, you can answer questions specific to your app or website, such as:
* What percentage of users are converted after engaging?
* What is the average time taken by your users to complete a conversion event?
* What is the average count of the users who completed a conversion event?
* What is the revenue generated on your platform in a specific duration?
* What is the average order value for a product purchase?
* What is the average revenue generated per user?

You can track the following metrics:
* **Conversion rate**: This chart shows your app or website's conversion rate for the selected date range and platform. It is calculated as a percentage of the users who converted out of the total number of users who opened your app or site.
* **Time to convert**: This chart shows the conversion time of the 90th percentile of users for your app or website compared to the previous day.
* **Converted users**: This chart shows the average number of users who converted on your app or website compared to the previous day.
* **Conversion events**: This chart shows the number of times the conversion events were performed compared to the previous day.
* **Revenue**: This chart shows the average daily revenue for your app or website and the total revenue. The daily revenue is charted and compared to the previous day.
* **Average Order Value**: This chart shows the average order value for your app or website every day compared to the previous day.
* **Average Revenue Per User**: This chart shows the average revenue per user for your app or website every day compared to the previous day.
## Retention
Retention is a critical metric in evaluating how good your app or website is at keeping your users. It allows you to measure user loyalty and the frequency of their engagement with your platform. Here are some of the questions retention will help you answer:
* What is the average count of uninstalls for your product for a given period of time?
* Which segment of users requires actions based on how recently they have used the service?
* How often do your users engage with your app or website?
* Who are the users that require immediate attention to prevent them from churning?

You can track the following metrics:
* **Uninstall users**: This chart shows the count of users who uninstalled your app for the selected time range and platform.
* **Uninstall events**: This chart shows the count of users who uninstalled your app for the selected time range and platform.
* **Needs attention**: This chart shows a count of the users who belong to the *Need Attention* segment based on their Recency, Frequency, Monetory (RFM) score. These users have spent a good amount of time on your app or website, but it was a while ago.
* **About to sleep**: This chart shows a count of the users who belong to the *About to Sleep* segment based on their RFM score. These users have not been active recently, and their frequency of visits and monetary spending are below average.
* **Hibernating**: This chart shows a count of the users who belong to the *Hibernating segment* based on their RFM score. These users have not visited in a long time and their visits occur infrequently with low spending amounts.
* **Lost**: This chart shows the users who belong to the *Lost segment* based on their RFM score. Based on their frequency of visits, monetary spending, and last visit, these users belong in the bottom percentile.
For more information on RFM scores and segments, refer to [How RFM is Calculated](/docs/user-guide/segment/create-segments/rfm-segments).
## Advanced
Dashboard elements can be adjusted to extract specific data based on your needs. This flexibility allows you to customize the data displayed and the analysis.
### Filters and Dates
On the key metrics dashboards, platform and duration filters are available at the top.

Follow the steps outlined to use filters:
1. In the **Platform** list, click the platform of your choice. The filter applies across the dashboard for the charts and tables across all the metrics. By default, the platform applied is **All**.
2. Choose the duration. You can select the date range to be **Last week**, **Last month** or you can also set a **Custom range**.
3. After selecting the platform filter and duration, click **Apply**.
4. To reset the filter, click the **Reset filters** icon.
### Suggested Actions
Each chart on the dashboard is interactive. To enhance your understanding, MoEngage provides suggested actions. Click a chart to access a detailed view, where you can see the percentage of change with a visualization of the metric for the selected platform over a time duration. Additionally, you will find a percentage change of the metric displayed for each chart. Based on the data, a suggested action to improve the metric will be provided.

### Download and Share Charts and Tables
Both charts and tables are available for download. To download:
1. Click the ellipsis icon next to any of the metrics and click **Download charts**.
2. Select the charts and click **Download**. The selected charts will be downloaded as image files.
3. Click **Download CSVs** to download the data as CSV files.

You can also share the Key Metrics dashboard. To do so, click the **Share** icon on the upper-right corner of the page. You can choose to share it via link or email.

# My Studio
Source: https://moengage.com/docs/user-guide/analyze/dashboards/my-studio
Save and organize your MoEngage analyses in My Studio — retrieve saved reports, resume interrupted work, and streamline your analytics workflow.
As the world continues to evolve, so do the challenges and opportunities data and analytics present. With MoEngage's **My Studio**, you can say goodbye to data management frustrations and hello to a streamlined and productive workflow. No longer will you have to worry about losing your progress due to unexpected disruptions, being delayed in making analytical decisions, or losing perspective in a sea of reports. **My Studio** offers a range of functionalities that allow you to store your saved analyses in one place, making it easy for you to retrieve and resume your work from where you left off. It streamlines the process of exploring popular analyses while also serving as a source of inspiration for your projects.
# Analytics Studio Overview
[Loom video player](https://www.loom.com/embed/9d764d37e2c04feba905d47cc993321d)
> [!NOTE]
>
> * My Studio is a personal user-specific dashboard that cannot be accessed by any other user.
> * A user can save a maximum of 50 analyses.
# Use Cases
* My Studio plays a crucial role in keeping your company on top of key performance indicators (KPIs). With a personal space, you can create a centralized hub for all your important metrics and reports.
* Searching, sorting, and filtering analyses are easier and more time-efficient, allowing you to organize your work according to your preferences and priorities.
* With My Studio's collaborative features, you can spark discussions, share ideas, and collectively work towards achieving your goals. It empowers your team to stay informed, engaged, and aligned with the company's overall vision.
# Navigating to My Studio
Let's first locate **My Studio** on your MoEngage dashboard before proceeding to create your saved analyses.
1. Login to your MoEngage dashboard and navigate to the left menu bar.
2. Click **Analyse** and then select **My Studio**.

3. Once you enter the My Studio dashboard, you'll see all your saved analyses with the following details:
| Name | Description | Last Updated | Analyses Type |
| - | - | - | - |
| Name of the user who saved the analysis. | A brief description of the analysis. | The date and time the analysis was last updated. | The category of analysis: - Users - Behavior - Funnels - Retention - Session and source - User paths |
| You can use the search bar to find a saved analysis or filter the results based on the analysis type. |
|  |
# Saved Analyses
When you execute the analysis and believe you will revisit it, MoEngage recommends saving the analysis to **My Studio**. You can accomplish this by clicking the **Save** dropdown and selecting your Workspace (Studio in this case) you want to save to. In this section, we will take the example of saving a **Users** analysis.
Follow the steps below to create saved analyses:
1. Login to your MoEngage dashboard and navigate to the left menu bar.
2. Under **Analyse**, select the **Users** type of analysis.

3. Select the appropriate User property(ies) for analysis from the **Select user property** dropdown and then click **APPLY** to execute the event.

Clicking **APPLY** will allow you to examine the analysis data in both graphical and tabular format.

4. Click the **Save** dropdown and then select **Save to Studio**.

5. On the pop-up, enter the name and description of your analysis and then click **Save** to confirm.

You'll receive a success message "Analysis saved successfully".
6. Navigate to **My Studio** on your MoEngage dashboard to view the newly saved analysis.

# Sharing Saved Analyses
> [!NOTE]
>
> This feature is only available in the Product Analytics package of MoEngage Analytics. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Once an analysis is saved to My Studio, you can share it with team members or external audiences to facilitate collaboration and knowledge sharing. This feature provides detailed control over who can view or edit the analysis.
To share an analysis from the My Studio list view, perform the following steps:
1. From the **Saved Analysis** tab in My Studio, locate the analysis you wish to share in the list.
2. Click the vertical ellipsis (...) next to the analysis name.

3. Select **Share** from the list. The **Share** settings window will appear.

4. Configure the sharing settings. For more information, refer to [Configuring Sharing Settings](/docs/user-guide/analyze/dashboards/my-studio#configuring-sharing-settings) below.

Alternatively, you can share an analysis immediately after saving it or when viewing/editing it. To share from the analysis page, click the **Share** button in the upper-right corner of the page header.

## Configuring Sharing Settings
Regardless of the method used to initiate sharing, the same pop-up window appears, allowing you to configure access permissions.
### General Access Sharing
You can set general access permissions for anyone who receives the shareable link. To do so:
1. Click the **Copy Link** button to copy the unique, secure shareable link to your clipboard.

2. Set Edit or View permissions for general access. For more information, refer to [Understanding Permissions](/docs/user-guide/analyze/dashboards/my-studio#understanding-permissions) below.
Share this link via email, chat, or other channels.
### Access to Specific Members
For more granular control, you can invite specific individuals via email and set their access levels independently. To invite specific members, perform the following steps in the **Share** pop-up window:
1. From the **Share access to** list, select the email addresses of the members you want to share the analysis with.
2. From the **Access type** list, select the desired permission level (**View** or **Edit**) for the specified user(s).

3. Click **Share**.
Invited users will receive an email notification containing a direct link to the shared analysis and a preview of the chart. Their names and permissions will appear in the list of users with access.
## Understanding Permissions
### Edit Access
Users granted **Edit** access have the following permissions:
* **Modify the analysis:** Make changes to the analysis parameters and setup.
* **Save changes:** Save updates to the analysis. Note that saving changes modifies the original analysis for all collaborators. Consider using **Save as a new analysis** if you want to preserve the original version.
* **Invite others:** Share the analysis with additional users, granting either View or Edit permissions.
* **Delete the analysis:** Remove the analysis entirely. A confirmation prompt will appear before deletion. The original owner will be notified via email if a collaborator deletes the analysis.
### View Access
Users granted **View** access have the following permissions:
* **View the analysis:** See the analysis configuration and results, and interact with visualizations.
* **Cannot edit:** They cannot make any changes to the analysis setup or save modifications.
* **Cannot invite others:** The option to share the analysis further is disabled for view-only users.
* **Request access (Indirect sharing):** If a user with View access shares the analysis URL with someone who doesn't have permission, the recipient can request access. This request is sent to the original owner of the saved analysis
# Drafts
When you perform analyses within MoEngage Analytics, the progress is automatically saved as drafts. These drafts are conveniently accessible in the **Drafts** tab on the **My Studio** page. This tab serves as a central location for all your ongoing analyses, allowing you to easily resume your work exactly from where you left off.

For each automatically saved draft, you can see its description, the date it was last updated, its expiration date, and the analysis type.
> [!NOTE]
>
> Draft analyses that were last modified 30 or more days ago will be automatically deleted.
## Recents
> [!NOTE]
>
> This feature is only available in the Product Analytics package of MoEngage Analytics. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
While performing an analysis, you can access your in-progress analyses. Click the **Recents** button in the upper-right corner to display a list of all analyses you have recently worked on. Drafts are identified by this  icon located next to the analysis name.

## Search and Filter
From the search box, you can search for your draft analyses by name. Additionally, you can filter the drafts by **Analysis Type** to conveniently group and locate specific analyses as shown below.

# View, Edit, or Delete Analysis

## View/Edit
On your Studio, click the analysis row you want to view or edit, or click the vertical ellipsis and then select **View/Edit**.
After editing a saved analysis, you need to select **Save as a new analysis** from the **Save** dropdown. This will generate a new draft for the same analysis and store it in your Studio.

> [!WARNING]
>
> An analysis will be saved only if you execute the specified event(s) and give a unique name to the analysis.
>
> 
## Delete
On your My Studio dashboard, click the vertical ellipsis on the analysis you want to delete and then select **Delete**.
# Overview
Source: https://moengage.com/docs/user-guide/analyze/dashboards/overview
Overview of MoEngage dashboards for monitoring campaigns, tracking KPIs, and accessing pre-built or custom views for your analytics needs.
A dashboard is a landscape that displays all your analysis charts and tables, summarizing the most important data. It enables you to easily monitor the status of your marketing campaigns and other product initiatives. You can add your analysis reports and key performance indicators (KPIs) to your dashboard and save them, allowing you to check on them whenever you wish.
To access dashboards:
1. On the sidebar menu in MoEngage, hover over the **Dashboards**  menu item. The **Dashboards** menu appears.

To get started quickly, MoEngage offers the following pre-built dashboards that meet basic analytics needs:
* [Key metrics](/docs/user-guide/analyze/dashboards/key-metrics)
* [Campaign stats](/docs/user-guide/analyze/dashboards/campaign-stats)
* [Best time analysis](/docs/user-guide/analyze/dashboards/best-time-analysis)
* [Reachability](/docs/user-guide/analyze/dashboards/reachability)
Before building your custom dashboard, let's learn more about what these dashboards offer.
# Reachability
Source: https://moengage.com/docs/user-guide/analyze/dashboards/reachability
Track push notification opt-in and opt-out trends with the MoEngage Reachability Dashboard, covering up to one year of historical data.
Reachability refers to the ability to contact a user through a chosen channel. The Reachability Dashboard in MoEngage Analytics provides insights into the reachability trends of users who have opted in to receive your push notifications and those who have opted out.
You can view users' reachability trends for any 30 days at a time by choosing the desired date range at the top of the dashboard. The starting date for this custom range can go back up to one year.
With this dashboard, you can address questions such as:
* How many users are reachable via push notifications?
* How many users have opted in for push notifications over time?
* How many users are active on your platform but cannot be reached due to opting out of push notifications?
You can view the reachability trends for the following platform users:
* Android
* iOS
* Web

The reachability trends have the following major metrics present:
* **Push eligible users**: These users have at least one active device with a valid push token. Eligible users are calculated based on users having any of these values of reachability user property.
* 201: Reachable and opted in
* 200: Reachable and opt-in status unknown
* 202: Not reachable due to opt-out
* **Push reachable users**: These users have at least one active device with a valid push token and have not explicitly opted out. Eligible users are calculated based on users having any of these values of reachability user property:
* * 201: Reachable and opted in
* 200: Reachable and opt-in status unknown
* **Opted-in users**: These users have at least one active device with a valid push token and opted in. These users are considered reachable. Eligible users are calculated based on users having reachability user properties as:
* 201: Reachable and opted in
* **Opted-out users**: These users have at least one active device with a valid push token and have opted out on all of them. These users are not considered reachable. Eligible users are calculated based on users having reachabilityuser attributes as:
* 202: Not reachable due to opt-out
> [!NOTE]
>
> The Reachability dashboard shows push reachability trends, so its counts can differ from the reachable user count of a segment or campaign. For more information, see [Why Reachable User Counts Differ Across Pages](/docs/user-guide/segment/reachability/user-reachability#why-reachable-user-counts-differ-across-pages).
# What causes unexpected event sequences in user paths?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/what-causes-unexpected-event-sequences-in-user-paths
Why User Path charts may show unexpected event sequences — learn about dropoff buckets, vertical event grouping, and ordering behavior.
## Problem
An unexpected sequence of events within the User Path charts is observed, where certain events are grouped together or appear out of chronological order. These discrepancies make the user experience confusing, leading to difficulty in accurately analyzing and understanding user steps.

## Solution
To address this issue, consider the following factors:
1. **Dropoff in User paths**
* The "Dropoff" represents an aggregated bucket or step in the **User paths** graph, typically appearing at the end of the path.
* Events within the same step are arranged vertically, but this ordering has no particular significance.
2. **Server-to-Server (S2S) Events**
* S2S events might not include a user_time attribute, leading to the server time being used as a fallback.
3. **Impact of Server Time**
* When events are pushed or synced from the app, they may share the same server time if they occur in quick succession.
* This can cause multiple events to appear in the same step of the **User paths** graph, regardless of their actual sequence.
> [!NOTE]
>
> * The **User paths** and the display of events in the graph are influenced by the nature and timing of events, including S2S events.
> * The vertical ordering of events within the same step has no specific significance.
> * Events appearing in the same step do not necessarily indicate a break in their sequence or chronology.
# Why do the campaign stats and campaign analytics show different counts?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-do-the-campaign-stats-and-campaign-analytics-show-different-counts
Why Campaign Stats and Campaign Analytics show different engagement counts in MoEngage, and how to interpret the analytical logic differences.
## Problem
Differences in engagement metrics, such as open and click rates, are observed between the Campaign Stats dashboard and the Campaign Analytics page in MoEngage.
## Cause
The differences in engagement metrics, such as open and click rates, between Campaign Stats and Campaign Analytics occur due to differences in their analytical logic. While both features are part of the same platform, they present similar data in distinct ways to meet specific analysis requirements.
## Solution
To understand and resolve this difference, review the following points:
1. **Query duration**
* The campaign dashboard displays data for a specific time range, such as the past seven days.
* Events and metrics outside this time range are not included.
2. **Clicked campaign redirect**
* When you click a campaign, the system redirects you to the Campaign Analytics page.
* This page has its own **Date range** filter, which is set separately from the time range on the dashboard.
3. **Data calculation**
* Consolidated **Campaign stats** on the dashboard calculate metrics based only on events within the selected time range.
* Events that occurred outside of the specified time range are excluded.
4. **Events outside the selected time range**
* A campaign could be initiated and include events outside the selected time range.
* This can result in discrepancies, such as a lower sent count but a higher opened or clicked count, which can increase the click-through rate (CTR) or conversion rate (CVR).
5. **Expected behavior**
* This behavior is expected. Each page counts only the events within its own time range. To compare the counts, set the same date range on both pages.
> [!NOTE]
>
> **Information**
>
> The Campaign stats dashboard aggregates metrics across campaigns for the selected time range, while the Campaign Analytics page shows one campaign's metrics for the date range selected on that page.


# Why Do Uninstall Counts Differ Between the Key Metrics Dashboard and Segmentation?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-do-uninstall-counts-differ-between-the-key-metrics-dashboard-and-segmentation
Why uninstall counts differ between Key Metrics and Segmentation — one tracks per-user uninstall time, the other counts per-device events.
## Problem
There is a discrepancy in the uninstall counts between the Key Metrics dashboard and Segmentation numbers.

## Explanation
* This difference is expected.
* The Key Metrics dashboard tracks the uninstall time attribute and records it when a user uninstalls the app from all their devices. 
* Segmentation numbers count each uninstall event for each device separately. 
# Why do uninstall event counts in MoEngage differ from Google's data or show zero?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-do-uninstall-event-counts-in-moengage-differ-from-googles-data-or-show-zero
Troubleshoot when MoEngage uninstall counts don't match Google's data or show zero — verify your silent push and real-time tracking setup.
## Problem
The uninstall event count or uninstall analytics in MoEngage does not match Google's data, and the uninstall count shows zero.
## Solution
To resolve the issue of uninstall analytics showing zero, perform the following steps:
1. Check if silent push or real-time uninstall tracking is enabled. Uninstalls can only be tracked if either silent push or real-time uninstall tracking is configured. For more information, refer to the relevant documentation:
* [Silent Push](https://www.moengage.com/docs/developer-guide/android-sdk/push/advanced/push-display-handled-by-application)
* [Real-time Uninstall Tracking](https://www.moengage.com/docs/developer-guide/components-for-sdk/tracking/real-time-uninstall-tracking)
2. Understand how uninstall tracking works.
* If uninstall data is missing in MoEngage for some days, it may be due to reliance on Firebase Cloud Messaging (FCM).
* The *Device Uninstall* event on the user profile reflects when MoEngage detected the app uninstallation, not the exact time the user uninstalled the app.
* Uninstall tracking depends on the callbacks received from the FCM server, and you cannot determine the exact uninstallation time.
By performing these steps, you can ensure accurate uninstall analytics and resolve discrepancies between MoEngage and Google's data.
# Why Does Real-Time Uninstall Tracking Differ from the Uninstall Status on the Dashboard?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-does-real-time-uninstall-tracking-differ-from-the-uninstall-status-on-the-dashboard
Why real-time uninstall tracking via FCM may not match the MoEngage dashboard status, and what causes differences in uninstall reporting.
## Problem
After the real-time uninstall tracking is implemented, the uninstalled status on the MoEngage dashboard is expected to match that.
## Explanation
The real-time uninstall tracking does not match the uninstalled status on the MoEngage dashboard due to the following reasons:
* Firebase Cloud Messaging (FCM) tracks the app-remove event when an app is uninstalled. MoEngage uses this app-remove event through FCM Functions.
* The uninstalls tracked by MoEngage's backend may not match the FCM events. The real-time uninstall tracking relies on FCM configuration and the app_remove event.
* Currently, MoEngage tracks uninstall by sending silent push notifications to all user devices daily. It can take up to 24 hours to track an uninstall.
* The FCM SDK tracks an uninstall immediately, allowing for a quick response.
* You cannot change the installed flag. MoEngage manages it through silent push notifications.
> [!NOTE]
>
> If you see more uninstalls in the Play Store console than in MoEngage, it can be an issue with calls made to FCM. In this case, you must contact the FCM support. It is essential to understand that uninstall tracking occurs in the backend, and real-time uninstall tracking numbers cannot be compared.
>
> To implement a real-time uninstall, read [Real-time Uninstall Tracking](https://www.moengage.com/docs/developer-guide/components-for-sdk/tracking/real-time-uninstall-tracking#create-cloud-function).
# Why does the 0-1 bucket in 'total events per user' behavior analysis show no users?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-does-the-0-1-bucket-in-total-events-per-user-behavior-analysis-show-no-users
Why the 0-1 bucket in Total Events per User behavior analysis is always empty, and how to find users who never performed an event by using segmentation.
## Problem
When you run a **Total Events per User** behavior analysis with a custom distribution, the 0-1 bucket always shows 0 users, even though you expect it to capture low-activity users.
## Why This Happens
Two things combine to make this bucket permanently empty:
1. **Total Events per User counts only users who performed the selected event at least once.** The analysis measures how many times each user performed an event they have already performed, so a count of 0 can never appear in the result set.
2. **Custom distribution buckets exclude their upper bound.** A 0-1 bucket captures values greater than or equal to 0 and less than 1 — that is, only a count of exactly 0. A user with exactly 1 event falls into the next bucket, 1-2, not 0-1.
Because no user in this analysis can have a count of 0, the 0-1 bucket is always empty, regardless of your data.

> [!TIP]
>
> To see a clean distribution of actual usage frequency, set **Distribution bucketing** to **Custom** and set **From** to 1 instead of 0. The buckets are generated from the **From**, **to**, and **interval** values, so starting at 0 always produces an empty first bucket.

## How to Find Users With Zero Events
Behavior analysis cannot surface users who never performed an event, because it analyzes only the users who did. To find and act on that zero-event cohort, use segmentation instead:
1. Go to **Segment** > **Create segment** and select **Filter users by**.
2. On the **User behavior** tab, select **Has Not Executed** and choose your event — for example, **App/Site Opened**.
3. Set the timeframe you want, for example **in the last** 7 **days**.

4. Click **Show count** to check the size of the cohort, then save the segment.
Use this segment directly for analysis, or to build a re-engagement campaign that targets users who have not performed the event.
# Why does the behavior analysis show the In-App shown event after delivery, but the campaign performance chart doesn't?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-does-the-behavior-analysis-show-the-in-app-shown-event-after-delivery-but-the-campaign-performance-chart-doesnt
Why In-App shown events appear in Behavior Analysis after delivery but not in the campaign chart — event time vs. server received time.
## Problem
* The behavior analysis for an In-app Messaging campaign set to deliver on a particular day displays the In-app shown event for days after delivery. 
* However, the Campaign Performance chart in the campaign shows only impressions on the delivery date. 
## Explanation
This discrepancy is due to the difference in time considered for Campaign Impressions and the Analyze Module.
* Campaign Impressions are based on *Event Time*.
* Data in Analytics and Segmentation is based on *Event Received Time* (server time).
See the following image for reference: 
You can verify this by checking the **Event Time** and **Event Received Time** on the User profile. For more information, refer to [Event Time and Received Time](/docs/user-guide/data/event-data/event-time-and-received-time).
# Why is there a discrepancy in the behavior table for ingested data?
Source: https://moengage.com/docs/user-guide/analyze/faqs-analyze/why-is-there-a-discrepancy-in-the-behavior-table-for-ingested-data
Why daily event counts in the MoEngage Behavior table differ from a source platform such as mParticle, and how ingestion logs and Analytics date backdated events differently.
## Problem
You send event data to MoEngage from a source platform (for example, mParticle), but the daily event counts in the MoEngage Behavior table do not match the counts in the source platform.
## Why This Happens
### Confirm That the Data Reached MoEngage
MoEngage ingestion logs record when data from any platform reaches MoEngage servers. These logs are accessible only to the MoEngage team. To verify raw ingestion for a specific date range, raise a request with MoEngage Support or your Customer Success Manager, and they check the logs on your behalf.
If a given day shows no data in the logs, either the requests never reached MoEngage, or they arrived and failed validation.
### Logs and Analytics Record Backdated Events Under Different Dates
* Logs record an event under the day it was **received**. For example, 1,000 events for January 1 that you send to MoEngage on January 10 appear in the logs under January 10.
* Analytics (the Behavior table) and Segmentation record and analyze those same events under **January 1** — the original occurrence date of the event, not the date it was received.
* This split is expected behavior, not a defect: logs reflect the ingestion date, while the Behavior table and Segmentation reflect the event date.
* If your source platform groups the same events by different date logic (for example, its own processing date instead of the event date), you see a day-level mismatch against the MoEngage Behavior table, even when the totals reconcile after the backdated data finishes syncing.
> [!NOTE]
>
> For historical or backdated data sent through the API, MoEngage logs reflect the time the event was **received**. Analytics and Segmentation use the **original occurrence time** of the event for analysis.
## What to Do
* To verify raw ingestion for a suspected gap, contact MoEngage Support with the date range. Ingestion logs are not self-serve.
* When you reconcile counts against a source platform, compare by event date rather than by processing or received date, so that the comparison matches how the MoEngage Behavior table and Segmentation attribute the data.
* If a mismatch persists beyond the expected backdating delay, contact MoEngage Support to investigate further.
# Accessible Campaigns in MoEngage
Source: https://moengage.com/docs/user-guide/campaigns-and-channels/getting-started/campaign-content/accessible-campaigns-in-moengage
Design accessible marketing campaigns in MoEngage that comply with WCAG guidelines and the European Accessibility Act for inclusive user outreach.
# Overview
Digital accessibility ensures your campaigns are designed so people with disabilities can effectively perceive, understand, navigate, and interact with them. The Web Content Accessibility Guidelines (WCAG) view disability as often arising from a mismatch between an individual's abilities and a product's design. This means inaccessible digital content can create barriers for users with various impairments (visual, auditory, motor, cognitive). With the European Accessibility Act (EAA) effective June 2025, prioritizing accessibility is vital for compliance, inclusive engagement, and reaching everyone in your audience.
Digital accessibility ensures that marketing campaigns are usable by everyone, including individuals who use assistive technologies. This involves designing campaigns so they can be perceived, understood, navigated, and interacted with by all potential customers.
Key considerations for digital accessibility include compatibility with:
* **Screen Readers:** Software such as TalkBack for Android and VoiceOver for iOS, which vocalize on-screen content for users with visual impairments.
* **Keyboards:** Allowing users to navigate and interact with content using only a keyboard, without a mouse.
* **Magnifiers:** Enabling users with low vision to enlarge text and images without loss of content or functionality.
# Accessibility at MoEngage
MoEngage is committed to empowering you to create inclusive and accessible experiences for all your users. We provide tools and features that make it easier for you to implement best practices across all your channels: Push, In-app Messaging, Email, On-Site Messaging (OSM), and Cards. This guide outlines these features and how you can use them.
# Why Prioritize Accessibility in Your Campaigns?
Building accessible campaigns offers you several key benefits:
* **Legal compliance:** You can adhere to legal mandates like the European Accessibility Act (EAA), which helps avoid potential penalties and ensures market access.
* **Expanded reach:** Your campaigns become understandable and usable by a wider audience, including millions of people with diverse abilities.
* **Enhanced user experience:** Accessibility improvements often lead to a better experience for all users. Clearer text, logical navigation, and alternative content formats benefit everyone.
* **Improved brand reputation:** You demonstrate a commitment to inclusivity, which can significantly enhance your brand image and foster customer loyalty.
* **Better campaign performance:** By reaching more users effectively, your accessible campaigns can lead to improved engagement rates and ROI.
# Core Principles for Accessible Campaigns
As you design your campaigns, keep these fundamental principles in mind:
* **Sufficient color contrast:** Ensure there's enough contrast between text and its background. This helps people with low vision or color blindness read your content. Aim for the Web Content Accessibility Guidelines (WCAG) 2.1 Level AA standard, which requires a minimum contrast ratio of 4.5:1 for normal text. MoEngage default templates will aim to meet these standards.
* **Logical content structure:** For content like emails or certain in-app messages, a clear and logical structure helps screen readers and other assistive technologies present your information effectively.
* **Full keyboard accessibility:** Make sure users can navigate and operate all interactive elements (like links, buttons, and forms) using only a keyboard. This is essential for users with motor impairments.
* **Clear and actionable labels:** Provide descriptive text for buttons and links that clearly indicates their purpose or destination. For example, use "Shop Now" instead of a vague phrase like "Click Here."
# Making Campaign Elements Accessible
Let's explore how you can address accessibility for common elements within your MoEngage campaigns. The elements are divided into the following categories:
* [Text and typography](#text-and-typography)
* [Images, logos, and media](#images-logos-and-media)
* [Interactive elements and dynamic content](#interactive-elements-and-dynamic-content)
* [Custom HTML](#custom-html)
## Text and Typography
Clear and adaptable text is foundational to accessible communication.
* **Use readable fonts and sufficient size:** Choose clear, legible fonts for all your content. While MoEngage provides various tools, ensure your custom designs also prioritize readability. When you're crafting content in the MoEngage for Push Notifications, In-app Messaging, Emails, On-Site Messages, or Cards, stick to our standard, legible font options. For body text, a good rule of thumb is to aim for at least 16px to ensure comfortable readability for most users. You'll find font and size selectors directly in the text editor for each campaign type.
* **Support font size scaling on mobile devices:** MoEngage is designed so that your campaign text respects the font size settings users choose on their mobile devices.\
For In-app Messaging and other mobile campaigns, MoEngage handles text display as follows:
* **Font size adherence:** Text automatically scales to match the font size settings configured on the user's device.
* **Full-screen messages:** When content in a full-screen In-app message exceeds the available viewport, MoEngage automatically enables scrolling to prevent content truncation.
* **Non-intrusive formats (nudges):** The layout for nudges adapts to accommodate varying text lengths. If the content overflows the component's boundaries, MoEngage enables scrolling within the nudge, while its position on the screen remains fixed.
* **Write actionable link and button text:** Always use descriptive text that makes sense even when read out of context.
Important considerations for scaled text:
* For **full-screen in-app notifications**, MoEngage automatically enables scrolling if increased text size causes content to overflow. This ensures all text remains accessible.
* For **non-intrusive notifications (nudges)**, the layout will adapt to text size changes, with scrolling enabled if needed, while maintaining the nudge's original position.
## Images, Logos, and Media
Visual content needs textual alternatives to be accessible.
* **Provide alternative text (Alt Text) for visuals:** Alt text is a textual description of an image for users who cannot see it, such as those using screen readers. It's crucial for conveying information and context. You should add meaningful alt text for all images, GIFs, and logos that convey information across your campaigns. Purely decorative images might have empty alt text, but ensure they genuinely serve no informational purpose. For more information on adding alt text, refer to [Channel-Specific Accessibility Considerations](#channel-specific-accessibility-considerations).
* **Character limit:** Aim for concise and descriptive alt text, generally up to 150 characters.
* **Personalization:** Alt text fields in MoEngage support personalization, allowing you to tailor descriptions dynamically.
* **Describe context for actionable images:** If an image functions as a link or button, the alt text should describe both the image content and the action (for example, "Special offer on summer dresses. Tap to view collection.").
* **When alt text might be handled differently:** For some standard images, like small app icons or "image loading" placeholders, the system may handle alt text automatically.
* **Utilize default alt text for static UI elements:** MoEngage provides default, localized alt text for common interface elements like close buttons ('X') or navigation arrows.
* **Include transcripts for audio and video:** For any pre-recorded audio or video content in your campaigns, you must provide a synchronized transcript and/or captions. This is particularly important for in-app messages and emails containing multimedia. Transcripts make your audio/video content accessible to more users, including those who are deaf, hard of hearing, or in noisy environments.
## Interactive Elements and Dynamic Content
Ensure your interactive components are usable by everyone.
* **Make dynamic content understandable:** For elements that change, like countdown timers, MoEngage helps make them understandable to assistive technologies.
* **Push inbox structure**\*:\* The way notifications are structured in the Push inbox is designed to improve navigation for screen reader users.
* **Enable full keyboard navigation:** MoEngage ensures interactive elements are reachable and operable using only a keyboard.
* **Web (On-Site Messages, Web Push):** Users can close these notifications or pop-up windows using the Escape (ESC) key, move between all links, buttons, and form fields using the Tab key.
* **Mobile (In-Apps, Mobile Push):** Ensure the close button (often an "X" icon) has an accessible text label (for example, "Close," "Close Popup," or "Dismiss") that is announced by screen readers.
* **Cards**: Keyboard users can navigate category tabs (for example, "All," "Promotional") within the Cards module using the arrow keys, Tab, Home, and End keys.
* **Manage user focus effectively:** Proper focus management guides users, especially those using keyboards or screen readers.\
Guidelines for focus on Pop-up windows and Modals (Web: On-Site Messages, Cards; Mobile: In-Apps):
* When a pop-up, modal, or on-site Message appears, keyboard focus automatically moves to the first interactive element within it.
* For **full-screen or intrusive pop-up windows**, focus will be "trapped" inside, meaning keyboard navigation stays within the pop-up. This does not apply to non-intrusive banners or nudges.
* When the pop-up/modal is closed, focus will return to the element that originally triggered it.
* When an In-app message appears, screen readers reliably announce its presence and shift focus to it.
* **Ensure adequate touch target size on mobile:** Make all interactive elements (buttons, links, icons) large enough to be easily and accurately tapped, especially on touch screens. Ensure your interactive elements (buttons, links, icons) are not too small or crowded. A minimum size of 44x44 pixels is a good guideline for iOS and 48pt for Android. Ensure your buttons and clickable areas are not too small or crowded. Visual elements like pin icons or carousel dots that aren't meant to be tapped don't need to meet these touch target size considerations.
* **Provide clear labels for all interactive elements:** Beyond alt text for images, make sure all controls (buttons, form fields, and so on) have clear, concise labels.
## Custom HTML
MoEngage allows you to use custom HTML for certain campaign types, such as In-app Messaging or On-site messaging. While this offers flexibility, it also means you take on more responsibility for ensuring the accessibility of your custom code.
* **Semantic HTML**: When writing custom HTML, always use HTML elements for their intended purpose (semantic HTML). For example, use `