Home / APIs / MessageContact Send

MessageContact Send

8232 points
Michael Clark's picture

The MessageContact Send option allows you to initiate an SMS message using this API. That request optionally allows you to pass the text of the message to override the message specified in the definition. Finally, that request allows recipients to be subscribed to an existing keyword specified in the request. You can use a single request to send a message and opt-in to a keyword.

Operation URL

https://www.exacttargetapis.com/sms/v1/messageContact/{messageId}/send

URL Parameters:

  • messageId - The API Key of the message definition (configured in the MobileConnect user interface)

JSON Parameters:

  • mobileNumbers - Array of numeric mobile numbers to which the message will be sent (250 numbers maximum)
  • Subscribers - Array of the subscriber records that the message will be sent to (250 subscribers maximum). This is different from mobileNumbers in that it allows for specifying a SubscriberKey value along with the mobile number which will be use as the unique identifier for that record.
    • MobileNumber - The mobile number for the subscriber
    • SubscriberKey - The unique key value used to identify the subscriber record
  • Subscribe (Optional) - True/False value indicating whether records should also be subscribed to provided keyword
  • Resubscribe (Optional) - True/False value indicating whether records should also be resubscribed to the keyword provided
  • keyword (Optional) - An existing keyword within your account (required when the Subscriber/Resubscribe optional parameters are set to True)
  • Override (Optional) - True/False value used to change the message to the value provided in the MessageText parameter
  • messageText (Optional) - Text string used to override the text on the Message
  • BlackoutWindow (Optional) - Details about the window of time where messages should not be sent. Messages initated outside of this window will be queued and delivery once the window is open.
    • UtcOffset - The number of hours off of UTC that the window values are defined in.
    • WindowStart - The start time of the period during which subscribers cannot receive messages.
    • WindowEnd - The end time of the period during which subscribers cannot receive messages.
  • SendTime (Optional) - Date and Time in UTC that the message will go out. Example format: 2012-10-17 17:01. The BlackoutWindow will still be respected if used with this option.
  • ContentURL (Optional) - The URL of the media content sent via an MMS message.

Example Request (Using MobileNumbers)

POST https://www.exacttargetapis.com/sms/v1/messageContact/MzA6Nzg6MA/send?access_token=...
Content-Type: application/json
{
    "mobileNumbers": [
	"13175551212"
    ],
    "Subscribe": true,
    "Resubscribe": true,
    "keyword": "JOINSMS",
    "Override": true,
    "messageText": "Welcome to Code@",
    "ContentURL" : "http://image.exct.net/lib/fe6d15707662057c7411/m/1/dj_CC_AUS.jpg"
    "BlackoutWindow": {
	"UtcOffset": "-0500",
	"WindowStart": "1500",
	"WindowEnd": "2200"
    },
    "SendTime": "2012-10-05 20:01"
}

If all values in the request are valid, the following response returns with a token that can be used to make a follow-up call to check the status of the request:

Example Response

HTTP/1.1 202 Accepted
{
  "tokenId": "c21NCNSDN2sMMWM2miosdjEHH",
}

If the request was not valid, a 400 response returns with details on the error. The example below includes the following errors:

  • The keyword does not exist in the account
  • The mobile number includes hyphens

Example Response

HTTP/1.1 400 Bad Request
{
  "errors" : ["1-317-555-1212 is not a numeric string",
      "Keyword TestKeyword is invalid for the code on the message"]
}

Example Request (Using Subscribers)

You can also pass an additional identifier with the mobile number in order to provide an alternate unique value for referencing these records. You cannot pass both a the Subscribers parameter and an additional mobileNumber parameter outside of a Subscribers parameter. Choose the option that best fits your call.

POST https://www.exacttargetapis.com/sms/v1/messageContact/MzA6Nzg6MA/send?access_token=...
Content-Type: application/json
{
    "Subscribers": [
	{
	"MobileNumber": "15555554410",
	"SubscriberKey": "ExampleSubKey"
	}
    ],
    "Subscribe": "true",
    "Resubscribe": "true",
    "keyword": "JOINSMS",
    "Override": "false",
    "BlackoutWindow": {
	"UtcOffset": "-0500",
	"WindowStart": "1500",
	"WindowEnd": "2200"
    },
    "SendTime": "2012-10-05 20:01"
}

Possible Errors

Message Details
Message id {0} is not valid. The messageID value provided in the URL was not in a valid format.
Message {0} is not valid for the client. The messageID value included in the URL does not match a valid value within the account.
The count of mobile numbers or subscribers cannot be zero. At least one value needs to be passed in the mobileNumbers parameter or in the Subscribers parameter.
An array of mobile numbers and an array of subscribers cannot be provided at the same time. When passing in the target audience, either the mobileNumbers parameter or the Subscribers parameter must be used, but not both in a single request.
A subscriber object must have both a mobile number and subscriber key defined. The subscriber details being passed is missing either the MobileNumber or SubscriberKey parameter.
Keyword cannot be blank when Subscribe and/or Resubscribe are true. If the Subscribe or Resubscribe options are set to true then the keyword parameter needs to be specified.
Keyword is not necessary when Subscribe and Resubscribe are false Keyword value is not needed if the Subscribe and Resubscribe options are not being used.
Keyword {0} is invalid for the code on the message. The keyword provided does not exist for the provided messageId.
Message is blank and no override message was provided. The message definition within the MobileConnect interface does not have a message specified so the messageText parameter is required.
Cannot override message text with a blank message. The parameter for Override was set to true, but the value passed for messageText does not contain a value.
MessageText is not applicable when Override is false. The call does not require passing a value for messageText if Override is set to true.
An unexpected error occurred, please contact Customer Support with reference id {0} If this unexpected error is presented when making a call, please take note of the reference id value returned in the error and contact ExactTarget Global Support for more information.

API Console

Product Group: