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

Trigger SMS Message

post

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

Request

Path Parameters
Body ()
Request Body
Root Schema : Trigger SMS Message
Type: object
Title: Trigger SMS Message
Show Source
Nested Schema : recipientData
Type: array
Array of Recipients with Optional Data
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : optionalData
Type: array
Array of optional data containing name value pairs.
Show Source
Nested Schema : recipient
Type: object
Information about the Recipient.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : listName
Type: object
Profile List to which the Recipient belongs.
Show Source
Back to Top

Response

Supported Media Types

Default Response

Body ()
Root Schema : Trigger SMS Message
Type: object
Title: Trigger SMS Message
Show Source
Nested Schema : recipientData
Type: array
Array of Recipients with Optional Data
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : optionalData
Type: array
Array of optional data containing name value pairs.
Show Source
Nested Schema : recipient
Type: object
Information about the Recipient.
Show Source
Nested Schema : items
Type: object
Show Source
Nested Schema : listName
Type: object
Profile List to which the Recipient belongs.
Show Source
Back to Top

Examples

Use the following API to trigger SMS messages to existing members of a Profile List.

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.

Request Notes:

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

Sample Request Body:

{
  "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: 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. 

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