Trigger Push Message API (HA Async)

Use the following interface to trigger Push campaign messages to existing members of a Profile List and its corresponding App Channel List. This endpoint is the AFTM alternative to Asynchronous Trigger Push Message API

Service URL:

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

Required Path Parameters:

campaignName - Name of the SMS campaign to be sent to the recipients.

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Request Body Properties:

See the Trigger Push Message Endpoints page in the Oracle Responsys REST API Guide. View the Request body section of the topic.

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": "PROFILE" when recipients need to be matched from Profile List (that is, known recipients).

  • 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": "PUSH" when recipients need to be matched from App Channel List (that is, unknown recipients).

  • 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": "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.

• This endpoint supports sending reference data in requests. To learn how you can retrieve this data when polling, refer to Returning reference data for asynchronous requests.

Sample Request Body:

{
  "recipientData": [
    {
      "customerId": null,
      "emailAddress": null,
      "recipientId": 131006807,
      "mobileNumber": null,
      "emailSHA256Hash": null,
      "emailMD5Hash": null,
      "deviceId": "",
      "apiKey": "",
      "listType": "PROFILE",
      "optionalData": [
        {
          "name": "CUSTOM1",
          "value": "WELCOME10"
        },
        {
          "name": "CUSTOM2",
          "value": "COUPON"
        }
      ]
    },
    {
      "customerId": null,
      "emailAddress": null,
      "recipientId": 100007327,
      "mobileNumber": null,
      "emailSHA256Hash": null,
      "emailMD5Hash": null,
      "deviceId": "",
      "apiKey": "",
      "listType": "PROFILE",
      "optionalData": [
        {
          "name": "CUSTOM1",
          "value": "DISCOUNT10"
        },
        {
          "name": "CUSTOM2",
          "value": "COUPON"
        }
      ]
    }
  ]
}

Sample Response:

NOTES:

• A successful response for the asynchronous API returns an HTTPS status code of 202 Accepted.
• A successful response returns a requestId, to be used in the Polling API endpoint to retrieve the status of your request.
• See Common error responses for the Asynchronous API for details about the error responses.

{
  "requestId": "YjN1aWowOjoxNjQzOTUyMjI0",
  "apiName": "HaAsyncTriggerPush",
  "status": "REQUEST_ACCEPTED",
  "links": [
    {
      "rel": "self",
      "href": "/rest/haAsyncApi/v1.3/campaigns/Summer_Push/push",
      "method": "POST"
    },
    {
      "rel": "asyncResponse",
      "href": "/rest/haAsyncApi/v1.3/requests/YjN1aWowOjoxNjQzOTUyMjI0",
      "method": "GET"
    }
  ]
}

Learn more

Common error responses for the Asynchronous API