API Personalization

This topic explains how to add custom data when working with trigger email, sms, and push message API endpoints.

In this topic:

• API Personalization
• Introduction
• Personalization in the payload
• Personalization in Responsys
• Examples
• Trigger Email
• Trigger Push Message
• Trigger SMS Message
• Endpoint support for personalization
• Considerations

Introduction

Your application can pass personalization data through the API payload. This personalization enables you to send more data into Responsys, thereby giving you the ability to customize the messages you send to your customers.

Personalization in the payload

Personalization data is specified in the optionalData array as attribute-value pairs. For example, you can define "COUPON_CODE" as a personalization attribute and then pass its value in the API payload as an attribute-value pair, so that coupon code doesn't have to be in any table.

"optionalData": [
  {
    "name": "COUPON_CODE",
    "value": "WELCOME5"
  }
]
...

Personalization in Responsys

Developers should work with marketers to determine which fields should be passed in the API request as optional data. Marketers should then add the fields to their Campaign Data Sources as Dynamic Variables where a unique Dynamic Variable must exist for each name-value pair, where the "name" and the Dynamic Variable name match.

The Dynamic Variable is referenced in the creative using RPL: ${DynamicVariable.dynamicVariableName}.

This is the same setup if the transient value is passed via Program using Entry Tracking Variables (ETV). There, the ETV name and the Dynamic Variable name must match.

Examples

This section lists personalization payload examples.

Trigger Email

Trigger an email containing a coupon code.

{
  "recipientData": [
    {
      "recipient": {
        "customerId": "1",
        "emailAddress": "john.doe@oracle.com",
        "listName": {
          "folderName": "WS_REST_SAMPLE",
          "objectName": "wsrest"
        },
        "recipientId": null,
        "mobileNumber": null,
        "emailFormat": "HTML_FORMAT"
      },
      "optionalData": [
        {
          "name": "COUPON_CODE",
          "value": "WELCOME5"
        }
      ]
    }
	

Trigger Push Message

Trigger a push message containing a purchased item name.

{
  "recipientData": [
    {
      "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": "PURCHASED_ITEM",
          "value": "Stonewash Jeans"
        },
        {
          "name": "PURCHASED_PRICE",
          "value": "$100"
        }
      ]
    }
  ]
}
	

Trigger SMS Message

Trigger an SMS message with a product SKU and product name.

{
  "recipientData": [
    {
      "recipient": {
        "customerId": "1",
        "mobilenumber": "919845098450",
        "listName": {
          "folderName": "My_Folder_Name",
          "objectName": "My_Profile_List"
        },
        "recipientId": "72067"
      },
      "optionalData": [
        {
          "name": "PRODUCT_SKU",
          "value": "123456"
        },
        {
          "name": "PRODUCT_NAME",
          "value": "Jeans"
        }
      ]
    }
  ]
}

Endpoint support for personalization

• Email Trigger

• Push Trigger

• SMS Trigger

Considerations

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

[personalization]