Asynchronous Trigger Push Message API

The Asynchronous Trigger Push Message API has a different service URL than the standard Trigger Push Message API, but it uses the same parameters, header, and request body. The response is different: it provides the data necessary to use the Polling API endpoint results.

Note: The Asynchronous API is generally available for all Responsys customers.

Service URL:

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

Required Path Parameters:

campaignName - Name of the push campaign to send to the recipients

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Message-Expiration=<ttl value – if omitted, the system uses the default of 3600 seconds. Use this value to set an expiration time for your request.>

Request Body - Required 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:

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.

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

{
  "recipientData": [
    {
      "customerId": null,
      "emailAddress": null,
      "recipientId": 131006807,
      "mobileNumber": null,
      "emailSHA256Hash": null,
      "emailMD5Hash": null,
      "deviceId": "",
      "apiKey": "",
      "listType": "PROFILE",
      "optionalData": [
        {
          "name": "Brand",
          "value": "Durham"
        },
        {
          "name": "Fit",
          "value": "Tailored"
        }
      ]
    },
    {
      "customerId": null,
      "emailAddress": null,
      "recipientId": 100007327,
      "mobileNumber": null,
      "emailSHA256Hash": null,
      "emailMD5Hash": null,
      "deviceId": "",
      "apiKey": "",
      "listType": "PROFILE",
      "optionalData": [
        {
          "name": "Cost",
          "value": "100.00"
        },
        {
          "name": "CUSTOM2",
          "value": "custom_value"
        }
      ]
    }
  ],
  "referenceData": {
    "data": [
      {
        "key1": "value"
      },
      {
        "key2": "value"
      }
    ]
  }
}

Response Notes:

  • The system validates the request payload syntax to ensure that the payload is well-formed JSON. However, it does not validate correctness of the values. For example, it does not validate if the campaign object exists or not, nor does it validate whether the payload uses the correct property names. Subsequently, you must poll for results to learn whether the request succeeded or failed due to other reasons.
  • A successful response for the asynchronous API returns an HTTPS status code of 202 Accepted.
  • The response body contains the information you need to analyze the response that you would get from the Polling API.
    • requestId: Unique identifier of the API request. The value is alphanumeric.
    • apiName: Name of the API request that you triggered. Always asyncMergeTriggerEmail for this API request’s response.
    • status: When successful, the status value is REQUEST_ACCEPTED. This means that the payload syntax was well-formed JSON and that the request was placed in the system queue for processing. You must poll for the final result; for more information, see Polling API endpoint.
  • See Common error responses for the Asynchronous API for details about the error responses.

Sample Successful Response:

{
  "requestId": "dXRqYUhDOjoxNjE3Nzg1OTM4",
  "apiName": "asyncTriggerPush",
  "status": "REQUEST_ACCEPTED",
  "links": [
    {
      "rel": "self",
      "href": "/rest/asyncApi/v1.3/campaigns/Push_Campaign/push",
      "method": "POST"
    },
    {
      "rel": "asyncResponse",
      "href": "/rest/asyncApi/v1.3/requests/dXRqYUhDOjoxNjE3Nzg1OTM4",
      "method": "GET"
    }
  ]
}

Sample Error Response - Queue is Full:

{
    "type": "",
    "title": "Unable to submit Async request",
    "errorCode": "UNABLE_TO_SUBMIT_ASYNC_REQUEST",
    "detail": "Error in submitting aysnc request",
    "errorDetails": []
}

Learn more

Common error responses for the Asynchronous API

Trigger SMS message

Returning reference data for asynchronous requests