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 (opens in a new tab). 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 (opens in a new tab).

Destination address types enabled by default:

The following destination address types are not available by default. They should be defined by User Data in SDK.

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. (opens in a new tab)

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 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"
    }
 

Mirror push notifications within the app

You can use Mobile push API to show the notification within the app for the following scenarios:​

• Show a push notification as well as show the notification within the app. Example: To support transactional information to end users who are using the app and cannot see push notifications. ​
• Show the notification only within the app without showing a push notification. The notification is not displayed in the Notification center. To use this option, enable Silent push notification type.

Message formats

You can show the notification within the app in the following formats:

• Pop-up: A type of notification that pops up on a screen and overlaps a part of the screen. Use this feature for scenarios when you want to get the full attention of the end user and ask them to do something.
• Banner: Small notifications that are temporarily displayed over the content of the mobile app. They are displayed either on the top or the bottom of the screen of the mobile device and then close automatically after a few seconds. Use banners when you need to inform an end-user about something without stopping them from what they are doing in the app.

Supported SDK versions

The following SDK versions support showing the message inside the app.

Notification parameters

To send notifications within the app, use the Send single Push notification (opens in a new tab) and Send multiple Push notifications (opens in a new tab) requests.

Add the following parameters in notificationOptions.

Get Stats over API

Use the bulk push message statistics method (opens in a new tab) to retrieve statistics for sent bulk push messages.

Query parameters

Response format

Errors

Delivery

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 (opens in a new tab).

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.

If you want to send one or multiple messages to different channels, you need to use the advanced OMNI message method (opens in a new tab).

You can use different options for processing push notifications when you receive them.

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 (opens in a new tab) method.