CleverTap User Docs

Welcome to the CleverTap User Docs. You'll find comprehensive guides and documentation to help you start working with CleverTap as quickly as possible, as well as support if you get stuck. Let's jump right in!

Push Notification

Push notifications are brief messages you can send to your mobile app users. They appear in the notification tray, or the notification inbox of the user, as shown below.


Push notifications enable you to communicate brief yet important alerts to your users. CleverTap’s rich segmentation and powerful infrastructure enables sending time-sensitive, relevant, and personalized push messages in large-scale.

The Push module on the CleverTap dashboard (under “Campaigns”) makes it easy to set up push campaigns to all your users or specific user segments. These segments can be created on the basis of past or live user behavior, user properties, or a combination of user behavior and properties.

Once a campaign has been sent, you can view detailed reports on how many messages were sent, how many users clicked on them, and how many users converted as a result.

Push Campaign Creation

Step 1: Create a New Campaign

To start creating a push campaign, first go into “Push” under “Campaigns” on the CleverTap dashboard, then click on “Create New +” on the top-right.

Step 2: Define the Who

The next step would be to indicate the target audience for your push campaign. You can target your push campaign to a user segment you create on the fly (by clicking on “Create ad-hoc segment”) or use a previously saved user segment (from the list of pre-saved segments shown in the table), as shown below.

If you choose to create an ad-hoc segment, you can now select a type of segment on which to base your push campaign. The target can be created either on the basis of past user behavior and/or user properties, or live (ongoing) user behavior (the latter is useful to send out real-time, triggered push campaigns).

For instance, we can choose to create a live “Inaction within time” campaign that will target users as soon as they add a product to cart but do not finish transacting within 10 minutes, the golden window within which most users transact on our iOS and Android app platforms.

On this basis, in the next step, here is how we would set up the “WHO”. You can choose to send this campaign to all users who qualify, or just a portion of the users who qualify, under “Campaign reach”.

You can also further check the “Filter this stream based on these users’ past behavior/user properties” checkbox to filter by any past user behavior or user properties. For past behavior campaigns, you will also have an option to “Estimate Reach” to see how many users qualify for the campaign criteria and are reachable via mobile push as of now.

Filter by User Properties

Let's say you want to send a push notification to people who live in California, whose preferred language is English, and who are between the ages 25 to 40. Using the Common Properties Filter feature in CleverTap, you can segment your campaign to only reach users who meet this criteria.

The table below lists all the different ways you can segment your audience for a mobile push notification campaign based on their user profile properties.

Property Type

User Properties

Custom user profile properties that you define and send to CleverTap.

Customer Type = Platinum


Demographics filters include Age and Gender.

Age = 25 to 40 years
Gender = Female


User's coarse location. Filters include Country, Region, and City. CleverTap's SDK can automatically detect this from the user's IP address.

Country = United States
State = California
City = San Francisco

Geography Radius

User's exact location. You can select a city, and then define the target radius. You can also select multiple cities. You can send this information using CleverTap's SDK. Please see the iOS and Android developer guides for more information.

Locations = San Francisco, USA; Paris, France


Reachability filters include Has email address, Has phone number, Unsubscribed email, and Unsubscribed SMS.

Unsubscribed email = No

App Fields

App Fields filters include App Version, Device Make, Device Model, OS Version, and CleverTap SDK Version. This information is sent by CleverTap's SDK for each device that has your app. This means a single user can have multiple devices associated with their user profile.

OS Version = 10

Step 3: Define the When

Then, you can set up the “WHEN” to schedule the campaign start and end, as shown below.

Past behavior campaigns can be scheduled to run:

  • On a specific date and time.
  • On multiple specified dates and times.
  • Recurring at a periodicity you set.

Live campaigns can be set up as follows:

  • In response to a user event.
  • User event/inaction combination (Example: Abandoned cart scenario).
  • Based on a date event property value of an event (Example: Reminder for upcoming travel booking).

Global campaign limits are limits you can apply to determine how many push notifications each app user receives per day. If you would like to override these settings for an important campaign, you can click on the “Don’t apply global campaign limits to this campaign” checkbox.

You can also click on the “Advanced” checkbox to specify “Do Not Disturb” (DND) hours during which notifications from this push campaign are prevented from going out, either by discarding them, or delaying delivery to after DND hours (say, 9PM to 9AM) complete.

Since past behavior campaigns can have scheduled times, you have the option to stop campaign delivery after a certain cut-off time, or even deliver at the specified time in the user’s timezone. You can read more on these here.

Step 4: Define the What

Finally, you can go on the next step that involves setting up push campaign content (“WHAT”). You will have 3 different options here.

Single Message Campaign

In this campaign, we will send the same message to all users who qualify in your target audience. This message type is best for broadcast messages and for applications that don’t vary campaign communication based on differences between properties such as language, geography, or any other user properties.

A/B Testing

Here, we will help you test up to 3 variants of a message to understand what type of message copy works best to get clicks from users.

A/B tests allow you to test up to 3 message variants on a test group, and the variant that gets the most clicks is declared the winning variant and is automatically sent to the rest of your target audience.

Creating multiple variants for a campaign (you can also auto-copy what is already present in a current variant).

In the next step, we will learn how to determine “A/B Distribution”.

Split Delivery
With Split Delivery, you can decide what percentage of your audience receives each message variant. We’ll deliver the messages in exactly this proportion for the duration of the campaign.

Campaigns Sent to Past Behavior Segments
For campaigns sent to Past Behavior Segments (grouping of users based on what they have done in the past), you have two options – launch the A/B test to a percentage of your target audience, or send out an absolute number of messages. In either case, we’ll deliver the variants equally to the test audience.

For example:

  • If you are testing three messages (Variant A, Variant B, Variant C).
  • Your Campaign Reach is 2,000,000 users.
  • You choose a Test Population of 15% of Campaign Reach (300,000 users).

Then, we will send:

  • Variant A to 100,000 users.
  • Variant B to 100,000 users.
  • Variant C to 100,000 users.

After all 300,000 messages have been delivered, we’ll calculate the winning message over this test group based on the number of click-throughs. We will then automatically send the winning message to the remainder of your target audience, which is 1,700,000 users in this example.

Note that for A/B testing, we ensure there is always an equal number of messages sent for each variant. This a there is no bias introduced during the test phase and that the best-performing message is always declared the winner.

Live User Segment (Triggered) Campaigns

With campaigns sent to Live User Segments (triggered) campaigns messages are delivered immediately when a user’s activity matches the criteria you’ve selected. For example: Send a message when the user has completed a booking or purchase. Since it’s not possible to determine the reach of triggered campaigns up front, you’ll need to decide how many total messages to send for A/B testing before a winner is declared.

For example, if you select 500 users as your test audience: We’ll alternate delivery of Variant A and Variant B as users qualify for the campaign. After 500 total messages are sent (Variant A – 250 and Variant B – 250), we’ll decide the “Winner” based on the number of clicks and continue only with this winning message for the duration of the campaign.

Deciding on a test audience for A/B Testing triggered campaigns requires some estimation. We recommend you check the total messages that were sent for similar triggered campaigns in the past to get a sense for how many users may qualify. If you select a test audience that’s too small (say 25 users), you’ll get a statistically insignificant sample. If your test group size exceeds the total number of users who ultimately qualify for that campaign, then no “Winner” will be declared and each message variant will be alternatively delivered for the duration of the campaign.

Multi-Message Campaign

If you’d like to send different message variants to your target audience based on the user-properties that they possess, this campaign type would be your best bet. Typical use-case: If you want to send a localized update to people based on their preferred language, this would be the type of campaign you go with.

Similar to creating A/B test variants, you can use the “+” button to add multiple variants based on user property value. In the example below, we have used the “Language” user property such that users with different “Language” property values will receive corresponding copies of the campaign in their regional language.

Personalization (for all campaign types)

The push notification title and message body can be personalized for every user based on specific user property or event property values. See User Profiles to learn more about user profile properties and events (dynamic replacements).

To invoke the personalization menu, type “@” in the title or the text fields while typing out the push notification message.

Emojis can be included in your push notifications, just like regular text. You can use the CleverTap emoji picker, or copy-paste emojis from Emoji keyboards online.

Adding in dynamic replacements in the push title and body. Notice a preview of the push notification is available to see below.

Adding in emojis using CleverTap’s in-built emoji picker.

In the “Advanced” section, you have the ability to add in rich media such as images/image carousels, gifs, and even videos using publicly-hosted media URLs. See previews on the right-hand side as you add in the media.

Rich Push Notifications

You can add in a fixed (or with dynamic replacements) media (image or video) URL for both your Android and iOS push notifications.

You can add in an image carousel, with each image having its own caption, sub-caption, and call to action URL (fixed or with dynamic replacements), to your iOS push notifications.

You can easily add default or custom (fixed or with dynamic replacements) sound files to your Android and iOS push notifications.

You can add deeplinks (fixed or with dynamic replacements) to the overall Android or iOS push notification to enable users to access specific screens within the app upon click.

Raising Notification Viewed Event for iOS

To be able to raise the Notification viewed event for iOS, it is mandatory to enable the mutable-content under the iOS section of the campaign creation
To understand how to enable Notification Viewed for your account, please visit our developer docs

Add Custom Actions to Android Notifications

We have added a simple way to insert button-like actions right into your Android push notifications to urge users to respond to your calls to action.

Once set up, the various calls to action would appear below the push as seen below.

On Android, you can also set a priority level for each notification to influence how prominently it gets displayed. The higher the priority, the more noticeable it will be.

Maximum Priority
Use for urgent, time-sensitive notifications. These notifications will get higher placement inside the user’s tray and appear as heads-up notifications.

High Priority
Use for important communications that require a extra attention such as chat messages. These will also appear as heads-up notifications and be given a higher priority in the user’s tray.

Default Priority
Use for the majority of your messages that are not time-critical such as general notifications and promotional offers.

Setting Priority for Notifications with CleverTap
You can set these priority levels right from the CleverTap dashboard as you create your Android push campaigns.

Have your app running our latest SDK (versions v3.1.4 or higher) and follow the steps outlined above to send actionable push notifications and set notification priority on Android devices.

Step 5: Test & Schedule Campaign

Once you are all done setting up the content of your campaign in “WHAT”, you have the option to send a test push notification to any CleverTap user profile you have marked as a “Test profile”.

Post-testing, when you are satisfied with the appearance of your campaign, you can “Continue to Overview” to view your campaign summary, the hit “Schedule notification”.

Push Campaign Throttling

You can also throttle the rate at which CleverTap will deliver push notifications under Settings → Global Campaign Limits. If your user base is large and all users receive and click on a push notification at roughly the same time to open the app, you could experience a significant (unwanted) load on your systems.

Push Campaign Throttling is used to meter how quickly CleverTap will deliver your notifications.

For example, if your reachable audience for a campaign is 500,000 users and your back-end systems can only support up to 20% of them, you can set a throttle limit to 100,000 notifications per 15 minute interval. The entire campaign will then deliver in 1 hour 15 minutes.

Viewing Push Campaign Stats

Once the campaign has gone out, you can view its stats by going into “Push” under “Campaigns” on the CleverTap dashboard and clicking on the campaign of interest to see its deliveries, clicks, and conversions.

Single Message Campaign

A/B Testing

Multi-Message Campaign

You can view the overall performance of the campaign and analyze whether you’ve achieved your marketing goal.

You can also split the campaign stats and view the performance of each variant of the campaign.

Optimizing delivery by Push Amplification

Push notifications are a great way to engage customers but they suffer from the issue of low deliverability on certain device manufacturers
Couple with this, more and more users chooses to opt-out of Push notifications

To counter this problem, you have now Push Amplification at your disposal. Push amplification enhances the delivery of push notifications to devices that missed receiving it.

To enable this feature, go to Settings -> Push Notifications -> Turn on the push amplification toggle. The final state should look as illustrated below:

Toggling push notification amplification

Once you turn 'ON' push amplification, all the push campaigns created henceforth will be amplified. Same goes for when you turn it 'OFF'.

Once push amplification is turned ON, your campaigns will reach more users through your push notifications. You can check this boost numbers in your push campaign stats page.

Push Amplification can be achieved via retrying the Push message as is (where messages are suppressed by the device) AND App Inbox (where the user has chosen to DND the push messages)


Each message stored on the CleverTap platform for Push Amplification is accounted for as a user event.

Optimizing delivery by sending to App Inbox

Apart from push amplification, you can further increase delivery of push notification by sending a copy of the same message to App Inbox.

To send a copy of the push message to App Inbox, click the checkbox that appears at the bottom of the message builder (what section) of push notification.


App Inbox also exists as a stand-alone channel. Read more about it here.

  • You will see a section to customize the same push message for App Inbox.
  • You can change the title color, message color and background color and also choose to add filter tags which will classify your message into tabs.
    ** Know more about tags here.
  • You will have to set a TTL for App Inbox message in the setup section, which can be done like this.

Push Amplification + Inbox Stats
Stats for push messages copied to App Inbox can be viewed in the push stats page. The % boost represents the % of messages boosted by App Inbox as compared to total of messages sent via App Inbox and Push Amplification

There is a separate for App Inbox to represent the stats for the copied messages

Push Notification

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.