Messaging API
Functionality: Send SMS Messages.
This gateway can be accessed via the HTTP or HTTPs Protocol by submitting values to the API server and can be used to send simple text messages to single or multiple mobile numbers with each request.
Protocol
The 5cSMS API receives API Requests through the HTTP Protocol and will accept a GET or POST request with the required parameters. Most programming languages have modules, which facilitate creating and executing such a request. Once a request is received the server will respond to advise the status of the request and various details that can be used interpreted by your software and/or stored for future use, such as a Message ID or Account Balance.
URI
The Messaging API can be accessed by calling either of the following URIs; http://www.5centsms.com.au/api/send.php or
https://www.5centsms.com.au/api/send.php Digital Signature (Optional) beta
Rather than provide your password as part of your request you can use a digital signature of “Hash” to authenticate. This signature is a hash using parts of your message and a unique private key. To generate your hash you should concatenate you message text (before it is encoded) with the destination number string and your private key then create an MD5 hash from this string. The resulting hash is your digital signature. To receive your private key you should contact
service@5centsms.com.au
Message To Private Key Hash Digital Signature
Hello 0404123123 abc123 MD5(“Hello0404123123abc123”) = dafl3jaf34asb… Hello 61404123123,61404123456 abc123 MD5(“Hello61404123123,61404123456abc123”)
= Ifvewyf8734g…
Version: 4.0 Last Updated: 16/07/2012
Request Parameters
The following parameters must be assigned values and passed to the API on a per request basis;
Parameter Details Example
username Your login/username (usually
your email address) user@5centsms.com.au
password Your password password
digitalSignature (optional) See Digital Signature section
above
to The destination mobile
number. To send the same message to multiple mobile numbers each separate mobile number must be separated by a comma "," and a maximum of 399 separate numbers can be specified in a single request.
0412345678,0412000000
sender The name or number of the
SMS sender. Can be up to 11 alphanumeric characters or up to 15 numerical characters.
0411222333
message
The message parameter refers to the actual message that is to be sent to the destination mobile number. The message can contain a maximum of 612* characters, including spaces. Due to restrictions in the HTTP protocol format, special characters must be encoded. We recommend using an in-‐ built function to encode your message text.
*Messages > 160 characters are charged as multipart messages.
this%20is%20a%20test.
reply (Optional) This parameter can be used to set any replies to be forwarded to your registered email and our Reply Notification API. This option will invalidate the sender parameter. NOTE Setting the reply parameter to api will also enable email notifications.
api
Response Parameters
Once your message has been submitted to the API you will receive feedback in the HTTP response as to the success of the transmission and a number of values. These values can be used and/or stored by your application. These values will always be separated by a | character. For Example: A|B|C or A||C or A|B
For the Messaging API the status of each destination number in your request will be separated by a new line character and a HTML break tag.
Parameter Details Examples
Status 0: Request Rejected
1: Sent 2: Failed
1 2
Destination The destination number for this
message
0412345678 04aa123456
Message ID Unique message identifier 123456
Notes Notes providing further
information on a messages status
OK
Invalid Destination Number AccountBalance The current balance of your
account. (The number of messages remaining) Postpaid accounts will return a negative number. 1000 0 -‐555
Version: 4.0 Last Updated: 16/07/2012
Example Request and Responses
Sending a Single SMS
GET /api/send.php?username=test@5centsms.com.au&password=testpassword&sender=0400000000&to=0400000000&message=this%20is% 20a%20test HTTP/1.1 Host: www.5centsms.com.au Connection: keep-‐alive Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
User-‐Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-‐US) AppleWebKit/534.10 (KHTML, like Gecko) Chrome/8.0.552.237 Safari/534.10 Accept-‐Encoding: gzip,deflate,sdch Accept-‐Language: en-‐US,en;q=0.8 Accept-‐Charset: ISO-‐8859-‐1,utf-‐8;q=0.7,*;q=0.3 HTTP/1.1 200 OK
Date: Sun, 16 Jan 2011 03:09:10 GMT
Server: Apache/2.2.15 (Unix) mod_ssl/2.2.15 OpenSSL/0.9.8e-‐fips-‐rhel5 mod_auth_passthrough/2.1 mod_bwlimited/1.4 FrontPage/5.0.2.2635
X-‐Powered-‐By: PHP/5.2.13 Keep-‐Alive: timeout=5, max=100 Connection: Keep-‐Alive Transfer-‐Encoding: chunked Content-‐Type: text/html 1|0400000000|3107944|OK<br>
Sending a Bulk SMS
GET /api/send.php?username=test@5centsms.com.au&password=testpassword&sender=0400000000&to=0400000000,0404000001&messag e= this%20is%20a%20test HTTP/1.1 Host: www.5centsms.com.au Connection: keep-‐alive Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
User-‐Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-‐US) AppleWebKit/534.10 (KHTML, like Gecko) Chrome/8.0.552.237 Safari/534.10 Accept-‐Encoding: gzip,deflate,sdch Accept-‐Language: en-‐US,en;q=0.8 Accept-‐Charset: ISO-‐8859-‐1,utf-‐8;q=0.7,*;q=0.3 HTTP/1.1 200 OK
Date: Sun, 16 Jan 2011 03:11:09 GMT
Server: Apache/2.2.15 (Unix) mod_ssl/2.2.15 OpenSSL/0.9.8e-‐fips-‐rhel5 mod_auth_passthrough/2.1 mod_bwlimited/1.4 FrontPage/5.0.2.2635
X-‐Powered-‐By: PHP/5.2.13 Keep-‐Alive: timeout=5, max=100 Connection: Keep-‐Alive Transfer-‐Encoding: chunked Content-‐Type: text/html 1|0400000000|3107945|OK<br> 1|0404000001|3107946|OK<br>
Sending an SMS to Receive a Response by Email/API
GET /api/send.php?username=test@5centsms.com.au&password=testpassword&sender=0400000000&to=0400000000&message=this%20is% 20a%20test&reply=email HTTP/1.1 Host: www.5centsms.com.au Connection: keep-‐alive Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5
User-‐Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-‐US) AppleWebKit/534.10 (KHTML, like Gecko) Chrome/8.0.552.237 Safari/534.10 Accept-‐Encoding: gzip,deflate,sdch Accept-‐Language: en-‐US,en;q=0.8 Accept-‐Charset: ISO-‐8859-‐1,utf-‐8;q=0.7,*;q=0.3 HTTP/1.1 200 OK
Date: Sun, 16 Jan 2011 03:09:10 GMT
Server: Apache/2.2.15 (Unix) mod_ssl/2.2.15 OpenSSL/0.9.8e-‐fips-‐rhel5 mod_auth_passthrough/2.1 mod_bwlimited/1.4 FrontPage/5.0.2.2635
X-‐Powered-‐By: PHP/5.2.13 Keep-‐Alive: timeout=5, max=100 Connection: Keep-‐Alive Transfer-‐Encoding: chunked Content-‐Type: text/html 1|0400000000|3107944|OK<br>