{"_id":"587752a2ec7f142d002e0733","user":"54eb4fdedf7add210007b29b","version":{"_id":"54eb63b859b1172100334fae","project":"54eb50e5615ffc1900305a16","forked_from":"54eb63a1867e1917009b711d","__v":28,"createdAt":"2015-02-23T17:30:32.501Z","releaseDate":"2015-02-23T17:30:32.501Z","categories":["54eb63b959b1172100334faf","54eb63b959b1172100334fb0","54eb63b959b1172100334fb1","54eb63b959b1172100334fb2","54ed8dd4ab373e2300f50eae","54ed99b2ab373e2300f50ede","55153a6de68daa2f00cff838","551546edbc466623002afe72","5515472ac28d6125001b8884","55154749c28d6125001b8885","555d9b4106dfec0d00d38ea7","5613e06e433e5735007c7708","5624bbb785a31117001c5403","56669e857cc81e0d00253f8e","568b8d837a42220d00498311","56a632277ef6620d00e2f18a","56d8147c3eb4dd0b00201aac","57a9ce2fac6db30e000d7efd","57a9cf4e944ea60e00dc3f74","58172386715dce0f00da4aa0","582dc59ee1b8692300c0dd03","589b19b4fec2730f0082e040","58b04a023529383900a759b5","58b92d1598157a0f004869bf","592e7685c58275000f20174f","59392839e376d4002f8a0474","59393064e376d4002f8a05a1","5947ae0d4005e2000f3a4fec","594a74df1d1de5001ab3517a","5954bc387a147f001b918915","59b8eeeb707542001076d3b6"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1"},"project":"54eb50e5615ffc1900305a16","__v":13,"category":{"_id":"57a9ce2fac6db30e000d7efd","__v":0,"project":"54eb50e5615ffc1900305a16","version":"54eb63b859b1172100334fae","sync":{"url":"","isSync":false},"reference":true,"createdAt":"2016-08-09T12:35:59.736Z","from_sync":false,"order":8,"slug":"push-messages","title":"Push messages"},"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-12T09:55:46.957Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"code":"POST /push/2/message/single HTTP/1.1\nHost: api.infobip.com\nAuthorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==\nContent-Type: application/json\nAccept: application/json\n\n{\n    \"from\": \"d417d38814740a23f50b5c876e226445-0f700564-abbf-4b5b-beae-86a4ef410904\",\n    \"to\": {\n        \"externalUserId\": \"customer_21234\"\n    },\n    \"text\": \"This Message was sent by targeting exact externalUserId.\",\n    \"notificationOptions\": {\n    \t\"soundEnabled\": false,\n    \t\"badge\": 1,\n      \"contentUrl\": \"http://www.mydomain.com/images/image1.jpg\",\n      \"category\": \"mm_accept_decline\"\n    },\n\t  \"customPayload\":{\n  \t\t\"targetUrl\": \"www.someDomain.com\",\n\t \t\t\"someData\": \"someData\"\n\t  },\n    \"validityPeriod\": 30,\n    \"validityPeriodTimeUnit\": \"MINUTES\",\n    \"notifyUrl\": \"http://example.com\",\n    \"notifyContentType\" : \"application/json\",\n    \"callbackData\" : \"DLR callback data\"\n}","language":"json"}]},"method":"post","results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n  \"bulks\": [\n    {\n      \"to\": {\n         \"externalUserId\": \"customer_21234\"\n      },\n      \"status\": {\n        \"groupId\": 1,\n        \"groupName\": \"PENDING\",\n        \"id\": 26,\n        \"name\": \"PENDING_ACCEPTED\",\n        \"description\": \"Message accepted, pending for delivery\"\n      },\n      \"messageCount\": 2,\n      \"bulkId\": \"zf813qgp7nnqu8xfa2vi\"\n    }\n  ]\n}\n"}]},"settings":"554860d6d2c8410d006c215e","auth":"required","params":[{"_id":"587752a2ec7f142d002e0739","ref":"","in":"body","required":true,"desc":"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.","default":"","type":"string","name":"from"},{"_id":"587752a2ec7f142d002e0738","ref":"","in":"body","required":true,"desc":"<a href=\"#section-recipient-destination-address-types\">Recipient destination address.</a>","default":"","type":"object","name":"to"},{"_id":"587752a2ec7f142d002e0737","ref":"","in":"body","required":true,"desc":"Text of the message that will be sent.","default":"","type":"string","name":"text"},{"_id":"587752a2ec7f142d002e0736","ref":"","in":"body","required":false,"desc":"Used for scheduled PUSH notifications. Message will be sent at scheduled time.","default":"","type":"datetime","name":"sendAt"},{"_id":"587752a2ec7f142d002e0735","ref":"","in":"body","required":false,"desc":"Aditional data that can be delivered with the PUSH message. customPayload must be formatted as JSON object.","default":"","type":"object","name":"customPayload"},{"_id":"587752a2ec7f142d002e0734","ref":"","in":"body","required":false,"desc":"<a href=\"#section-notification-options\">JSON object that contains notification options.</a>","default":"","type":"object","name":"notificationOptions"},{"_id":"59ddc9c6b0fab8001ae0fb77","ref":"","in":"body","required":false,"desc":"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.","default":"","type":"int","name":"validityPeriod"},{"_id":"59ddc9c6b0fab8001ae0fb76","ref":"","in":"body","required":false,"desc":"The message validity period time unit. Supported values are: `SECONDS`, `MINUTES` and `HOURS`.","default":"HOURS","type":"string","name":"validityPeriodTimeUnit"},{"_id":"59f33627eba8cd00265b8880","ref":"","in":"body","required":false,"desc":"The URL on your callback server on which the <a href=\"push-sent-messages-reports\">Delivery report</a> will be sent. <a href=\"delivery-reports-on-notify-url\">Additional Information about Delivery reports on Notify URL.</a>","default":"","type":"string","name":"notifyUrl"},{"_id":"59f33627eba8cd00265b887f","ref":"","in":"body","required":false,"desc":"Preferred Delivery report content type. Supported content types: `application/json`, `application/xml`.","default":"application/json","type":"string","name":"notifyContentType"},{"_id":"59f33627eba8cd00265b887e","ref":"","in":"body","required":false,"desc":"Additional client's data that will be sent on the notifyUrl. The maximum value is 200 characters.","default":"","type":"string","name":"callbackData"}],"url":"/push/2/message/single"},"isReference":true,"order":9,"body":"If successful, the response header HTTP status code will be 200 OK and the message will be sent.\nIf you try to send the message without authorization, you will receive a 401 Unauthorized error.\nIn case of a wrongly formatted request the HTTP status code will be 400 Bad Request.\n\n##Response format\n\n|Parameter|Type|Description|\n|-|-|-|\n|*to*|object|[Recipient destination address](#section-recipient-destination-address-types).|\n|*status*|object|Message status.|\n|*messageCount*|int|Number of recipients for targeted segment.|\n|*bulkId*|String|The ID which uniquely identifies the request.|\n\nStatus:\n\n|Parameter|Type|Description|\n|-|-|-|\n|*groupId*|int|Status [group ID](http://dev.infobip.com/v1/docs/response-codes#status-object-example).|\n|*groupName*|String|Status [group name](http://dev.infobip.com/v1/docs/response-codes#status-object-example).|\n|*id*|int|Status [ID](http://dev.infobip.com/v1/docs/response-codes#status-object-example).|\n|*name*|String|Status [name](http://dev.infobip.com/v1/docs/response-codes#status-object-example).|\n|*description*|String|Human readable [description](http://dev.infobip.com/v1/docs/response-codes#status-object-example) of the status.|\n\n\n##Notification options\nYou may choose different options on how to alert the user when PUSH message is received.\n\n|Name|Required|Default|Type|Description|\n|-|-|-|-|-|\n|vibrationEnabled|no|true|boolean|Notification vibration (Android only).|\n|soundEnabled|no|true|boolean|Sound when notification arrives on a device.|\n|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](https://github.com/infobip/mobile-messaging-sdk-android/wiki/How-to-use-custom-notification-sound%3F) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/How-to-use-custom-notification-sound%3F) usage details.|\n|badge|no|-|int|Badge counter (iOS only).|\n|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](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/Rich-notifications) since MM SDK version 2.5.8. [Supported on Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Rich-notifications) since MM SDK version 1.6.4.|\n|category|no|-|String|Category id for actionable notification. [Supported on Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Interactive-notifications) since MM SDK version 1.6.16. [Supported on iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/Interactive-Notifications) since MM SDK version 2.6.9. Predefined category ids: `mm_accept_decline` - Accept & Decline button actions.|\n\n##Recipient destination address types\nPush 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. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Push SDK\",\n  \"body\": \"Learn how to properly implement destination address type parameters in [Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data) SDK documentation.\"\n}\n[/block]\nDestination address types enabled by default:\n\n|Name|Type|Description|\n|-|-|-|\n|*pushRegistrationId*|String|Push Registration Id is unique ID which identifies application instance and specific device.|\n|*cloudType*|String|Possible values are `GCM` (Google Cloud Messaging) or `APNS` (Apple Push Notification service).|\n\nThe following destination address types are not available by default. They should be defined by User Data in SDK.\n\n|Name|Type|Description|\n|-|-|-|\n|*externalUserId*|String|External user ID set in User Profile. Learn more about external user id in [Android ](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data#external-user-id)and [iOS ](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data#external-user-id)SDK documentation.|\n|*GSM*|String|MSISDN in international format (Example: 41793026727).|\n|*email*|String|Email of the user if it is provided in User Profile.|\n|*<custom field>*|String|Any field from **custom data** parameters. Learn more about custom data in [Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data#custom-user-data) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data#custom-user-data) SDK documentation.|\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"You can use a single address type or even combine two or more to achieve a 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.\",\n  \"title\": \"Combining different address types in a single request\"\n}\n[/block]\n####Single recipient destination address type\nUse this method to target recipient's device associated with the single Push registration ID.\n```\n\"to\": {\n    \"pushRegistrationId\": \"69827EDB-A806-4AF6-A7F6-98298EAA4F14\"\n}\n```\nWith this type of targeting, you can achieve the following:\n\n  * target all iOS or Android devices\n  * target a particular device\n  * target all devices of particular external user id\n  * target all devices linked to a GSM\n  * target all devices linked to an email\n  * target all devices associated with any custom data parameter like tag, subscription or other\n\nIn the following example we are targeting all iOS devices.\n```\n\"to\": {\n    \"cloudType\": \"APNS\"\n}\n```\n\nWith this example all devices that have been associated with GSM number 41793026727 will be targeted. \n\n```\n\"to\": {\n    \"GSM\": \"41793026727\"\n}\n```\n\n####Multiple recipient destinations of the single address type (IN)\nCombining 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.\n\n```\n \"to\": {\n    \"cloudType\": [\"APNS\", \"GCM\"]\n }\n```\nBy using this method you can target all user devices by email address.\n```\n \"to\": {\n    \"email\": [\"jane.smith:::at:::somedomain.com\", \"john.smith@somedomain.com\"]\n }\n```\n\n####Multiple destination address types (AND)\nYou 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.\n\nIn the following example, all iOS devices of the recipient with a specific external ID will be targeted.\n```\n\"to\": {\n    \"cloudType\": \"APNS\",\n    \"externalUserId\": \"customer_21234\"\n}\n```\n\n####Multiple destination address types (OR)\nIn 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.\n\nIn the following example, recipients who's favorite pizza is Capricciosa or favorite pasta is Napolitana will be targeted.\n```\n\"to\": {\n    \"$or\": [\n        {\"FavoritePizza\": \"Capricciosa\"},\n        {\"FavoritePasta\": \"Napolitana\"}\n    ]\n}\n```\n\n####Advanced targeting example\nThe combination of different targeting methods is also supported.\n\nIn 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.\n```\n\"to\": {\n    \"$or\": [\n        {\"externalUserId\": \"my-ext_id-1\"},\n        {\"email\": [\"myEmail_1@domain.com\", \"myEmail_2@domain.com\"]}\n    ],\n    \"cloudType\": \"GCM\"\n}\n```\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Test your Push notifications before sending!\",\n  \"body\": \"Advanced segment targeting can get complicated and error-prone. **[Test your Push notifications request](/docs/test-push-notifications-before-sending)** before sending them out to get a feel of how many devices will be effected.\"\n}\n[/block]","excerpt":"Use this method to send a single Push notification to one or multiple recipients","slug":"send-push-notifications","type":"endpoint","title":"Send PUSH notifications"}

postSend PUSH notifications

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

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

from:
required
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:
required
object
<a href="#section-recipient-destination-address-types">Recipient destination address.</a>
text:
required
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
Aditional data that can be delivered with the PUSH message. customPayload must be formatted as JSON object.
notificationOptions:
object
<a href="#section-notification-options">JSON object that contains notification options.</a>
validityPeriod:
integer
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.
validityPeriodTimeUnit:
stringHOURS
The message validity period time unit. Supported values are: `SECONDS`, `MINUTES` and `HOURS`.
notifyUrl:
string
The URL on your callback server on which the <a href="push-sent-messages-reports">Delivery report</a> will be sent. <a href="delivery-reports-on-notify-url">Additional Information about Delivery reports on Notify URL.</a>
notifyContentType:
stringapplication/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.

Examples


Result Format


Documentation

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](#section-recipient-destination-address-types).| |*status*|object|Message status.| |*messageCount*|int|Number of recipients for targeted segment.| |*bulkId*|String|The ID which uniquely identifies the request.| Status: |Parameter|Type|Description| |-|-|-| |*groupId*|int|Status [group ID](http://dev.infobip.com/v1/docs/response-codes#status-object-example).| |*groupName*|String|Status [group name](http://dev.infobip.com/v1/docs/response-codes#status-object-example).| |*id*|int|Status [ID](http://dev.infobip.com/v1/docs/response-codes#status-object-example).| |*name*|String|Status [name](http://dev.infobip.com/v1/docs/response-codes#status-object-example).| |*description*|String|Human readable [description](http://dev.infobip.com/v1/docs/response-codes#status-object-example) 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](https://github.com/infobip/mobile-messaging-sdk-android/wiki/How-to-use-custom-notification-sound%3F) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/How-to-use-custom-notification-sound%3F) usage details.| |badge|no|-|int|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](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/Rich-notifications) since MM SDK version 2.5.8. [Supported on Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Rich-notifications) since MM SDK version 1.6.4.| |category|no|-|String|Category id for actionable notification. [Supported on Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/Interactive-notifications) since MM SDK version 1.6.16. [Supported on iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/Interactive-Notifications) since MM SDK version 2.6.9. Predefined category ids: `mm_accept_decline` - Accept & Decline button actions.| ##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. [block:callout] { "type": "warning", "title": "Push SDK", "body": "Learn how to properly implement destination address type parameters in [Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data) SDK documentation." } [/block] Destination address types enabled by default: |Name|Type|Description| |-|-|-| |*pushRegistrationId*|String|Push Registration Id is unique ID which identifies application instance and 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 ](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data#external-user-id)and [iOS ](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data#external-user-id)SDK documentation.| |*GSM*|String|MSISDN in international format (Example: 41793026727).| |*email*|String|Email of the user if it is provided in User Profile.| |*<custom field>*|String|Any field from **custom data** parameters. Learn more about custom data in [Android](https://github.com/infobip/mobile-messaging-sdk-android/wiki/User-data#custom-user-data) and [iOS](https://github.com/infobip/mobile-messaging-sdk-ios/wiki/User-data#custom-user-data) SDK documentation.| [block:callout] { "type": "warning", "body": "You can use a single address type or even combine two or more to achieve a 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.", "title": "Combining different address types in a single request" } [/block] ####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": { "cloudType": "APNS" } ``` 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": { "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 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, 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 who's 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"]} ], "cloudType": "GCM" } ``` [block:callout] { "type": "info", "title": "Test your Push notifications before sending!", "body": "Advanced segment targeting can get complicated and error-prone. **[Test your Push notifications request](/docs/test-push-notifications-before-sending)** before sending them out to get a feel of how many devices will be effected." } [/block]