1. REST API for Oracle Responsys Marketing Cloud Service
  2. Tasks
  3. Merge Trigger SMS

Merge Trigger SMS

post

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

Request

Path Parameters
Body ()
Request Body
Root Schema : Merge Trigger SMS
Type: object
Title: Merge Trigger SMS
Show Source
Nested Schema : mergeRule
Type: object
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
Show Source
  • Allowed Values: [ "OPTIN", "OPTOUT" ]
    This value must be specified as either OPTIN or OPTOUT and would be applied to all of the records contained in the API call. If this value is not explicitly specified, then it is set to OPTOUT.
  • Value of incoming preferred email format data. For example, 'H' may represent a preference for HTML formatted email.
  • Indicates what should be done for records where a match is not found (true = insert / false = no insert).
  • Allowed Values: [ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
    First match column for determining whether an insert or update should occur.
  • Allowed Values: [ "RIID_", "CUSTOMER_ID_", "EMAIL_ADDRESS_", "MOBILE_NUMBER_", "EMAIL_MD5_HASH_", "EMAIL_SHA256_HASH_" ]
    Second match column for determining whether an insert or update should occur. (optional).
  • Allowed Values: [ "NONE", "AND" ]
    Operator to join match column names
  • Value of incoming opt-in status data that represents an opt-in status. For example, 'I' may represent an opt-in status.
  • Value of incoming opt-out status data that represents an optout status. For example, '0' may represent an opt-out status.
  • String containing comma-separated channel codes that if specified will result in record rejection when the channel address field is null. Channel codes are 'E' (SMS), 'M' (Mobile), 'P' (Postal Code). For example 'E,M' would indicate that a record that has a null for SMS or Mobile Number value should be rejected. This parameter can also be set to null or to an empty string, which will cause the validation to not be performed for any channel, except if the matchColumnName1 parameter is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_. When matchColumnName1 is set to EMAIL_ADDRESS_ or MOBILE_NUMBER_, then the null or empty string setting is effectively ignored for that channel.
  • Value of incoming preferred email format data. For example, 'T' may represent a preference for Text formatted email.
  • Allowed Values: [ "REPLACE_ALL", "NO_UPDATE" ]
    Controls how the existing record should be updated.
Nested Schema : mergeTriggerRecordData
Type: object
Record data that represents Field Names and corresponding values for the recipient.
Show Source
Nested Schema : fieldNames
Type: array
Field Names in the Profile List. Note MOBILE_NUMBER_ must be specified in the E.164 format.
Show Source
Nested Schema : mergeTriggerRecords
Type: array
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : fieldValues
Type: array
Values corresponding to the fieldNames.
Show Source
Nested Schema : optionalData
Type: array
Optional data containing array of 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 SMS Response
Type: array
Title: Trigger SMS 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 Merge Trigger SMS API.

The following example shows how to merge members into a profile list and trigger SMS messages to them.

Responsys SMS campaigns that already exist can be sent to up to 200 members of a profile list.

For the list associated with the specified SMS campaign, you must specify an array of record data that contain field names and their corresponding field values.

Do not use system column names for the optional data, such as MOBILE_NUMBER_ or MOBILE_COUNTRY_. This may cause incorrect data to be processed, possibly resulting in skipped records and incorrect data being recorded in the SMS SENT Event table.

Note MOBILE_NUMBER_ is required within fieldNames and must be specified in the E.164 format.

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.

IMPORTANT NOTE: For this API call to work, the Responsys user who creates the campaign must use the campaign template "Direct API Notification" and must activate it by clicking the Activate button on the Summary page of the SMS Campaign wizard. If the Responsys user chooses a different template, such as "Broadcast," then the system returns a "CAMPAIGN_IS_INVALID" message.

This API supports hashed emails (MD5 and SHA256) when the request parameter insertOnNoMatch is set as false. In other words, inserting a new record is not allowed using email hash as a match column.

FIELDS DESCRIPTION
Authorization <AUTH_TOKEN>
Content-Type application/json

Sample Request Body:

   {
       "mergeTriggerRecordData": {
          "mergeTriggerRecords": [
              {
                  "fieldValues": [
                      "mdi1234@foobar.com",
                      "martiness",
                      "6505551212",
                      "US"
                  ],
                  "optionalData": [
                  {
                      "name": "FIRST_NAME",
                      "value": "jim_1"
                  },
                  {
                      "name": "LAST_NAME",
                      "value": "smith_1"
                  }
              ]
 
              },
              {
                  "fieldValues": [
                      "mdi.1234@foobarcorp.com",
                      "concord",
                      "6505551212",
                      "US"
                  ],
                  "optionalData": [
                   {
                      "name": "FIRST_NAME",
                      "value": "jim_2"
                   },
                   {
                      "name": "LAST_NAME",
                      "value": "smith_2"
                   }
                  ]
 
              }
         ],
        "fieldNames": [
              "EMAIL_ADDRESS_",
              "CITY_", 
              "MOBILE_NUMBER_",
              "MOBILE_COUNTRY_"
         ]
      },
      "mergeRule": {
          "htmlValue": "H",
          "matchColumnName1": "EMAIL_ADDRESS_",
          "matchColumnName2": null,
          "optoutValue": "O",
          "insertOnNoMatch": true,
          "defaultPermissionStatus": "OPTIN",
          "rejectRecordIfChannelEmpty": "E",
          "optinValue": "I",
          "updateOnMatch": "REPLACE_ALL",
          "textValue": "T",
          "matchOperator": "NONE"
      }
}

Sample Response

The response returns a status for each record sent in the request. In this example, the first record was successfully merged and the SMS message was sent to the recipient whose RIID is 72067. The second record was successfully merged, but the SMS message was undeliverable.

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

Sample Responses: Failures

Campaign is invalid. Requests fail if an incorrect campaign template is specified. 

{
	"type": "",
	"title": "Not a valid campaign",
	"errorCode": "CAMPAIGN_IS_INVALID",
	"detail": "Campaign is invalid or inactive",
	"errorDetails": []
}

Invalid country code: Requests fail if the country code provided for an E.164 requets is not valid. 

{
  "type":"",
  "title":"Invalid request parameters",
  "errorCode":"INVALID_PARAMETER",
  "detail":"Record 0 = Invalid Mobile Number Format.\r\n",
  "errorDetails":[]
}
Back to Top