Send Mobile App Messages over API
MAM offers a wide range of possibilities when it comes to destination targeting options. Below you will find the available fields and examples on how they can be used.
To send a single Push notification to one or multiple recipients, use this method. When sending a large number of messages or targeting different user segments with different messages to optimize data traffic and increase performance, use this method.
PUSH SDK
Learn how to properly implement destination address type parameters in the Android, iOS, and Huawei SDK documentation, or for the React Native, Flutter and Cordova plugins.
Destination address types enabled by default:
Name |
Type |
Description |
pushRegistrationId |
string |
Push Registration Id is a unique ID which identifies application instance and specific device. |
platform |
string |
Possible values are Android or iOS. |
sdkVersion |
string |
SDK Version which can be found on the Github: |
osVersion |
string |
OS version. |
deviceManufacturer |
string |
Device manufacturer: |
deviceModel |
string |
Device model, for example, iPhone 6, iPhone 5s (GSM+CDMA), LG-D855. |
applicationVersion |
string |
Application version. |
pushRegistrationEnabled |
boolean |
Is the device allowed to receive push notifications? Set to true to only target users who have push registration enabled. For more details refer to iOS SDK Wiki and Android SDK Wiki. |
notificationsEnabled |
boolean |
Set to true to only target devices where notifications for the mobile application are turned on by the user. |
geofencingEnabled |
boolean |
Is Geofencing SDK set and tracking locations allowed by the user. |
deviceSecure |
boolean |
Is Touch-Id or passcode set for the device? |
The following destination address types are not available by default. They should be defined by User Data in SDK.
Name | Type | Description |
externalUserId | string | External user ID set in User Profile. Learn more about external user id in Android, iOS and Cordova SDK documentation. |
phoneNumber | string | MSISDN in international format (Example: 41793026727). |
string | Email of the user if it is provided in User Profile. | |
{custom field} | string | Any field from installation custom attribute parameters. Learn more about custom attributes in Android, iOS and Cordova SDK documentation. |
COMBINING DIFFERENT ADDRESS TYPES IN A SINGLE REQUEST
You can use a single address type or even combine two or more to achieve the desired user segmentation. Use the API request example above and replace only the “to” field with one of the examples below to take advantage of various segmentation options.
Single Recipient Destination Address Type
Use this method to target recipient’s device associated with the single Push registration ID.
"to": {
"pushRegistrationId": "69827EDB-A806-4AF6-A7F6-98298EAA4F14"
}
With this type of targeting, you can achieve the following:
-
target all iOS or Android devices
-
target a particular device
-
target all devices of a particular external user id
-
target all devices linked to a phone number
-
target all devices linked to an email
-
target all devices associated with any custom data parameter like tag, subscription or other
In the following example, we are targeting all iOS devices.
"to": {
"platform": "iOS"
}
With this example, all devices that have been associated with the phone number 41793026727 will be targeted.
"to": {
"phoneNumber": "41793026727"
}
To send a single Push notification to one or multiple recipients, use this method.
Multiple Recipient Destinations of the Single Address Type (IN)
Combining two or more different parameters of the same destination address type can be done as shown in the example below. In this example, the message will be delivered to both iOS and Android users.
"to": {
"platform": ["iOS", "Android"]
}
By using this method you can target all of the user devices according to email address.
"to": {
"email": ["[email protected]", "[email protected]"]
}
Multiple Destination Address Types (AND)
You can use this method to target a recipient segment by using two or more different address type filters. The message will be delivered only to those recipients who satisfy all filter conditions. In other words, if the recipient’s device matches address type 1 AND address type 2, the message will be sent.
In the following example, all iOS devices of the recipient with a specific external ID will be targeted.
"to": {
"platform": "iOS",
"externalUserId": "customer_21234"
}
Multiple Destination Address Types (OR)
In some cases, you may want to segment your recipients by including different filters over multiple destination address types. By using this method, the recipient will receive the message if he satisfies at least one condition. In other words, if the recipient matches address type 1 OR address type 2, a message will be sent.
In the following example, recipients whose favorite pizza is Capricciosa or favorite pasta is Napolitana will be targeted.
"to": {
"$or": [
{"FavoritePizza": "Capricciosa"},
{"FavoritePasta": "Napolitana"}
]
}
Advanced Targeting Example
The combination of different targeting methods is also supported.
In the following example, we are targeting Android devices of the recipients who have a specific user ID or at least one of the listed emails.
"to": {
"$or": [
{"externalUserId": "my-ext_id-1"},
{"email": ["[email protected]", "[email protected]"]}
],
"platform": "Android"
}
TEST YOUR PUSH NOTIFICATIONS BEFORE SENDING
Advanced segment targeting can get complicated and be error-prone. Test your Push notifications request before sending them out to get a feel of how many devices will be affected.