Trigger SMS message

Use this interface to trigger SMS messages to existing members of a profile list. Responsys will send personalized SMS messages to mobile phone numbers.

If you also want to merge members into a Profile List before triggering an SMS message, see Merge Trigger SMS.

REQUEST NOTES:

• You can trigger a message for MD5 and SHA256 email hashes. Include emailMD5Hash and emailSHA256Hash as properties for the recipient to do so.
• The endpoint will validate whether the mobile number format is E.164. The endpoint will behave differently depending on the format:
  • When the mobile number format is E.164:
    • Records are skipped when the country is not served by the country code used for the campaign.
  • When the mobile format is not E.164:
    • Records are triggered based on the country code irrespective of the mobile numbers.
    • Records are skipped when there is no mobile country code.
    • Records are skipped when the country is not served by the country code used for the campaign.

Service URL:

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

Required Path Parameter:

campaignName - Name of the SMS campaign to send to the recipients.

Request Method:

POST

Request Header:

Authorization=<AUTH_TOKEN>

Content-Type=application/json

Sample Request Body:

Refer to the online REST API reference for an explanation of each property.

{
  "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"
        }
      ]
    }
  ]
}

Sample Response in case of success:

The response returns information about each record sent in the request. In this example, the SMS message was sent successfully to the recipient device for which the RIID is 72067.

[
  {
    "errorMessage": "Message triggered successfully",
    "success": true,
    "recipientId": 72067
  },
  {
    "errorMessage": "Mobile number not found",
    "success": false,
    "recipientId": -1
  }
]

Sample Responses: Failures

Recipient not found: Requests will fail if there are no matching recipients found in the Profile List.

{
  "errorMessage": "NO_RECIPIENT_FOUND: Recipient Not Found",
  "success": false,
  "recipientId": -1
}

Campaign not found: Requests fail if the campaign specified in the request is not found in the Responsys account.

{
  "type": "",
  "title": "Campaign not found",
  "errorCode": "CAMPAIGN_NOT_FOUND",
  "detail": "WS_SMS_DAPI_REST1 Campaign Not Found",
  "errorDetails": []
}

Invalid Mobile format: Requests fail if any mobile phone numbers specified do not follow the format:

{
  "errorMessage": "INVALID_MOBILE_NUMBER_FORMAT: Invalid Mobile Number Format",
  "success": false,
  "recipientId": -1
}

Invalid Campaign Type: Requests fail if the campaign specified in the request is not a SMS campaign.

{
  "type": "",
  "title": "Invalid Campaign Type",
  "errorCode": "INVALID_CAMPAIGN_TYPE",
  "detail": "{campaignName} is not a Sms Campaign'",
  "errorDetails": []
}

Folder or object name not found: Requests fail if the folder, or a list are not found. Error resembles:

{
  "type": "",
  "title": "Invalid request parameters",
  "errorCode": "INVALID_PARAMETER",
  "detail": "Missing folder name or Object name",
  "errorDetails": []
}

API limit exceeded: When the client application exceeds the throttling limit for this API, a 401 Unauthorized error is returned with the following error response body. Refer to Get Throttling Limits to learn more. Error resembles:

{
  "type": "API_Limit_Exceeded",
  "title": "",
  "errorCode": "API_LIMIT_EXCEEDED",
  "detail": "",
  "errorDetails": []
}

Record limit exceeded: Requests fail if more than 200 recipients are specified in the request.

{
  "type": "Record_Limit_Exceeded",
  "title": "Record limit exceeded",
  "errorCode": "RECORD_LIMIT_EXCEEDED",
  "detail": "Record limit exceeded, maximum of 200 records are allowed per each api call",
  "errorDetails": []
}

Invalid field name: Requests fail if you have specified a field, but that field cannot be found in the specified list.

{
  "type": "",
  "title": "Invalid field name",
  "errorCode": "INVALID_FIELD_NAME",
  "detail": "Column(s) [RIID] not found in the list",
  "errorDetails": []
}

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

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