Send Mobile Push over API
Send Mobile Push over API
Mobile Push API offers a wide range of possibilities when it comes to destination targeting options. Below you will find the available fields and examples of 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 GitHub: Releases of plugins for: |
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 the following SDK wikis: |
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 the following 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 the following 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 the 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": ["jane.smith@somedomain.com", "[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 whose 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"
}
Get Stats over API
Use the bulk push message statistics method to retrieve statistics for sent bulk push messages.
NOTE
To get a detailed delivery report for each message sent in your bulk request, refer to the Push sent message reports on the Infobip API Developer Hub.
Query parameters
Parameter |
Type |
Description |
---|---|---|
bulkId |
string |
The ID that uniquely identifies the sent request. |
Response format
Parameter |
Type |
Description |
---|---|---|
totalSent |
int |
Total number of sent messages. |
delivered |
int |
Total number of delivered messages. |
seen |
int |
Total number of seen messages. |
errors |
error |
Messages not delivered to users. |
delivery |
delivery |
Delivery information about the bulk sending of messages. |
Errors
Parameter |
Type |
Description |
---|---|---|
registration |
int |
Messages not delivered due to errors with non-valid registrations due to user uninstalling the app. |
expired |
int |
Messages undelivered due to expired validity period. Indicates users who have disabled notifications on a specific Push application. |
cloud |
int |
Messages not delivered due to errors on APNS or FCM clouds. Happens due to transient errors on cloud services. |
Delivery
Parameter |
Type |
Description |
---|---|---|
rate |
double |
Delivery rate. The ratio between total delivered and total sent messages in a specific bulk sending process. |
Send Push over OMNI API
The OMNI API enables automatic fallback to another channel according to the defined order.
To send push with OMNI API you need to:
- Create an OMNI scenario
- Send a message with OMNI scenario
- Get delivery reports (optional)
Create OMNI Scenario
To create an OMNI scenario, you need to define the OMNI steps which will be sequentially executed.
To send push notifications with the scenario, you should use push (“channel”: “PUSH”)
and APPLICATION CODE as the sender (“from”: “APPLICATION CODE”)
generated during the setup of the mobile application.
Find more information on how to create the OMNI scenario in the Create Mobile Application Profile article in the Documentation Hub. Refer to the Infobip API Developer Hub for more information on how to create an OMNI scenario.
Most common OMNI scenario is push with SMS as a fallback channel. The following code snippet demonstrates how to create such a scenario.
{
"name" : "push + SMS scenario",
"flow": [
{
"from": "APPLICATION CODE",
"channel": "PUSH"
},
{
"from": "YOUR_REGISTERED_SMS_SENDER",
"channel": "SMS"
}
],
"default": true
}
Send Messages With OMNI Scenario
Once you've created the OMNI scenario (identified by the key
parameter), you can send your OMNI messages through defined communication channels.
NOTE
To be able to send push messages using Infobip web interface, you need to have at least one mobile application profile registered on the platform. Refer to the Create Mobile Application Profile for detailed instructions.
If you want to send one or multiple messages to different channels, you need to use the advanced OMNI message method.
You can use different options for processing push notifications when you receive them.
Name |
Required |
Default value |
Type |
Description |
---|---|---|---|---|
vibrationEnabled |
No |
true |
boolean |
Notification vibration (Android only). |
soundEnabled |
No |
true |
boolean |
The sound when notification arrives on a device. |
soundName |
No |
- |
string |
The name of the custom sound played when a notification arrives on a device. The file should be in the app; max 30 seconds long. The file extension is required for iOS and optional for Android. For custom sound to be played |
badge |
No |
|
integer |
Badge counter (iOS only). |
contentUrl |
No |
|
string |
URL of the image displayed in the notification. Rich push notifications are available on devices with iOS 10 and Android 4.1.+. Supported on iOS since Mobile SDK version 2.5.8. Supported on Android since Mobile SDK version 1.6.4. |
category |
No |
|
string |
Category id for actionable notification. Supported on Android since Mobile SDK version 1.6.16. Supported on iOS since Mobile SDK version 2.6.9. Predefined category ids: mm_accept_decline - Accept & Decline button actions. |
inAppStyle |
No |
|
string |
Possible values: |
isSilent |
No |
|
boolean |
Set to |
title |
No |
Application name set within mobile project |
string |
Notification title displayed within notification. Requires iOS 10+ or Android 4.1+ (may depend on Android custom firmware) |
webViewUrl | No | string | URL to open external web page within the mobile app (web view). | |
inboxTopic | No | string | A case sensitive topic name to save a message to an inbox. If the topic name does not exist for a specified account, message sending will be rejected. |
The code snippet demonstrates how to send a push notification with options with OMNI API.
{
"scenarioKey": "key",
"destinations": [
{
"to": {
"phoneNumber": "phone number"
}
}
],
"push": {
"text": "This PUSH message will pop up on your mobile device.",
"customPayload": {
"contentUrl": "https://someurl.com/content",
"deepLink": "myApp://some/link"
},
"notificationOptions": {
"vibrationEnabled": true,
"soundEnabled": true,
"soundName": "sound.wav",
"badge": 1,
"contentUrl": "http://www.mydomain.com/images/image1.jpg",
"category": "mm_accept_decline",
"inAppStyle": "MODAL",
"title": "This is some title"
},
"targetOnlyPrimaryDevices": true,
"includeNotificationsDisabledDevices": true
},
"sms": {
"text": "This is the SMS failover message"
}
}
Get Delivery Report
You can check the status of messages sent and get delivery reports with the OMNI reports method.