Ready to take your push notifications to the next level? Use Taplytics' integrated push notification service to immediately get in touch with your users at exactly the right time.

In general, push objects consist of five main elements.

notificationobjectrequired - The actual notification that should be sent to each device.
notification.alertstringrequired Notification message that will be seen by the user. Note: this becomes optional if custom_keys has been set.
notification.time_to_livenumberoptional Seconds for which we will attempt to deliver the notification. Slightly different per platform, please read Google's and Apple's documentations on it.
imageobjectoptional Image data that specifies this push as a rich image push. Images must be less than 10 mb. Requires iOS 10, Android 4.4 or newer and Taplytics iOS SDK 2.19.0, Android SDK 1.18.0 or newer.
image.urlstringoptional The url pointing to the image that should be used for the image push. Image file extension must be .jpg, .jpeg, or .png
image.tl_cdnbooleanoptional Specifies whether the provided image should be re-uploaded to the Taplytics CDN for delivery. Set to false to send the push using the original URL.
filtersarray of objectsoptional - The audience that the push notification is directed towards. If not specified, push will send to all users.
custom_keysobjectoptional - An object of keys and values that will be included in the notification payload that will be sent to the device.
filter_duplicate_contentbooleanoptional - Automatically prevents multiple API push requests with the same message content from delivering multiple notifications to the same user within a 15 minute window. Defaults to true.
scheduleobjectoptional - Contains time object of when the push notification will be sent. If not specified, it will be immediate.
productionbooleanoptional - Determines whether your push notification will go to real users or to a Sandbox. Defaults to false.
is_silentbooleanoptional - If true, push notifications will be sent as a silent background push. No notification will be presented to users.
badge_countnumberoptional - Allows you to change the badge number via the REST API. Setting it to 0 would remove the badge count altogether.

Audience Selection:

To define the audience for your push notification, you can either brodcast your push notification to all clients, or target specific clients. If you wish to send to all users, do not specify any filters.

Filter Fields:

  • The filters field is an array of objects. These objects have the following fields.
typestringThe type of field by which you wish to filter, possible options can be found in the next table below
comparatorstringThe operator used to compare the given values and those of your users. Can be "=", "<=", ">=", "!="
valuesarrayAll the values you wish to match your users by. A user will be part of the filter if ANY of the values specified here match the type using the comparator.
dataKeystringIf you are filtering on custom user data, this field specifies the key of the custom data that you wish to compare. NOTE: only specify this field if the type is equal to "custom_data"

Filter Types:

In order to target specific subsets of your userbase, you will need to use one of the following targeting identifiers for your type field:

"an_version"The Android versions by which you will filter. If no "ios_version" filter specified, it will only send to Android
"ios_version"The iOS versions by which you will filter. If no "android_version" filter specified, it will only send to iOS
"os"The OSes you wish to send to. Only use if you are not already specifying versions for the desired OS. Possible values are "iOS" and "Android"
"id"The IDs of the users that you wish to send to
"email"The emails of the users that you wish to send to
"custom_data"Your custom defined custom data for the user by which you will filter. Only works on top level fields (no nesting). NOTE: if using this type, a dataKey field must also be specified in the filter
"gender"Gender of the users you wish to send to (only works if you have specified this on your users beforehand)
"user_id"Custom user IDs by which you can filter
"age"The age of the users by which you can filter
"app_lang"The language of your user's app by which you can filter
"country"The country of your users by which you can filter
"device_model"The device models of your users by which you can filter
"push_token"Target a specific device by unique push token
"push_token_sandbox"Target a specific dev device by unique push token
Examples - Filters:
"filters": [{
    "type": "an_version",
    "comparator": ">=",
    "values": ["5.0.0"]
    "type": "ios_version",
    "comparator": "!=",
    "values": ["8.0.1"]
    "type": "country",
    "comparator": "=",
    "values": ["Canada", "US"]
    "type": "custom_data",
    "comparator": ">=",
    "values": [16],
    "dataKey": "dollars spent"

This filter will send the push notification to users who:

  • Have an Android phone with a version greater than or equal to 5.0.0 OR have an iPhone with versions not equal to 8.0.1
  • AND are currently in either Canada OR the US
  • AND have a custom data field dollars spent with a value greater than or equal to 16

With great power comes great responsibility. Though this filter language is powerful, since you have so much control over how the data is manipulated, if used incorrectly there could be unintended consequences:

Examples - BAD Filters, DO NOT DO THIS:
"filters": [{
    "type": "ios_version",
    "comparator": "!=",
    "values": ["8.0.1", "8.1.3"]
    "type": "app_lang",
    "comparator": ">",
    "values": ["en"]
  • Since a user is matched if they fulfill ANY of the values in the array, this will send to every iPhone device. If they are on 8.0.1, then obviously they are NOT on 8.1.3. They will pass the check and thus the message will send to them. To avoid this unintended behaviour, create multiple filters per version
  • Here you are using a 'greater than' comparator on a string. This will try and match on numerical ASCII values and will produce unexpected results.
Scheduled Messages:

Push notifications can be sent out immediately, or they can be sent out at a specific time. Additionally, they can be sent out at a standard time to everyone, or they can be sent out based on the audience member's local time.

timestringoptional The UTC at which your push notification will be sent to every user. Format is UTC: YYYY-MM-DDTHH:MM:SSZ.
local_timestringoptional The time in any given audience member's timezone at which you want to send the notification. Format is UTC, with no timezone included: YYYY-MM-DDTHH:MM:SS.

One of these two strings must be provided. If they both are, local time takes precedence. All times must be in the future.

    "schedule": {
        "time": "2015-11-05T13:15:30Z",
        "local_time": "2015-11-05T13:15:30"

This will get sent at each user's local time.