Send bulk Push notifications

Use this method when sending a large amount of messages or targeting different user segments with different messages to optimize data traffic and increase performance.

Resource

https://api.infobip.com/push/2/message/multi

Parameters

Property name Type Description
messages string Collection of Push notifications. Each message in the collection is completely independent. Different values may be used for each notification, such as "sender application" or "message text".
from string Push application code you are using to send notifications. Application code is the application identifier which links your mobile application to the application profile created inside the Infobip Platform. It is required to insert the application code into the Mobile Messaging SDK configuration once you implement it in your mobile application.
to * object Recipient destination address.
text  string Text of the message that will be sent.
sendAt  datetime Used for scheduled Push notifications. The notification will be sent at the scheduled time.
customPayload object Additional data that can be delivered with the Push notification. customPayload must be formatted as JSON object.
notificationsOptions object JSON object that contains notification options.
validityPeriodTimeUnit string (HOURS) The message validity period time unit. Supported values are: SECONDS, MINUTES and HOURS.
notifyUrl string The URL on your callback server on which the Delivery report will be sent. Additional Information about Delivery reports on Notify URL.
notifyContentType string (application/json) Preferred Delivery report content type. Supported content types: application/json, application/xml.
callbackData string Additional client's data that will be sent on the notifyUrl. The maximum value is 200 characters.
targetOnlyPrimaryDevices boolean Set to true to only send messages to push devices which are marked as primary devices. By default, messages will be sent to all targeted devices, including both primary and non-primary.

Request Example

					POST /push/2/message/multi HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

{
	"messages": [
		{
    		"from": "d417d38814740a23f50b5c876e226445-0f700564-abbf-4b5b-beae-86a4ef410904",
    		"to": {
        		"externalUserId": "customer_21234"
    		},
    		"text": "This message can be one of many in this message collection.",
    		"notificationOptions": {
    			"soundEnabled": false,
    			"badge": 1
    		},
	  		"customPaylod":{
  				"targetUrl": "www.someDomain.com",
	 				"someData": "someData"
	 		  },
        "validityPeriod": 30,
        "validityPeriodTimeUnit": "MINUTES",
        "notifyUrl": "https://example.com",
        "notifyContentType" : "application/json",
        "callbackData" : "DLR callback data"
		},
		{
		    "from": "c297d38814740a23f50b5c876e226445-0f700564-abbf-4b5b-beae-86a4ef410904",
		    "to": {
        		"externalUserId": "customer_113456"
		    },
		    "text": "This is the second message in this collection.",
		    "notificationOptions": {
		    	"soundName": "notification_sound.wav"
		    }
		}
	]
}
					
				

Response

					{
  "bulks": [
    {
      "to": {
        "externalUserId": "customer_21234"
      },
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "PENDING_ACCEPTED",
        "description": "Message accepted, pending for delivery"
      },
      "messageCount": 2,
      "bulkId": "oungulj9xm9b3hixkupu"
    },
    {
      "to": {
        "externalUserId": "customer_113456"
      },
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 26,
        "name": "PENDING_ACCEPTED",
        "description": "Message accepted, pending for delivery"
      },
      "messageCount": 2,
      "bulkId": "gby7cz3x6m244n2e4vzb"
    }
  ]
}
					
				

If successful, the response header HTTP status code will be 200 OK and the message will be sent. If you try to send the message without authorization, you will receive a 401 Unauthorized error. In case of an incorrectly formatted request, the HTTP status code will be 400 Bad Request.

Response format

Parameter Type Description
to object Recipient destination address.
status object Message status.
messageCount integer Number of recipients for targeted segment.
bulkId string The ID which uniquely identifies the request.

Status:

Parameter Type Description
groupId int Status group ID.
groupName String Status group name.
id int Status ID.
name String Status name.
description String Human-readable description of the status.

Notification options

You may choose different options on how to alert the user when the Push notification is received.

Name Required Default Type Description
vibrationEnabled no true boolean Notification vibration (Android only).
soundEnabled no true boolean Sound when notification arrives on a device.
soundName no - String Name of the custom sound played when notification arrives on a device. File should be located in the app with max 30 seconds length. File extension is required for iOS and optional for Android. For custom sound to be played soundEnabled shouldn’t be false (Example: notification_sound.wav). Check Android and iOS usage details.
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 MM SDK version 2.5.8. Supported on Android since MM SDK version 1.6.4.
category no - string Category id for actionable notification. Supported on Android since MM SDK version 1.6.16. Supported on iOS since MM SDK version 2.6.9. Predefined category ids: mm_accept_decline - accept/decline actions.
showInApp no - Boolean Set to true to enable in app dialog for actionable message. Supported on iOS from 3.6.0. Supported on Android from 1.13.0.
isSilent no - Boolean Set to true to send silent push message. Such messages aren’t displayed on device lock screen and in the notification center. Silent messages can be used to deliver custom data to your mobile application or to trigger an in-app notification.

Recipient destination address types

Push notifications offer a wide range of possibilities when it comes to destination targeting options. Below you will find available fields and examples on how they can be used.

Push SDK

Learn how to properly implement destination address type parameters in the Android and iOS SDK documentation.

Destination address types enabled by default are:

Name Type Description
pushRegistrationId string Push Registration Id is a unique ID which identifies application instance and a specific device.
cloudType string Possible values are GCM (Google Cloud Messaging) or APNS (Apple Push Notification service).

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 and IOS SDK documentation.
GSM string MSISDN in international format (Example: 41793026727).
email string Email of the user if it is provided in User Profile.
string Any field from custom data parameters. Learn more about custom data in Android and IOS 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 GSM
  • 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": {
    "cloudType": "APNS"
}

With this example all devices that have been associated with the GSM number 41793026727 will be targeted.

"to": {
    "GSM": "41793026727"
}

Multiple recipient destinations of a 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": {
    "cloudType": ["APNS", "GCM"]
 }

By using this method you can target all user devices by email address.

 "to": {
    "email": ["jane.smith@somedomain.com", "john.smith@somedomain.com"]
 }

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 the 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": {
    "cloudType": "APNS",
    "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, a recipient will receive the message if he satisfies at least one condition. In other words, if the recipient matches the address type 1 OR address type 2, the 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 recipients who have a specific user ID or at least one of the listed emails.

"to": {
    "$or": [
        {"externalUserId": "my-ext_id-1"},
        {"email": ["myEmail_1@domain.com", "myEmail_2@domain.com"]}
    ],
    "cloudType": "GCM"
}

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 effected.