Trigger Push Messages

Use the following interface to trigger Push campaign 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 up to 200 members of a Profile List and its 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 the following: 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 apiKey and deviceId 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 to customize 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 symbol € is escaped as \u20AC, the yen symbol ¥ is escaped as \u00A5, an ü is escaped as \u00FC, an é is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.

Service URL:

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

Required Path Parameter:

campaignName

Request Method:

POST

Request Header:

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, 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 + app combinations that the known mobile app user has installed.

{
  "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 for 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 in case of 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 whose App Channel List RIID is 72067. For the second record, the trigger push message action was not successful, because listType was set to PROFILE, a record was present in the Profile List, CHANNEL_DELIVERABILITY_STATUS_ is D (Deliverable) in the App Channel List, 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 in case of 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": []
}