Send Push notifications

Use this method to send a single Push notification to one or multiple recipients.

Resource

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

Parameters

Property name Type Description
from string PUSH Application Code you are using to send messages. Application Code is the application identifier which links your mobile application to the application profile created in Infobip Platform. It is required to insert the Application Code in 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. Message will be sent at scheduled time.
customPayload object Additional data that can be delivered with the Push message. customPayload must be formatted as JSON object.
norificationOptions object JSON object that contains notification options.
validityPeriod int The message validity period. Unless specified differently in validityPeriodTimeUnit, it is expressed in hours. When the period expires, it will not be allowed for the message to be sent or message will be canceled if it's pending in Cloud (APNS or GCM). Default value 48h. Minimum value is 30 sec. Maximum value is 72h.
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/single HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

{
    "from": "d417d38814740a23f50b5c876e226445-0f700564-abbf-4b5b-beae-86a4ef410904",
    "to": {
        "externalUserId": "customer_21234"
    },
    "text": "This Message was sent by targeting exact externalUserId.",
    "notificationOptions": {
    	"soundEnabled": false,
    	"badge": 1,
      "contentUrl": "https://www.mydomain.com/images/image1.jpg",
      "category": "mm_accept_decline"
    },
	  "customPayload":{
  		"targetUrl": "www.someDomain.com",
	 		"someData": "someData"
	  },
    "validityPeriod": 30,
    "validityPeriodTimeUnit": "MINUTES",
    "notifyUrl": "https://example.com",
    "notifyContentType" : "application/json",
    "callbackData" : "DLR callback data"
}
					
				

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": "zf813qgp7nnqu8xfa2vi"
    }
  ]
}
					
				

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 a wrongly 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 PUSH message 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 true 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 button 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.
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)

Recipient destination address types

Push notifications offer 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.

Push SDK

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

Destination address types enabled by default:

Name Type Description
pushRegistrationId string Push Registration Id is unique ID which identifies application instance and specific device.
platform string Possible values are Android or iOS.

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 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 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": {
    "platform": "iOS"
}

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

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

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", "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 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, recipient will receive the message if he satisfies at least one condition. In other words, if recipient matches address type 1 OR address type 2, 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": ["myEmail_1@domain.com", "myEmail_2@domain.com"]}
    ],
    "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 effected.