Parameters

The parameters below are the POST parameters that can be provided in order to send an SMS message.

NOTE: Please ensure all parameters are in UPPER CASE. All POST parameters are case sensitive.

Parameter	Required	Type	Possible/ Example Values
USERNAME	Yes	String
PASSWORD	Yes	String
ACTION	Yes	String	'send'
ORIGINATOR	No	String	Mobile Number, Sender Name, 'shared', 'dedicated'
RECIPIENT	Yes	String
CAMPAIGN	No	String	* max length 100 characters
REFERENCE	No	String	* max length 100 characters
SCHEDULE	No	Datetime	2011-12-25 00:00:00
MESSAGE_TEXT	Yes	String	See definition for allowed characters
URL	No	String
RECIPIENTMESSAGES	No	JSON Data (array)	Allows you to send up to 100 messages with one HTTP POST.
REPLYTYPE	No	String (array)	WWW, HTTP, EMAIL.
REPLYPATH	No	String (array)	URL (for POST) or Email Address.
FILE_LIST	No	String	Filename
FILE_HASH	No	String	MD5 hash value hash value of uploaded file

 

HTTP Post Parameters Definitions

USERNAME

• Type: string
• Description: This is your Username for your SMS Central account

PASSWORD

• Type: string
• Description: This is your Password for your SMS Central account

ACTION

• Type: string
• Description: To send an SMS message, please provide the string value ‘send’ (without single quotes) as this POST parameter’s value.

ORIGINATOR

• Type: string
• Description: This is the name or number your SMS message is to appear to come from, it can be alphanumeric (letters and numbers only) and can be up to a maximum of 11 characters.

* To send from one of SMS Central’s pool of shared numbers, please use the string value ‘shared’ (without single quotes).

* To send from your own dedicated numbers, cycling through them so the recipient does not receive an SMS from the same number, please use the string value ‘dedicated’ (without single quotes).

RECIPIENT

• Type: string
• Description:  This is the number you wish to send your SMS message to.  SMS Central recommends that you provide the number in International format.

An example Australian recipient value is:

CAMPAIGN

• Type: string
• Description:  This string value allows you to group messages by providing a new campaign name, or provide an existing campaign name to associate these messages to that campaign. This parameter is useful in reporting.

* If you specify a ‘shared’ or a dedicated number as the ORIGINATOR, responses to your message will also provide this campaign value.

REFERENCE

• Type: string
• Description:  This string value allows you specify your own unique value to identify the message you are sending.

* This value will also be returned in delivery receipts.
* If you specify a ‘shared’ or a dedicated number as the ORIGINATOR, responses to your message will also provide this reference value, allowing you to match replies with the message you sent. See Receive an SMS for more info.
* The ‘REFERENCE’ value must be a unique value for each message, an attempt to send 2 messages with the same ‘REFERENCE’ value will result in the message being rejected with a 513 error code.

SCHEDULE

• Type: datetime
• Description:  This datetime value allows you to schedule the message to be delivered on the day and time of your SCHEDULE parameter value. The message will sit in SMS Central’s queue’s until the scheduled date and time, upon which the message will be sent.

An example datetime value, representing December 25^th, 2011 and 3:35pm is:

MESSAGE_TEXT

• Type: string
• Description:  This is the text of the SMS message to be sent and this text must be URL encoded.Please note that only the following list of ASCII characters will be treated as GSM, all other characters will result in the message being treated as a Unicode message:
  a-z
  A-Z
  0-9
  ~!@#$%^&*()-_=+][?<>,'.":/\{}
  (whitespace)
  

* Please note: A standard SMS message has a maximum of 160 characters. Longer messages are definitely possible, however please be aware that exceeding 160 characters will constitute a ‘second’ message.
When a message is longer than 160 characters, this is referred to as a multi-part message as it contains multiple messages (or multiple-parts). The total SMS limit then becomes 153 characters per ‘part’ as the 7 characters are used up by invisible headers and footers which denote which part of the message is being sent (i.e. Part 1 of 2). For example:

1 message = 160 characters available
2 messages = 306 characters available (153+153)
3 messages = 459 characters available (153+153+153)
4 messages = 612 characters available (153+153+153+153)
5 messages = 760 characters available (153+153+153+153+153)
6 messages = 918 characters available (153+153+153+153+153+153)
7 messages = 1071 characters available (153+153+153+153+153+153+153)
ETC

Note: If your message is treated as a Unicode message (due to having characters not within the GSM character set), a single Unicode SMS message has a maximum of 70 characters. Longer messages are possible, however in this case each message part will contain a maximum of 67 characters.

URL

• Type: string
• Description: By providing a URL to content in this optional parameter, the message will be converted into a WAP Push message. In this case the value within the MESSAGE_TEXT field will be the WAP message label.

RECIPIENTMESSAGES

• Type: JSON data (array)
• Description: The value for this parameter is JSON data (array) which contains the ‘RECIPIENT’, ‘MESSAGE_TEXT’ and ‘REFERENCE’ (optional) values for each of the (up to) 100 messages, where ‘RECIPIENT’ is the mobile number of the recipient, and ‘MESSAGE_TEXT’ is the specific text of the message to be delivered to that recipient and ‘REFERENCE’ is the string value of a unique reference that you can apply to the message (also to be used for delivery receipt tracking).

* This parameter will accept up to 100 messages in the one HTTP POST.
An example value, in JSON format is:

If a value for the ‘RECIPIENTMESSAGES’ parameter is provided in your HTTP POST, the ‘RECIPIENT’ and ‘MESSAGE_TEXT’ and ‘REFERENCE’ POST Parameters will be ignored and the values in this JSON data will be applied.

Please ensure you send via HTTP POST if you intend to utilise the RECIPIENTMESSAGES parameter

* Please note: Sending (up to) 100 messages via the RECIPIENTMESSAGES parameter will still receive the same ‘Response to your HTTP POST’. If any of the 100 messages is rejected due to an invalid number, all 100 messages will be rejected and the entire JSON Data batch (HTTP POST) will need to be re-sent, to deliver the messages.

REPLYTYPE

• Type: string
• Description: This is an optional field, allowing you to indicate that you would like Reply messages to the SMS message you are sending, to be forwarded to an Email Address or web URL (as specified in REPLYPATH). The acceptable values for this parameter are: EMAIL, WWW, HTTP. These values are case-sensitive. A value of EMAIL will indicate the reply should be forwarded to an email address. A value of WWW or HTTP will indicate the reply should be forwarded to a URL (this also includes an HTTPS URL).

* Please note: If the 'REPLYTYPE' is provided, then a value for REPLYPATH is mandatory.

REPLYPATH

• Type: string
• Description: If the REPLYTYPE parameter is provided, the REPLYPATH parameter is also required. This parameter allows you to indicate the location where Reply messages to the SMS message you are sending, should be forwarded.
  If your ‘REPLYTYPE’ parameter value is ‘EMAIL’ the REPLYPATH acceptable value is a valid format email address.
  If your ‘REPLYTYPE’ parameter value is ‘WWW’ or ‘HTTP’ the REPLYPATH acceptable value is a URL or IP address (preceded by HTTP or HTTPS).

Within the URL provided as your REPLYPATH value, there are specific query string parameters you may specify, with tags, which we will then substitute with actual values. For example:

http:///www.yourcompany.com?phone=#ORIGINATOR#&msg=#MESSAGE_TEXT#&date_sent=# SENTDTS#&DATE_RECEIVED=#RCVDDTS#&recipient=#RECIPIENT#

The above query string parameters of #FROM# and #MESSAGE_TEXT#, #RECIPIENT# and #SENTDTS# and #RCVDDTS# will be replaced with the actual values such. The following list indicates what each of those tags represent.

#FROM# - This represents the mobile number of the handset
#ORIGINATOR# - This represents the mobile number of the handset
#RECIPIENT# - This represents the number being replied to
#MESSAGE_TEXT# - This represents the text of the message
#SENTDTS# - Datetime of the time the original outbound message was sent
#RCVDTS# - Datetime of the time the reply message was received

 * Please note: When sending the REPLYPATH value as a POST or GET parameter, it must be URL-encoded. If you are providing the REPLYPATH within the JSON-encoded RECIPIENTMESSAGES parameter, it does not need to be URL-encoded as the JSON-encoding is sufficient.

Attaching a compressed pipe-delimited file
SMS Central provides functionality allowing you to send a much larger batch of messages than the ‘RECIPIENTMESSAGES’ limitation of 100 messages. You may attach a compressed pipe-delimited file with the API request, which may contain up to One Million SMS messages (1,000,000 SMS). In doing so, the ‘RECIPIENTMESSAGES’ parameter will be ignored and the following will apply:

FILE_LIST

• Type: string
• Description: This is the file name of the file being attached to the request. Please note

(1) the uncompressed file name must end in “.csv” or “txt” to be considered valid. 

(2) the file must contain the header (or empty line) in the first line of the file, as the first line is ignored.

FILE_HASH

• Type: string
• Description: This is the MD5 hash value of the file you are attaching, essentially allowing SMS Central to validate the file and data being provided.

Structure of the compressed pipe-delimited file
• The file may be compressed using ZIP format.
• Structure of the pipe-delimited file is:
Header: id|recipient|message_text|originator
Sample: 123456|61406040271|”Hello World”| 61435800957

The fields available (as listed in the Header above) are:

id
This is equivalent to the ‘REFERENCE’ parameter and is a unique value that you may provide for the message.

recipient
This is the mobile number of the recipient of the message to be sent

message_text
This is the text of the message. This is an optional value, if no value is provided, the value in the ‘MESSAGE_TEXT’ POST/GETparameter will be used.

originator
This is the name or number your SMS message is to appear to come from, it can be alphanumeric (letters and numbers only) and can be up to a maximum of 11 characters. This is an optional value and if none is provided, the ‘ORIGINATOR’ POST/GET parameter value will be used.

Response

Your HTTP POST will give you a response providing you with an immediate result of your SMS send.

SMS Central will always return a “HTTP/1.1 200 OK” HTTP status code in the header of the response to your HTTP POST.

The content of the response will contain the Success or Error response code and the corresponding success or error response message. Please see Success and Error Response Codes for a list of all possible response codes.

A response code with the number ‘0’ indicates that your HTTP POST was successful and the message is being processed for delivery.

A successful HTTP POST to Send an SMS will result in the following content in the HTTP Response:

A response to your HTTP POST indicating an error will contain the error response code and description in the same line, separated by whitespace. An example of such a response is as follows:

Please note: These results are not delivery receipt results; they are there to provide you with information on the success of your HTTP POST, not the message delivery itself.

Please see Receive DLRs for receiving final carrier delivery confirmation status via Delivery Receipts.