Merge Trigger SMS
/rest/api/v1.3/campaigns/{campaignName}/sms
Request
-
campaignName: string
Campaign Name
object
Merge Trigger SMS
-
mergeRule:
object mergeRule
Merge rule used to merge recipient records in a Profile List. Only used during the merge operation.
-
mergeTriggerRecordData:
object mergeTriggerRecordData
Record data that represents Field Names and corresponding values for the recipient.
object
-
defaultPermissionStatus(optional):
string
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. -
htmlValue(optional):
string
Value of incoming preferred email format data. For example, 'H' may represent a preference for HTML formatted email.
-
insertOnNoMatch(optional):
boolean
Indicates what should be done for records where a match is not found (true = insert / false = no insert).
-
matchColumnName1(optional):
string
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. -
matchColumnName2(optional):
string
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). -
matchOperator(optional):
string
Allowed Values:
[ "NONE", "AND" ]
Operator to join match column names -
optinValue(optional):
string
Value of incoming opt-in status data that represents an opt-in status. For example, 'I' may represent an opt-in status.
-
optoutValue(optional):
string
Value of incoming opt-out status data that represents an optout status. For example, '0' may represent an opt-out status.
-
rejectRecordIfChannelEmpty(optional):
string
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.
-
textValue(optional):
string
Value of incoming preferred email format data. For example, 'T' may represent a preference for Text formatted email.
-
updateOnMatch(optional):
string
Allowed Values:
[ "REPLACE_ALL", "NO_UPDATE" ]
Controls how the existing record should be updated.
object
-
fieldNames:
array fieldNames
Field Names in the Profile List. Note
MOBILE_NUMBER_
must be specified in the E.164 format. -
mergeTriggerRecords:
array mergeTriggerRecords
Array of values corresponding to the fieldNames. Each element in the array represents a single recipient.
array
MOBILE_NUMBER_
must be specified in the E.164 format.array
object
-
fieldValues(optional):
array fieldValues
Values corresponding to the fieldNames.
-
optionalData(optional):
array optionalData
Optional data containing array of name value pairs.
array
Response
- application/json
Default Response
array
Trigger SMS Response
-
Array of:
object items
Response for individual recipient.
object
-
errorMessage(optional):
string
Error Message, if any, that occurred during the merge or trigger operations.
-
recipientId(optional):
number
The Responsys ID (RIID) of the recipient.
-
success(optional):
boolean
Indicates success or failure.
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":[] }