# Send Mobile push over API

Infobip provides a robust API to send Mobile push messages and get analytics. You can use this API for transactional, informational, and promotional use cases.

## Send Mobile push over API [#send-push-over-api]

Use the [Send Push notifications](https://www.infobip.com/docs/api/channels/mobile-app-messaging/send-push-notifications) method to send Mobile push messages to one or more recipients. The unified structure of the API across all channels enables you to integrate it with your app. The Mobile push parameters enable you to target either a specific mobile application user or to a segment of users.

Configure the fields as follows.

### Sender [#send-push-over-api-sender]

The identifier of the application profile. Use the Application code or Application ID of the [application profile](get-started/mobile-application-profile#create-and-enable-a-mobile-application-profile) that you create in the Infobip web interface.

### Destination [#send-push-over-api-destination]

To send a Mobile push message to a single recipient, use one of the following parameter types:

- **External user ID**
- **Email**
- **Phone number**
- **Registration**

To send a Mobile push message to multiple recipients, use **Multiple**.

For more information, refer to the relevant sections on this page.

### Target single recipient with non-personalized device [#push-over-api-single-person-non-personalized]

A non-personalized device is an end user's device that is not associated with any of the personalized standard attributes (External user ID, email, or phone number).

To send a Mobile push message to a non-personalized device, do the following.

- Specify **REGISTRATION** as the destination **type**.
- Specify the Push registration ID. This value is available by default on all installations of the mobile application.

#### Code sample

```json
    "destinations": [
	{
	"pushRegistrationId": "DBE0B0B6-668E-491E-8EE8-2A3DB2C71CBE",
	"type": "REGISTRATION"
	}
	]
```

#### Push registration ID

The following table shows information about the Push registration ID.

| Destination parameter | Type | Description |
| --- | --- | --- |
| pushRegistrationId | String | The unique identifier of a specific application instance-device combination.This parameter can be collected over Mobile SDK.For more information, refer to the following documentation.AndroidiOSHuaweiFlutterReact NativeCordova |

### Target single recipient with personalized device [#push-over-api-single-person-personalized]

A personalized device is an end user's device that is associated with one or more of the personalized standard attributes (External user ID, email, or phone number).

Use the following destination address types.

| Destination parameter | Type | Description |
| --- | --- | --- |
| externalUserId | String | External user ID set in the Person Profile. |
| phoneNumber | String | MSISDN ininternational format. Example: 41793026727.This value is available in theContact informationtab of the end user's Person profile in People. |
| email | String | Email address of the end user.This value is available in theContact informationtab of the end user's Person profile in People. |

These address types are not available by default. You must define them either in the Mobile SDK or the People API.

- [Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [Huawei](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [Flutter](https://github.com/infobip/mobile-messaging-flutter-plugin/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [React Native](https://github.com/infobip/mobile-messaging-react-native-plugin/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [Cordova](https://github.com/infobip/mobile-messaging-cordova-plugin/wiki/Users-and-installations#personalization-external-user-id-emails-and-phone-numbers)
- [People API](https://www.infobip.com/docs/api/customer-engagement/people/personalize-push-instance)

#### Code sample

```json
    "destinations": [
	{
	"externalUserId": "customer_21234",
	"type": "EXTERNAL_USER_ID"
	}
	]
```

Note
If multiple devices are linked to a person profile by using externalUserId, phoneNumber, or email, the push notification is delivered to all the devices by default. To send push notifications only to the primary device, use the parameter *<targetOnlyPrimaryDevices>* in the *<destinations>* section.

### Target multiple recipients by using OR operator [#push-over-api-multiple-persons-using-OR]

To send a Mobile push message to multiple recipients, do the following.

- Specify **MULTIPLE** as the destination **type**.
- Specify multiple values for the destination parameter by using the <OR> operator.

#### Code sample

```json
    "destinations": [
     {
        "$or": [
          {
             "externalUserId": "customer_21234"
           },
           {
             "externalUserId": "customer_21235"
           }
         ],
         "type": "MULTIPLE"
     }
]
```

### Target multiple recipients by using device attributes [#push-over-api-multiple-persons-device-attributes]

You can target multiple recipients based on the device attributes.

These destination address types are enabled by default.

| Name | Type | Description |
| --- | --- | --- |
| platform | String | Accepted values are Android or iOS. |
| sdkVersion | String | SDK Version that can be found on GitHub.Mobile SDK Android releasesMobile SDK iOS releasesMobile SDK Huawei releasesReleases of plugins for:FlutterReact NativeCordova |
| osVersion | String | Operating system version. |
| deviceManufacturer | String | Device manufacturer:iOS - AppleAndroid. Example: Samsung, Asus.The value for a specific installation can be found in theContact informationtab >Mobile applicationssection of a person profile in [People](https://www.infobip.com/docs/people). |
| deviceModel | String | Device model. Example: iPhone 6, iPhone 5s (GSM+CDMA), LG-D855. For more information about iOS device models, refer to [List of iOS models](https://support.apple.com/guide/iphone/supported-models-iphe3fa5df43/ios).The value for a specific installation can be found in theContact informationtab >Mobile applicationssection of a person profile in [People](https://www.infobip.com/docs/people). |
| applicationVersion | String | Application version. |
| osLanguage | String | The language that is set on the mobile device. This parameter can be overridden by application logic. |
| deviceSecure | Boolean | Is biometric authentication or passcode set for the device. |
| notificationsEnabled | Boolean | Set totrueto target only the devices in which the end user has enabled notifications for the mobile application. |

The following destination address types are not available by default. You must define them over Mobile SDK.

| Name | Type | Description |
| --- | --- | --- |
| {custom field} | String | Any field from installation custom attribute parameters.For information about the implementation of custom attributes, refer to the following documentation.Android SDKiOS SDKHuawei SDKFlutter pluginReact Native pluginCordova |

To send a Mobile push message to multiple recipients, do the following.

- Specify **MULTIPLE** as the destination **type**.
- Specify multiple values for the destination parameter by using the <and> and <or> operators.

In the following example, all iOS devices are targeted.

#### Code sample

```json
    "destinations": [
     {
        "$or": [
          {
             "platform": "iOS"
           }
         ],
         "type": "MULTIPLE"
     }
]
```

### Advanced targeting

To create the required user segmentation and send them Mobile push messages, do the following.

- Specify **MULTIPLE** as the destination **type**.
- Use the <and> and <or> operators.

#### Example 1

In the following example, all iOS devices of the recipient with a specific phone number are targeted.

##### Code sample

```json
"destinations": [
     {
        "$and": [
          {
             "platform": "iOS"
           }, 
          {
             "phoneNumber": "441134960001"
           }
         ],
         "type": "MULTIPLE"
     }
]
```

#### Example 2

In the following example, the following recipients are targeted. The recipients must fulfil both criteria.

- The custom device attribute, *Device type*, is either *Personal* or *Business*.
- Target device has iOS.

##### Code sample

```json
"destinations": [
     {
        "$and": [
          {
             "platform": "iOS"
           }, 
          {
             "DeviceType": "personal"
           }
           ],
        "$or": [
           {
            "DeviceType": "business"
           } 
           ],
         "type": "MULTIPLE"
     }
]
```

## Mirror push notifications within the application [#api-mirror-push-notification]

You can use **Send push API** to show the notification within the application 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 application and cannot see push notifications. ​
- Show the notification only within the application 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 [#api-mirrored-push-notification-message-formats]

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

- **Modal**: 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 [#api-mirror-push-notification-supported-versions]

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

| SDK | Supported version for Modal pop-up | Supported version for Banner |
| --- | --- | --- |
| **SDK for Android** | since 1.13.0 | since 2.0.0 |
| **SDK for iOS** | since 3.6.0 | since 5.0.0 |
| **SDK for Huawei** | since 1.0.0 | since 1.0.0 |
| **Flutter** | All versions | All versions |
| **React Native** | All versions | All versions |
| **Plugin for Cordova** | since 0.7.0 | since 1.0.0 |

### Notification parameters [#api-in-app-notification-parameters]

To send notifications within the app, add the following parameters in **notificationOptions**.

| **Parameter** | **Description** |
| --- | --- |
| **showMirroredPush** | Enables the message to be displayed within the app. |
| **mirroredPushStyle** | Define whether the notification is displayed within the application as a banner or as a modal pop-up. |
| **mirroredPushExpirationPeriod** | Specify the maximum period during which the flow delivers the notification within the app. |
| **mirroredPushExpirationTimeUnit** | Set the time unit for the expiration period to show the notification within the app. Choose either minutes or hours​. |
| **Buttons**: If the **mirroredPushStyle** is set to **MODAL**, you can also define buttons. |
| **mirroredPushDismissTitle** | Specify the text for the **Dismiss** button ​ |
| **mirroredPushOpenTitle** | Specify the text for the **Open** button |
| **onTapButtonAction** | Specify the action to perform when the end user taps the Primary button in the notification within the app.​ |

## Get Stats over API

Use the <apidocslink href="channels/mobile-app-messaging/get-push-statistics">bulk push message statistics method</apidocslink> 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 <apidocslink href="channels/mobile-app-messaging/get-push-statistics">Push sent message reports</apidocslink> 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 [#createomni-scenario-send-push-over-omni-api]

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](https://www.infobip.com/docs/mobile-push/get-started/mobile-application-profile) article in the Documentation Hub. Refer to the Infobip API Developer Hub for more information on <apidocslink href="channels/omni-failover/create-omni-failover-scenario">how to create an OMNI scenario</apidocslink>.

Most common OMNI scenario is push with SMS as a fallback channel. The following code snippet demonstrates how to create such a scenario.

```json
    {
      "name" : "push + SMS scenario",
      "flow": [
        {
          "from": "APPLICATION CODE",
          "channel": "PUSH"
        },
        {
          "from": "YOUR_REGISTERED_SMS_SENDER",
          "channel": "SMS"
        }
      ],
      "default": true
    }
```

### Send Messages With OMNI Scenario [#send-messages-with-omni-scenario-send-push-over-omni-api]

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](https://www.infobip.com/docs/mobile-push/get-started/mobile-application-profile#copy-application-code-create-and-enable-a-mobile-application-profile) for detailed instructions.

If you want to send one or multiple messages to different channels, you need to use the <apidocslink href="channels/omni-failover/send-omni-failover-message">advanced OMNI message method</apidocslink>.

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 playedsoundEnabledshouldn’t be false (e.g., notification_sound.wav). CheckAndroidandiOSusage 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 iOSsince Mobile SDK version 2.5.8.Supported on Androidsince Mobile SDK version 1.6.4. |
| category | No |  | string | Category id for actionable notification.Supported on Androidsince Mobile SDK version 1.6.16.Supported on iOSsince Mobile SDK version 2.6.9. Predefined category ids: **mm_accept_decline** - Accept & Decline button actions. |
| inAppStyle | No |  | string | Possible values:MODAL,BANNER. Set toMODALto use in application dialog for actionable messages, orBANNERto show a standard banner view.MODALis supported on iOS from3.6.0, on Android from1.13.0, on Cordova from0.7.0, and React Native from1.0.0.BANNERis supported from iOS5.0.0, Android2.0.0, Cordova1.0.0, and React Native1.0.0. |
| isSilent | No |  | boolean | Set totrueto send a silent push message. Such messages are not displayed on the device lock screen and in the notification center. Silent messages can be used to deliver custom data to your mobile application or to show the notification within the app. |
| title | No | Application name set within mobile project | string | Title of the notification. The title is visible to the end user. 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 application (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.

```json
    {
      "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 [#get-delivery-report-send-push-over-omni-api]

You can check the status of messages sent and get delivery reports with the <apidocslink href="channels/omni-failover/get-omni-failover-delivery-reports">OMNI reports</apidocslink> method.