Parameters

To send an on-demand request to retrieve SMS messages that have been received, please send a HTTP POST to the API URL with the following POST parameters.

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 view received SMS messages, please provide the string value ‘read’ (without single quotes) as this POST parameter’s value.

DATESTART

• Type: datetime
• Description: To specify a day and time for how far back you wish to retrieve the received SMS messages, please specify this day and time in datetime format.
  * For example, if you wish to retrieve messages newer than and including 25 December, 2011 and 3:35pm is:

  2011-12-25 15:35:00

DATEEND

• Type: datetime
• Description: To specify a day and time for an end period for which you wish to retrieve the received SMS messages, please specify this day and time in datetime format.

For example, if you wish to receive messages up until and including 25 December 2011, please provide the value of 2011-12-25 23:59:59

STATUS

• Type: string
• Description: This STATUS parameter allows you to specify which type of messages you would like to retrieve, the options, to be provided as values (all characters uppercase) are:
  • ‘ALL’ – this will retrieve all received SMS messages, for the dates specified in DATESTART to DATEEND (or every single message, if no values are provided for those parameters)
  • ‘UNREAD’ – this will retrieve all SMS messages, for the dates specified in DATESTART to DATEEND, which are marked as unread. Please note that retrieving unread messages will result in them consequently being marked as read
  • ‘READ’ – this will retrieve all received SMS messages, which have been marked as read (either by retrieving unread messages via the API, or marking them as read by logging in to your SMS Central account).

CAMPAIGN

• Type: string
• Description: The campaign parameter allows you to retrieve the reply messages to the campaign you may have just sent. By providing the name of the campaign (URL encoded) as per the value provided via the CAMPAIGN parameter when sending an SMS, you can retrieve reply messages to that campaign. For example, you may provide the CAMPAIGN value of the name of your campaign and the STATUS value of 'UNREAD' in order to retrieve new (unread) reply messages to your campaign.

Response

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 to your HTTP POST will be in XML format when messages are received, or a simple string if there was an error with your request.

The XML Response will contain a collection of <message> tags, inside a single <messages> tag.

Each <message> tag will contain the following tags wrapped within:

• <datestamp> - this is the date the message was received
• <direction> - this will always be ‘MO’ which stands for Mobile Originated and represents an inbound message
• <originator> - this is the mobile number of the handset which sent in the message
• <recipient> - this is the mobile number that the handset was sending the message to
• <messagetext> - this is the text message content that was received

Example of a Successful Response To Your Request (type: XML)

<messages>

      <message>

            <datestamp>2011-10-13 21:28:44</datestamp>

            <direction>MO</direction>

            <originator>61xxxxxxxxx</originator>

            <recipient>61xxxxxxxxx</recipient>

            <messagetext>Lorem ipsum dolor sit amet</messagetext>

      </message>

</messages>

Possible Error Responses To Your Request (type: string)

SMS Central also provides the option to retry the forwarding of the delivery receipt to your URL, in the event that your server may be having issues or experiencing downtime.

Within the ‘Rules & Triggers’ section of the SMS Central portal, you’re able to enable the retry logic when setting up your forwarding rules.

In doing so, in the event that the nominated URL does not provide an adequate response or is experiencing downtime, SMS Central will continually retry the forwarding to your URL up to 10 times, with an increased delay of 5 minutes between each attempt. For example:

attempt 1: 2014-01-02 10:15:00
attempt 2: 2014-01-02 10:20:00
attempt 3: 2014-01-02 10:30:00
attempt 4: 2014-01-02 10:45:00
attempt 5: 2014-01-02 11:05:00
attempt 6: 2014-01-02 11:30:00
attempt 7: 2014-01-02 12:00:00
attempt 8: 2014-01-02 12:35:00
attempt 9: 2014-01-02 13:15:00
attempt 10: 2014-01-02 14:00:00

Parameters

When forwarding received SMS messages to the URL you have specified with a HTTP GET, SMS Central will provide the following parameters:

HTTP GET Parameters Definitions

USER_NAME

• Type: string
• Description: This is the Username you set for the URL in Rules & Triggers i.e. the username required for Basic Authentication.

PASSWORD

• Type: string
• Description: This is the Password you set for the URL in Rules & Triggers i.e the password required for Basic Authentication.

ORIGINATOR

• Type: string
• Description: This is the mobile number of the handset that has sent in the SMS message.

*In international format, an example of an Australian originator value is:

RECIPIENT

• Type: string
• Description:  This is the number that the message was being sent to. This would either by your dedicated number, or a shared virtual mobile number provided by SMS Central.

*An example of an Australian recipient value is:

CAMPAIGN

• Type: string
• Description:  When the message you are receiving is found to be a reply to an SMS message you have sent, if you provided a ‘CAMPAIGN’ value in that SMS message you sent, this CAMPAIGN parameter will provide that value, allowing you to match received messages to the campaign.

REFERENCE

• Type: string
• Description:  When the message you are receiving is found to be a reply to an SMS message you have sent, if you provided a unique REFERENCE value in that SMS message you sent, this REFERENCE parameter will provide that value, allowing you to match the received message as a reply to that specific SMS message you sent.

MESSAGE_TEXT

• Type: string
• Description:  If the received message is a single part message (up to 160 characters), this parameter will contain the text of the SMS message received.

UDH

• Type: OCTET Encoded User Data Header
• Description:  If there is no value in the ‘MESSAGE_TEXT’ parameter and the received message is longer than 160 characters long, the UDH parameter will be provided containing an Octet-encoded user data header. In this case, the message will be split into 153 character parts, provided in the ‘BINARY’ parameter. This UDH value provides information about the message, including which part of the message this is.
  In the case where the message contains non-GSM characters, the standard message length can contain up to 70 characters. In this case, each multi-part message will contain 67 characters.
  An example value is: 0500038A0302
  - The first 3 octets will always be "050003".
  - The next octet ("8A" in the example) identifies the group. However, since we will pass your reference back to you in the delivery receipt, this octet will probably be useful for double checking only.
  - The next octet ("03" in the example) specifies the total number of parts in the group.
  - The last octet ("02" in the example) specifies the particular part of this message/delivery receipt. In this case, the delivery receipt would be for the second part of a 3-part message.

  In order to check that the full message is delivered, you will need to look at the last 2 octets to check how many parts a message has, and check that you received a positive delivery for each part.

BINARY

• Type: OCTET Encoded Binary Data
• Description:  If there is no value in the ‘MESSAGE_TEXT’ parameter and the received message is longer than 160 characters long, or the message contains characters not within the standard GSM character set, the BINARY parameter will be provided containing an Octet-encoded binary data. Where the message contains only standard GSM characters, In this case, the message will be split into 153 character parts, with each part of the message providing a User Data Header (UDH) PARAMETER value and the content of the message part provided in the BINARY parameter.

  In the case where the message contains non-GSM characters, it will be split into 70 character parts for a single message or 67 character parts for a multi-part message, with each part of the message providing a User Data Header (UDH) which provides information for determining which part of the multi-part message you have just received.

DCS

• Type: integer
• Description:  The Data Coding Scheme (DCS) value represents the character set with which the ‘BINARY’ value should be decoded. A value of 8 should be treated as UCS-2 as it will contain characters outside of the ASCII/GSM character set. Any other value should be treated as ASCII/Latin-1.

VALUE

• Type: string
• Description: If the received message is a MO-billed Premium SMS message (the user sending the message will pay a fee, charged to their mobile phone bill, for sending the message), the VALUE parameter will contain the amount billed to the handset, in cents.

*For example if the charge is 55cents, the value for the VALUE parameter would be: