1. Developer Guide
  2. API
  3. Push
Push API

Push API is used to:

  • Create Campaigns (targeting all users or a group of users) to send notifications.
  • Target a single user using a unique user attribute
  • Personalize payload for each user.

API Endpoint

API Endpoint
POST https://pushapi-0X.moengage.com/v2/transaction/sendpush

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.

Request Headers

HTTP
'Content-Type':'application/json'

Request Body

  • appId (Mandatory: Yes)
    • APP ID provided by MoEngage to identify the specific app. You can find it in the MoEngage Dashboard. We have revamped our settings UI on the Dashboard; you can find the APP ID in the following navigations in the revamped and old UIs:
      • Settings -> Account -> APIs -> Push tile.
      • Settings -> Transactional Push Settings on MoEngage Dashboard.
    • MoEngage recommends that you test API integration on Test Environment. The App Id for TEST ACCOUNT is suffixed with _DEBUG.
  • campaignName (Mandatory: Yes)
    • Used to check the campaign details/statistics on the MoEngage dashboard. Campaign name should be unique for All Users & Custom Segment campaigns. For User Level API requests:
      campaign name should be the same if multiple requests belong to a single type of campaign.
      campaign names should be unique if all the API requests belong to different campaign types.
      NOTE: API automatically creates a campaign with the given name. You need not create a campaign from the dashboard to use the name.
  • campaignTags (Mandatory: No)
    • Used to add more context to campaigns. Context can be descriptive names or campaign themes such as onboarding, retention, country, all users, and so on. Tags can also be used to filter campaigns or identify the behaviors of users who received these campaigns. The list of tags should be passed in this field.
    • For example, 
      “campaignTags“ : [“Transactional“, “Accounts“]
  • signature (Mandatory: Yes)
    • A signature is required to verify if the client is authorized to make the API call. It is generated from a hash of Campaign Name, App Id and API Secret. MoEngage uses the SHA 256 method to generate this hash. You can find the API Id (or App Id) & API Secret in your MoEngage Dashboard under Settings > Transaction Push Settings. 
  • requestType
    • The value of this key is used to indicate the intention of an API request. The default value is push.
  • targetAudience (Mandatory: Yes)

    • The target segment for the campaign. It can have one of the following values

      • All Users: to target all users of your App/Website

      • Custom Segment: to target pre-created user segments. You will have to use the MoEngage dashboard to create/manage custom segments. Please note that the custom segment name should exactly match the name of the target segment on the MoEngage dashboard

      • User: to target a user with an attribute

  • customSegmentName (Mandatory if the targetAudience value is Custom Segment)
    • Name of the custom segment as saved or defined on the dashboard
  • targetUserAttributes (Mandatory if targetAudience value is User)
    • In case the target audience is the User, you can target the user via user properties/attributes. You have to send the following parameters to find the user
      - attribute
      - comparison parameter
      - attribute value
      Note:
      For API Requests where the target audience is a specific user, if a campaign with the given name already exists, existing campaign data corresponding to the given campaign name will be used for sending notifications.
      Any edits in other parts of campaign data within the API request parameters will be ignored.
      If any changes are required in the campaign data, please change the name of the campaign in API Request, so that a new campaign is created.
  • targetPlatform (Mandatory: Yes)
    • To choose the platform devices being targeted by your campaign. Push API allows you to target users on Android app, iOS app, and Web platforms. You can target one or more platforms. If you are sending Web (Chrome) push notifications through the API, you should choose Web as the platform.
  • payload (Mandatory: Yes)

    • Enables push messages and rich content (image, sound and so on) sent to your customers. Do the following:
      1. Configure messages separately to the target platforms you want to send.
      2. Include payload for at-least one platform in your API request.

    • Rich Content

      • The following rich content is supported on different platforms.
        ANDROID - coupon, image, sound
        IOS - coupon, sound, image, audio, video ( image, video, and audio are only supported after IOS-10)
        To use emoticons (emojis), just copy-paste it where required (ex. ❤️ )
        Note: image, video, and audio can not be used together.

    • contentAvailable
      • This is used only for the iOS platform.
      • Used for updating the iOS app's badge count with push notifications.
      • Is an Integer and can be either 0 or 1.
  • campaignDelivery (Mandatory: Yes)
    • Helps decide when the campaign should be sent.
    • All notifications targeted to a single user will be sent as soon as possible (ASAP).
    • Scheduling campaign for Later or Periodically is applied only for segmented or all users campaigns.
    • For scheduled campaigns, the timezone can be passed using the "timezone" field. This is not mandatory and in case it is not passed, then the default timezone will be set to IST (and not UTC/GMT). Here is a list of allowed timezone values.
  • defaultAction (Mandatory: Yes for Android and Web. Optional for iOS)
    • Different deep-linking options for the Android/iOS platform. You can define the action when the user clicks on the notification through this.
  • conversionGoals
    • List of conversion goals. Once set it can't be changed for a specific campaign.
      For numeric attributes, allowed filter types are:
      [ ‘is between’, ‘is less than', ‘is greater than’,is equal to' ]
  • advancedSettings
    • Advanced settings for the push include settings like TTL ( time to live), ignoreFC, countFC, and priority of the message.
  • TTL
    • If not delivered, Push Services(GCM/WEB) will retry to send the message until the TTL (in hours) does not expire. Send ‘0’ if it is not applicable to you. After TTL has expired, push notifications will not be shown to the user. The default value for TTL is 36 hours and is applicable only to Android push / Web push notifications.
  • ignoreFC
    • Allowed Values are "true" or "false".

      Note: This field is case-sensitive. Follow the case as described in the allowed values above when passing the value in the request.
      "true" value - Bypasses Frequency capping set using the dashboard and will send the notifications to everyone in the target segment.
      "false" value - Applies the Frequency cap set on the dashboard and will not send the notification after the limit is reached.
      If the key is not present, it will be treated as ignoreFC="false". While testing your API, ensure that you set this flag as "true", else you might not receive a few notifications.

  • countFC
    • Values are "true" or "false" only when ignoreFC value is set to true.
      "true" value - Only push campaigns are counted in frequency cap count.
      "false" value - Push campaigns are not counted in the frequency cap count.
  • sendAtHighPriority
    • Values are "true" or "false" only for Android push / Web push notifications. Uses GCM/FCM flag to send time critical messages with high priority and drains user's device battery more than normal messages.
  • pushAmp+
  • preCacheSegment
    • Values are "true" or "false". Applicable for scheduled and periodic campaigns. If enabled, pre-caches the segmentation, and campaign sending time will be improved. For caching, it is recommended to create the campaign at least 2 hours before the scheduled time.
  • campaignThrottleTime
    • Values are Integers (time in minutes). Push throttling allows you to control the rate of sending a push notification. The value to be passed can be between 1 and 360 (minutes).
  • campaignThrottleRpm
    • Values are Integers. The default throughput for Push API is 100K RPM. You can send either of the key-value pairs in the Push API payload, between campaignThrottleRpm and campaignThrottleTime. Both of the key-value pairs are optional.
      • If you send both, the value for campaignThrottleRpm takes precedence over the value for campaignThrottleTime.
      • If you send either of them, the value you send is considered.
      • If you do not send any of them, the value defined in settings is considered (the Limit to <> Push notifications per minute setting at Settings > Channel > Delivery Controls > Throttling > Throttling configuration > Push). If the RPM value is defined in settings, the defined value is considered. If the RPM value is not defined in settings, the default RPM for Push channel (that is, 100K) is enforced.
      • For personalized campaigns, the maximum RPM value MoEngage supports is 250K.
  •  useJinjaPersonalization
    • Values are "true" or "false". A boolean value to indicate if Jinja personalization is applied on the message payloads. It is recommended to use this personalization format for . For example, you can add the following jinja code to personalize the user name. 
      "title": "Hello {{UserAttribute['userName']}}"
  • ignoreMinimumDelay
    • Values are "true" or "false". A boolean value to indicate if Client level Minimum Delay setting is to be applied for the campaign. The default value is true, if not passed in the API.
  • additionalActions
    • Additional action buttons for Android. The buttons allowed for ANDROID are call, snooze, copy, and share. A maximum of two additional action buttons can be used at a time.

We have mentioned examples for some of the attributes.

campaignName

If you want to push updates to your users for Billing and Order Confirmation, all the push requests related to billing can have the same campaign name: “Billing Campaign” while all the push requests related to order delivery can have the campaign name “Orders Campaign”. As a result, one would be able to see aggregated stats for all related (All Billing or All Order Confirmation) API requests under one campaign name.

signature

Python code to generate the signature for your test account, use the app_id that is appropriate for your account.

PushAPI_Transaction_Push_Settings.jpg

Python 3.xPython 2.x 
from hashlib import sha256
app_id = "XXXXXXXXXXXXXXXXXXXXXX_DEBUG" #(Please refer to required parameters section)
campaign_name = "TEST"
api_secret = "XXXXXXXXXXXX" # This is the sample key. Each app has a different secret key
signature_key = app_id+'|'+ campaign_name+'|'+ api_secret
signature = sha256(signature_key.encode('utf-8')).hexdigest()
print(signature)

Generated Signature

Signature
Generated Signature: 
bc52a205a64d18d9978d9532a59f6302e2a5745bd1fda05929dd6f044a9fb7b3

targetAudience

User-based targeting is done based on fields as described in the example.
In the example, user email is used for user-based targeting.

JSON
// e.g. To target All Users
"targetAudience": "All Users",

// e.g. To target a custom segment with name: MySegment123
"targetAudience": "Custom Segment",
"customSegmentName": "MySegment123",

// e.g. To target an user with Email Id as abc@exmaple.com, it will be
"targetAudience": "User",
"targetUserAttributes": 
{
    "attribute": "USER_ATTRIBUTE_USER_EMAIL",
    "comparisonParameter": "is",
    "attributeValue": "abc@example.com"
},

Other fields used are:
for unique id use - USER_ATTRIBUTE_UNIQUE_ID
for email use - USER_ATTRIBUTE_USER_EMAIL
for mobile number use - USER_ATTRIBUTE_USER_MOBILE
for Google Advertising identifier - MOE_GAID
for iOS Identifier for advertising - ADVERTISING_IDENTIFIER
for device push token - PUSH_ID ( same key is used for android gcmId, iOS push token)

For custom attributes, targeting is done on any custom attribute along with the available fields. Set the extra key, "isCustom" to true.
comparisonParameter supports only "is" and "in" query types. (Note: The maximum number of parameters that can be added while using the "in" comparisonParameter is 50).
The following example describes the custom attribute set to true.

targetPlatform

Target Single Platform Target Multiple Platform 
//List of platforms to target
"targetPlatform":["ANDROID"],

payload

payload sample rich content 
"payload": {
    "ANDROID": { // payload specific to Android
    },
    "IOS": { // payload specific to iOS
    },
     "WEB": { // payload specific to web.
    }
 }

campaignDelivery

ASAP Schedule later Recurring Campaigns 
// send campaign asap
"campaignDelivery": {
    "type": "soon"
  },

conversionGoals

single conversion goal multiple conversion goal 
// single conversion goal 
"conversionGoals": [
    {
      "name": "amount 1", // name of the goal to be displayed in dashboard.
      "eventName": "AddedTocart", // event on which conversion should be tracked.
      "attrs": { // attributes of event.
        "filter": "is between",
        "name": "amount",
        "value": "10,100", //range to be passed as comma seperated values 
        "type": "numeric"
      }
    }
  ]

advanceSettings

JSON
// sample advanced settings

"advancedSettings": {
    "ttl": { // if not passed, all platforms will have ttl of 36 hours.
      "ANDROID": 12, // the ttl for both Android and iOS platforms are tracked in ANDROID field. 
      "WEB": 24
    },
    "ignoreFC": "true",
    "countFC": "true",
    "sendAtHighPriority": "true",
    "pushAmp+"       : "true",
    "preCacheSegment": "true",
    "campaignThrottleTime" : 5,
    "useJinjaPersonalization" : "true",
    "ignoreMinimumDelay"      : "false",
    "campaignThrottleRpm"     : 400
  }

defaultAction

JSON
"defaultAction": { // Default action when user click on notifications. 
  "type": "navigation",
  "value": "", // Value of the screen name on which re-direction should happen.
  "kvPairs" :{ // additional key value pairs to be passed while sending notification.
                       "key1" : "value1",
                        "Key2" : "value2"
             } //optional 
},

"defaultAction": { // Default action when user click on notifications. 
  "type": "richlanding",
  "value": "" ,// Rich landing url, which is a web (http/https) url.
  "kvPairs" :{ // additional key value pairs to be passed while sending notification.
                       "key1" : "value1",
                        "Key2" : "value2"
             } //optional 
},

"defaultAction": { // Default action when user click on notifications. 
  "type": "deeplinking",
  "value": "", // Deep-linking URI
  "kvPairs" :{ // additional key value pairs to be passed while sending notification.
                       "key1" : "value1",
                        "Key2" : "value2"
             } //optional 
},

additionalActions

JSON
"additionalActions": [ // List of action buttons. Maximum 2 buttons are allowed.
        {
          "type": "call",// action type
          "value": "12345678", // respective value
          "name": "Call button", // action name displayed on notification
          "iconURL": "abc" // url for icon to be displayed
        },
        {
          "type": "copy", // action type
          "value": "12345678", // respective value
          "name": "Copy button", // action name displayed on notification
          "iconURL": "abc" // icon url
        },
        {
          "type": "snooze", // action type
          "value": 5, // in hours i.e. snooze after 5 hours
          "name": "snooze button", // action name, displayed on notification
          "iconURL": "abc" // icon url
        },
        {
          "type": "share", // action type
          "value": "xyz", // text to share
          "name": "share button", // action name, displayed on notification
          "iconURL": "abc" // icon url
        }
      ]

Response

Response Code Description
200 Your request has been registered. You can check the dashboard for the campaign status.
4xx Kindly check the response for payload error information.
5xx There is something is wrong with the server, kindly retry the request after some time.

Sample Payloads 

Here are the sample payloads across different platforms (Android, iOS & Web).

Example 1

Android app iOS app web (Chrome Push) 
"ANDROID": {
      "message": "Message", // Message of the push notification
      "title": "Title", // Title of the push notification 
  		"channel_id": "ChannelId", // Channel id of push notification (Optional)
      "richContent": [ //List of rich content items. Android push notifications have support  Image, Coupen and Sound. One single notifcations can support all combinations of these three types of rich content.
        {
          "type": "image",
          "value": "https://images.iimg.in/c" 
        },
        {
          "type": "coupon", 
          "value": "free" // when user click notifications, this code will be copied.
        },
        {
          "type": "sound",
          "value": "tring"
        }
      ],
      "defaultAction": { // Default action when user click on notifications. 
        "type": "richlanding", // Type of the default action
        "value": "https://www.google.co.in/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8 ",
        "kvPairs" :{ // additional key value pairs to be passed while sending notification.
        		"key1" : "value1",
        		"Key2" : "value2"
         }
      },
      "additionalActions": [ // List of action buttons. Maximum 2 buttons are allowed.
        {
          "type": "call",// action type
          "value": "12345678", // respective value
          "name": "Call button", // action name, displayed on notification
          "iconURL": "abc" // url for icon to be displayed
        },
        {
          "type": "copy", // action type
          "value": "12345678", // respective value
          "name": "Copy button", // action name, displayed on notification
          "iconURL": "abc" // icon url
        }
      ],
      "fallback": { // Complete replica of the android dict, in case a personalization is failed, this message content will be sent.
      }
    },

Example 2

This is a sample payload to target all users for each platform and also all platforms.

Android app iOS app web (Chrome Push) Across all platforms 
{
  "appId": "XXXXXXXXXXXXXXXXXXXXXXXX",
  "campaignName": "Test Push", // Name of the campaign.
  "campaignTags": ["Transactional"],
  "signature": "d7d28929ba474edf293b7c892efe22ec0e426ab1ba242b50c96f3126b9285385",
  "requestType": "push", // Type of request (push)
  "targetPlatform": [
    "ANDROID"
  ],
  "targetAudience": "All Users",
  "payload": {
    "ANDROID": { // Android Payload, detailed is described above
      "message": "Android Message",
      "title": "Android Message Title",
      "Summary": "Android Summary",
      "richContent": [
        {
          "type": "image",
          "value": "https://images.iimg.in/c"
        },
        {
          "type": "coupon",
          "value": "free"
        },
        {
          "type": "sound",
          "value": "tring"
        }
      ],
      "defaultAction": {
        "type": "richlanding",
        "value": "https://www.google.co.in/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8 "
      },
      "additionalActions": [
        {
          "type": "call",
          "value": "12345678",
          "name": "Call button",
          "iconURL": "abc"
        },
        {
          "type": "copy",
          "value": "12345678",
          "name": "Copy button",
          "iconURL": "abc"
        }
      ]
    }
  },
  "campaignDelivery": { 
    "type": "soon", //values can be - soon/later/periodic; if later/periodic, please provide respective values as well.
  },
  "conversionGoals": [
    {
      "name": "amount 1",
      "eventName": "AddedTocart",
      "attrs": {
        "filter": "is between",
        "name": "amount",
        "value": "10,100",
        "type": "numeric"
      }
    }
  ],
  "advancedSettings": {
    "ttl": {
      "ANDROID": 12 // the ttl for both Android and iOS platforms are tracked in ANDROID field. 
    },
    "ignoreFC": "false",
    "sendAtHighPriority": "true",
    "inboxExpiry": 360  //in hours

  }
}

Example 3

This example shows different payloads to target different segments of users.

Target Single User Target Custom Segment Target All Users 
{
  "appId": "XXXXXXXXXXXXXXXXXXXXXXXX",
  "campaignName": "Test Push", // Name of the campaign.
  "signature": "d7d28929ba474edf293b7c892efe22ec0e426ab1ba242b50c96f3126b9285385",
  "requestType": "push", // Type of request (push)
  "targetPlatform": [
    "ANDROID"
  ],
  "targetAudience": "User",
  "targetUserAttributes":{
    "attribute": "USER_ATTRIBUTE_USER_EMAIL",
    "comparisonParameter": "is",
    "attributeValue": "abc@example.com"
  },
  "payload": {
    "ANDROID": { // Android Payload, detailed is described above
      "message": "Android Message",
      "title": "Android Message Title",
      "Summary": "Android Summary",
      "richContent": [
        {
          "type": "image",
          "value": "https://images.iimg.in/c"
        },
        {
          "type": "coupon",
          "value": "free"
        },
        {
          "type": "sound",
          "value": "tring"
        }
      ],
      "defaultAction": {
        "type": "richlanding",
        "value": "https://www.google.co.in/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8 "
      },
      "additionalActions": [
        {
          "type": "call",
          "value": "12345678",
          "name": "Call button",
          "iconURL": "abc"
        },
        {
          "type": "copy",
          "value": "12345678",
          "name": "Copy button",
          "iconURL": "abc"
        }
      ]
    }
  },
  "campaignDelivery": { 
    "type": "soon" //values can be - soon/later/periodic; if later/periodic, please provide respective values as well.
  },
  "conversionGoals": [
    {
      "name": "amount 1",
      "eventName": "AddedTocart",
      "attrs": {
        "filter": "is between",
        "name": "amount",
        "value": "10,100",
        "type": "numeric"
      }
    }
  ],
  "advancedSettings": {
    "ttl": {
      "ANDROID": 12 // the ttl for both Android and iOS platforms are tracked in ANDROID field. 
    },
    "ignoreFC": "false",
    "sendAtHighPriority": "true",
    "inboxExpiry": 360  //in hours

  }
}

Example 4

This payload describes the sample for the push API response payload.

Sample Response
// sample success push respons payload
{
 "status": "Success",// shows valid request and accepted for processing
 "responseId": "cd13199a-0f70-4bf2-9c54-99879eefae76",
 "requestId": "",
 "cid": "581e08281069b855c03576d2"
}

// sample failure push response payload
{
 "status": "Fail", // shows invalid request
 "Error_Message": "Campaign Name not found", // reason of failure
 "responseId": "5612064a-24fa-4e8c-9e8a-c1c4221fe0ea",
 "requestId": "", 
}

Previous

Next

Was this article helpful?
2 out of 8 found this helpful

How can we improve this article?