Leanplum's user guides and developer documentation.

Leanplum Documentation

Leanplum's user guides, SDK setup, API docs, and more resources are here to help you get the most out of A/B testing, Campaigns, Messaging, and Analytics.

Push notifications

Compose, personalize, segment, and send a push notification. Customize with dynamic deeplinks, advanced options, and iOS options

Before you can send your first push notification, there are a few things you'll need to do. Be sure to follow the steps outlined in our developer docs and Set up push notifications.

Create your first push message

Once push is set up, go to the Messaging dashboard and click Create Message to start a new message. Select push notification as the message type.


Under Compose, in the Message section, type in the message you would like to use, like "We just added new content, come check it out!"


In the Message Composer, you can insert dynamic Leanplum values, like User Attributes, Event values, and other data tracked in Leanplum. This data is specific to each user, and will be inserted dynamically by Leanplum when we send the push notification.

You can use the Insert Value tool in the Message Composer (the {{ button), or manually type in variables using the Jinja templating language, which uses the handlebars-standard double curly braces {{ to indicate and enclose a dynamic element.

Hey {{ "first_name" value }}, it's time for your next workout!

Learn more about how to personalize your message with dynamic content in Personalize a message.

Segment your message for different audiences

Most of the options for push notifications can be segmented within the overall targeting of the message. This means that you can send the message to a group of users using targeting, and within that group, segment content and other options to sub-groups A-1, A-2, A-3, etc. For message content, this allows you to send slightly different messages to different user groups based on each segment you select.

For example, you can create a segment whose language is "Spanish", and localize the greeting. You could also segment the sound of the push notification, or the Open Action. You can also set data variables (above) to different values based on a segment.

Select the + button next to your message content or another composer setting to create a new version of your message for a separate audience segment.

Hover over the field to reveal the +.

Choose an Open Action

The Open Action is what will occur when the user opens the notification. The default "No Action" takes them to your app's main screen, but options like In-App messages or Open URL can make the interaction much more personal.

Leanplum offers the following actions:

  • No Action. The user will be led to the app's main screen.
  • In-App Messages (7 options). The user will be led to an in-app message you setup in the Message Composer. Options include Alert, Confirm, Center Popup, Web Interstitial, Push Pre-Permission, Interstitial, or Register for Push in-app messages. You can configure the message right in the Message Composer after selecting it as the Open Action.
  • Open URL. The user will be led to the URL you enter. Options include web pages or deeplinks within your app. URLs can also be personalized using event parameters or user attributes using the process outlined in “dynamically customizing text”.
  • Deeplinks. A deeplink is a direct link from the notification to a specific location inside your app. For example, let’s say you have an ecommerce app, and want to send your users a push notification when there is a deal on a popular item. You might have a deeplink schema like this, where “productID” can be replaced with an actual ID to send a user directly to a specific product page:
` ecommerceApp://product/productID`
  • Dynamic links. You can also make your links, even deeplinks, dynamic based on a User Attribute or Parameter values.

Using Leanplum’s Insert Value {{ functionality, you can populate the productID dynamically but you must send the product ID as a parameter value of the event which triggers the push notification. For the example above, you might want to send the user to a product they have previously viewed. You would put in a deeplink that looks like this:

     ecommerceApp://product/{{Parameter “productID"}}

You now have a message that will always lead a user to the product they were recently viewing, resulting in a highly personalized experience.

Schedule delivery

When configuring a message, delivery time is one of the most important things to consider. Leanplum provides a variety of methods for message delivery.

Let’s go through the delivery options based on the most common goals. Keep in mind that regardless of the delivery type, each message will only be delivered to users that fit the target you’ve set.

  • Immediate: “I want to send a push notification right away”
  • Scheduled: “I want to send a push notification on October 2nd, 2016”
  • Optimal time: This uses a Leanplum algorithm to send the message to each user during the time of day that they have been most active, increasing the likelihood of engaging with the notification. Read our case study on the benefits of using Optimal time for your scheduled push notifications.
  • User’s timezone: This delivers the notification at the same time, relative to each user's timezone.
  • Your local timezone (relative to GMT): For example, Pacific daylight savings time is shown as “GMT-7 time”.
  • UTC: This delivers the notification at the exact same time, all over the world.
  • Triggered: “I want to send users a push notification after they do something specific in the app”
  • Triggered locally: “I want to send users a push notification after they enter a geofence”


Locally triggered push notifications do not work with our Quiet Hours feature. This is because the send is controlled by the local trigger, and not Leanplum's servers.

  • Manual: “I want to bypass Leanplum’s automated delivery options and use a server-to-server call to trigger a push notification”


If you set Quiet Hours, and the message delivery time falls into those hours, the message will be sent as soon as the Quiet Hours period has ended (i.e., if your Quiet Hours end at 6 am and a message was scheduled for 5:45 am, it will be sent at 6:01 am).

Test a push notification

The best way to test a push notification is to click Send Preview in the Message Composer. This sends the message only to your registered test devices, and allows you check that any jinja or personalized text in your message is working as intended.

More options

To reveal additional options and settings, select Show All in the upper right corner of the Message Composer. This will reveal iOS options for badge counts and other advanced options.

iOS options

There are several iOS-only options you can customize for your push notification. These are hidden in the composer by default, but can be found by clicking "Show All" above the Compose section.

  • Badge: This places a numeric badge on the home screen app icon when a push notification is sent. It will be set to the number you provide in the dashboard (not incremented by it). To increment it by your number instead, see our developer documentation. To clear the badge, leave the message blank and provide 0 for the badge.


Insert value {{ set badge with Jinja }}

You could use the handlbars/insert value logic to set the badge count. For example, if you have a user attribute set for notifications, like unseen_notifications you could add {{ (userAttribute.unseen_notifications|int) + 1 }} to the badge field. This would automatically add one to the user's current badge count.

  • Category: Requires iOS 8 and higher. This is the category identifier which is used to display user actions associated with the notification. This requires categories to be set up in your app when registering for push notifications. An example of a category would be SOCIAL, which shows Like and Share buttons.
  • Custom actions: If a category identifier (above) is set, these are the actions defined within that category. To build a custom action, hover over the column and click the + to add a new variable. Enter the name of the category action (defined within the category) and then choose a Leanplum Open action. For the social example above, you could add a new property with the name SHARE with an open URL action to deep link to the Share screen.
  • Preload content: Requires iOS 7 and higher, and the "Remote notifications" background mode. If the app has permission to run in the background, this causes the app to wake up and perform any tasks necessary to preload content associated with the notification. It defaults to true. Setting it to false prevents the content from being preloaded.
  • Sound: The name of the sound file that you would like to play as the alert sound for the notification. The file must first be included in your application for use, and follow Apple's guidelines.
  • Title: Adds a short description of the reason for the alert. See Apple's docs for more info.
  • Subtitle: Adds a secondary description of the reason for the alert. See Apple's docs for more info.
    See Apple's example image of the Title and Subtitle placement.

Android notification channels

See Android notification channels for more information.

Advanced Options

Also hidden by default, these options offer more advanced control of the experience and allow you to tie the notification into features inside your app's code.


This allows you to send custom key-value pairs with your push notifications that can be read by your app when the notification is opened. You can also segment the values of the variables you send, which can be fairly powerful, and allow you to essentially pass the segmentation to the code in your app.

For example, you can use the Data field to customize your push notification titles. When you send a push notification to Android devices, Android automatically uses your app's name as the title of push notifications.

If you'd rather use a different title, add a text field called "title" under Data. Type your push title into the field on the right ("Title Android").

A best practice is to keep push titles brief (5 words or fewer). Or, you can choose to have no title at all by leaving the title field empty.


Send yourself a preview

The on-screen preview device will not display your custom title — data fields aren't evaluated until the message sends. To see how your push title will look, preview the message on your test device.

Note that you're only customizing the title for this push notification. To apply a consistent change (so you don't have to perform this step every time), use the push notification customizer.

Mute inside app

When this box is checked, the push will be muted for users who are already inside your app. This can help you create a seamless user experience and avoid your users feeling spammed. "Muted" means the push will still deliver, but won't pop up across the screen.

Android: When muted, the push won't pop up at the top of the screen for users who have the app in foreground at the time of send. If mute is not checked, the push will deliver as usual regardless of whether or not the app is foregrounded.

iOS: When mute is checked, the push won't show on the screen if your app is foregrounded (being used).
If mute is not checked and the app is foregrounded, the push still won't display unless the message has a custom open action, such as "open URL" or "deeplink." In these situations, the push may appear as an iOS in-app alert, instead of the usual push format.

Push notifications with the default open action of "open the app" will not send to users who already have the app open, regardless of whether or not mute is checked.

Updated about a month ago

Push notifications

Compose, personalize, segment, and send a push notification. Customize with dynamic deeplinks, advanced options, and iOS options

Suggested Edits are limited on API Reference Pages

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