1. REST API for Oracle Responsys Marketing Cloud Service
  2. Tasks
  3. Trigger Push Message

Trigger Push Message

post

/rest/api/v1.3/campaigns/{campaignName}/push

Request

Path Parameters
Body ()
Request Body
Root Schema : Trigger Push Message
Type: object
Title: Trigger Push Message
Show Source
Nested Schema : recipientData
Type: array
Array of Recipients with Optional Data
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : optionalData
Type: array
Array of optional data containing name value pairs.
Show Source
Nested Schema : items
Type: object
Show Source
Back to Top

Response

Supported Media Types

Default Response

Body ()
Root Schema : Trigger Push Response
Type: array
Title: Trigger Push Response
Array of Recipient Results.
Show Source
Nested Schema : items
Type: object
Response for individual recipient.
Show Source
Back to Top

Examples

Tip:

Need Higher API Call Limits? We have an API on Asynchronous API with the same functionality. Please use the Asynchronous Trigger Push Message API.

Use the following API to trigger push messages to existing members of a Profile List and its corresponding App Channel List.

Request Notes:
  • You can send push messages to existing Responsys Push campaigns for to up to 200 members of a Profile List and its corresponding App Channel List.
  • The request payload allows specifying one of the available Profile List attributes, so that you may uniquely identify the recipients of the push message.
  • The Profile List attributes that can be specified are one of recipientId, customerId, emailAddress, mobileNumber, emailSHA256Hash, or emailMD5Hash.

    NOTE: In the request body, all recipientData must be present but the Profile List attributes you are not using must be set to null.

  • Use the listType attribute PROFILE when recipients need to be matched from Profile List (that is, known recipients).

    NOTES:

    • The Profile List members selected using these attributes are matched against the App Channel list to find the device IDs of all devices to trigger push messages.
    • You can send to all devices and apps that a mobile app user has installed by setting "apiKey": null.
    • You can send to a specific mobile app that a user has installed by specifying the apiKey value. Note that you may only use one apiKey value per recipient. This means that if a mobile app end user (recipient) has a single entry in a Profile List but has multiple entries in the App Channel List for different apps, the apiKey attribute restricts the push message to trigger for one of those apps.
  • Use the listType attribute PUSH when recipients need to be matched from App Channel List (that is, unknown recipients).

    NOTES:

    • In the request body, all recipientData properties must be present, but the Profile List attributes you are not using must be set to null.
    • When using listType of PUSH, the App Channel List attributes that you must specify are both deviceId and apiKey. Including both deviceId and apiKey ensures that push messages will only be triggered for devices that match the apiKey.
  • You can use the optionalData attribute as part of the payload is used for customizing the push message.
    • Do not use system-defined fields (for example, MOBILE_NUMBER_) for your optional data.
    • To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro currency symbol is escaped as \u20AC, the yen currency symbol is escaped as \u00A5, an umlauted u is escaped as \u00FC, an accented e is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.
FIELDS DESCRIPTION
Authorization <AUTH_TOKEN>
Content-Type application/json

Sample Request Body:

The following Trigger Push Message request payload example is requesting that Responsys send a Push campaign message to two recipients:
  • The first recipient is an unknown user. Unknown users are those for whom Responsys has device data in the App Channel List, but there is no match between the App Channel List record and a Profile List record. Because the user is not known, the recipient's listType is PUSH, deviceId contains recipient device's deviceId value, and apiKey contains the API_KEY value of the mobile app installed on the recipient device.
  • The second recipient is a known user. Known users are those for whom Responsys has a matching Profile List record for an App Channel List record. Because the user is known, the recipient's listType is PROFILE. Also, because the API_KEY for the mobile app specified in the apiKey property, the push message is being sent to that specific app. When the apiKey property is null, Responsys sends the push message to all device and app combinations that the known mobile app user has installed.

NOTE: In your code, ensure that deviceId and apiKey contain the actual values. 

   {
    "recipientData": [
        {
            "customerId": null,
            "emailAddress": null,
            "recipientId": null,
            "mobileNumber": null,
            "emailSHA256Hash": null,
            "emailMD5Hash": null,
            "deviceId": "device_Id_value",
            "apiKey": "API_Key_value",
            "listType": "PUSH",
            "optionalData": [
                {
                    "name": "CUSTOM1",
                    "value": "c1a_value_new"
                },
                {
                    "name": "CUSTOM2",
                    "value": "c2a_value_new"
                }
            ]
        },
        {
            "customerId": null,
            "emailAddress": "foo.bar@oracle.com",
            "recipientId": null,
            "mobileNumber": null,
			"emailSHA256Hash": null,
            "emailMD5Hash": null,
            "deviceId": null,
            "apiKey": "API_Key_value",
            "listType": "PROFILE",
            "optionalData": [
                {
                    "name": "CUSTOM1",
                    "value": "c1a_value_new"
                },
                {
                    "name": "CUSTOM2",
                    "value": "c2a_value_new"
                }
            ]
        }
    ]
}
Response Notes:
  • The recipientId displayed in the Trigger Push Message response body is the App Channel List RIID. (This differs from the API responses when sending to other channels, such as Email and SMS, which use the RIID from the Profile List.)
  • The success results returned in the Trigger Push Message response body may vary from actual results, depending on the intended recipient's CHANNEL_DELIVERABILITY_STATUS_ and CHANNEL_PERMISSION_STATUS_ settings in the App Channel List. Consult the EventDB to verify whether the system sent the messages.
    • When CHANNEL_DELIVERABILITY_STATUS_ is D (Deliverable) but CHANNEL_PERMISSION_STATUS_ is O (OptOut):

      If the request was sent with listType of PUSH, the API response returns "success":true but in the EventDB, the record is shown as SKIPPED because the recipient is not found. This occurs whether a record is present in the Profile List or not.

      However, when request is sent with listType of PROFILE and a record is present in the Profile List, the API response sends "success":false and "errorMessage" : "RECIPIENT_STATUS_UNDELIVERABLE: Recipient deliverability status is undeliverable".

    • When CHANNEL_DELIVERABILITY_STATUS_ is U (Undeliverable) and CHANNEL_PERMISSION_STATUS_ is O (OptOut), the API response returns "success":true but in the EventDB, the record is shown as SKIPPED because the recipient is not found. This occurs regardless of the listType setting and whether or not there is a record present in the Profile List.

Sample Response: Success

The response returns information about each record sent in the request. In this example, the mobile push message was sent successfully to the recipient device for which the App Channel List RIID is 72067. For the second record, the trigger push message action was not successful, because because listType was set to PROFILE, a record was present in the Profile List, CHANNEL_DELIVERABILITY_STATUS_ was D (Deliverable) in the App Channel List record, but the recipient's CHANNEL_PERMISSION_STATUS_ in the App Channel List was set to O (OptOut). 

[{
	  "errorMessage" : null,
	  "success" : true,
	  "recipientId" : 72067
	 },{
	  "errorMessage" :"RECIPIENT_STATUS_UNDELIVERABLE: Recipient deliverability status is undeliverable ",
	  "success" : false,
	  "recipientId" : -1
	 }

]

Sample Response: Failure

In this example, none of the recipients received the mobile push message, because the system could not find the campaign name sent in the request.

	{
   "type": "",
   "title": "Campaign not found",
   "errorCode": "CAMPAIGN_NOT_FOUND",
   "detail": "Campaign not found with name [campaignName]" ,
   "errorDetails": []
	}
Back to Top