English

Application Programming Interface (SMS API)

Endpoints

The first thing you'll need to know is to where to send your API request to. My-Cool-SMS accepts GET, POST and JSON requests via port 80 or SSL on port 443. You can connect to the following URLs respectively.

HTTP

The API endpoint for HTTP requests is:
http://www.my-cool-sms.com/api-socket.php

HTTPS

If you require a secure connection you can use the API via SSL on port 443.
The API endpoint for HTTPS requests is:
https://www.my-cool-sms.com/api-socket.php

API Components

My-Cool-SMS has two two kinds of API components. Functions and Callbacks.

Functions

Functions are used to i.e. request the sending of an SMS text message, looking up your balance or fetching delivery reports. A function can be invoked by using the HTTP request structure as outlined below.

Callbacks

Callbacks are push requests sent from My-Cool-SMS to your server. A callback is invoked in real-time when events like receiving an SMS or a new delivery report happen and is posted back to an URL your server for processing.

Request Structure

You can send requests via HTTP POST, GET or JSON. Although My-Cool-SMS won't stop you from using POST or GET it is highly recommended to use JSON requests. JSON is a light-weight data-interchange format that is easy for humans to read and write and easy to parse and generate for the programming language of your choice.
Above all JSON is very robust when sending Unicode SMS text messages and doesn't require you to implement complex UCS2 encoding and decoding procedures. If you ever had to work with cross-server Unicode, UCS2 or GSM7 encodings and decoding you might know already that being able to avoid it is a blessing. You can find out more about JSON here.

Login Credentials and Function Selectors

A request to the My-Cool-SMS API must always contain your username, password and a function selector that tells the API what you want to do.

JSON

Let's have a look at a JSON example that you would use when looking up your balance:
{
    "username":"xxx",
    "password":"yyy",
    "function":"getBalance"
}

POST/GET

With POST or GET the same request would look as follows:
username=xxx&password=yyyy&function=getBalance

Mandatory and Optional Parameters

While the username, password and function parameters are always required, every function can have specific mandatory and optional parameters that might have to be provided too.
When fetching a delivery report for example, you'll also want to specify which SMS you want the delivery report for. You do that by simply adding an additional parameter, in this case "id".
{
    "username":"xxx",
    "password":"yyy",
    "function":"getDeliveryReport",
    "id":"ce184cc0a6d1714d1ac763f4fe89f521"
}

Response Structure

An API request always returns a JSON object. Every response contains a success parameter that indicates whether the request could be successfully processed or not. Depending on whether this parameter is true or false you'll want to treat the response differently.

Success Response

A successful request to the getDeliveryReport function would return a JSON object like the following:
{
    "success":true,
    "smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
    "status":"SMS_STATUS_DELIVERED"
}
Every function has different response parameters. You can view the detailed specification here.

Error Response

Let's say you have a typo in the password parameter. In that case the API will return a JSON object with the following structure:
{
    "success":false,
    "errorcode":"101",
    "description":"Login Failed. Wrong Username or Password."
}
You can always expect a three digit errorcode and a description that helps you to pinpoint the problem to be returned when the success parameter in the response is false.

Handling Responses

Read Response

The API response is always sent in JSON format. All you need to do with it is to convert the response data into an object. That's real simple because virtually every programming language offers native methods to do exactly that.
To find more information about JSON for the programming language of your choice go to this page and scroll down a bit.
In PHP you'd do something amongst the lines of the following to process the API response:
// Let's assume you sent a getDeliveryReport request and
// the HTTP response is stored in $response...

// Now simply convert the response into a PHP object
$oResponse = json_decode($response);

//$oResponse is now an object

if($oResponse->success) {
    //Great. It worked!
    echo($oResponse->smsid);
    echo($oResponse->status);
} else {
    //Oops. something went wrong.
    echo($oResponse->errorcode);
    echo($oResponse->description);
}

Handling Callbacks

Read Input

Callbacks aren't much different from function responses and you can convert them into an object exactly the same way as above. One thing you'll need to know though is how to capture the HTTP Raw Request Input. The callback is neither sent via GET nor POST but as HTTP Raw Data which you can read as oulined next.
In PHP you'd do something amongst the lines of the following to process the callback request:
//capture the raw data input stream
$oCallback = json_decode(file_get_contents("php://input"));

//$oCallback is now an object.
print_r($oCallback);
In Java it's pretty much the same:
InputStream body = request.getInputStream();
Please note that whatever programming language you use you can only read the input once. Store the body somewhere else for processing.

PHP Examples

Function: sendSms

Let's have a look at what actual code to send an SMS might look like. You probably want to implement the API using as little lines of code as possible. So, how would the following work for you?
<?php

$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

?>
Pretty neat? If that's all you need, simply download the PHP SMS Starter Kit, have a look at the comments in the code, run send-sms.php and you're good to.

PHP SMS Starter Kit

Download PHP SMS Starter Kit
The starter kit contains good-to-go code for invoking API functions and handling callbacks.

For Techies

If you're a little bit more tech savvy you might want to have a look at the actual class that handles the request:
<?php

class MyCoolSMS {

    function __construct() {
    
        $this->username = 'xxx'; //your username here...
        $this->password = 'yyy'; //your password here...
        $this->endpoint = 'http://www.my-cool-sms.com/api-socket.php';
    }

    public function sendSms($number, $message, $senderid='MyNumber') {
    	
        return($this->request(json_encode(array(
            'username' => $this->username,
            'password' => $this->password,
            'function' => 'sendSms',
            'number' => $number,
            'senderid' => $senderid,
            'message' => $message
        ))));
        
    }
    
    public function getDeliveryReport() {}
    
    public function getBalance() {}
    
    //add more functions as you please...
    
    private function request($oRequest) {
    
        $oCurl = curl_init($this->endpoint);
        curl_setopt($oCurl, CURLOPT_POST, 1);
        curl_setopt($oCurl, CURLOPT_POSTFIELDS, $oRequest);
        curl_setopt($oCurl, CURLOPT_RETURNTRANSFER, 1);
        
        if(curl_errno($oCurl) == 0) {
            $oResponse = json_decode(curl_exec($oCurl));
            if(!is_object($oResponse)) {
                $oResponse = $this->getError('001', 'Bad Response');
            }
        } else {
            $oResponse = $this->getError(curl_error($oCurl));
        }		
    
        curl_close($oCurl);
        
        return $oResponse;
    
    }
	
    private function getError($error = '000', $description = NULL) {

        return json_encode(array(
            'success' => false,
            'error' => $error,
            'description' => $description,
        ));
        
    }

}

?>
Save above code into a file called MyCoolSMS.class.php and start using it like this:
<?php

require_once('MyCoolSMS.class.php');

$oMyCoolSMS = new MyCoolSMS();
$oResponse = $oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');

if($oResponse->success) {
    //Great, it worked!
    print_r($oResponse);
} else {
    //Oops, Something went wrong...
    print_r($oResponse);
}

?>

You're good to go!

Let's have a look at the API function and callback documentation now.
Did we miss something? Do you have questions? Have some advice or something we should add here? If so, let us know!
© My-Cool-Webservices Ltd. 2008-2014
Deutsch
Español
Français
Nederlands
Polski
Português
Руccкий
繁体中文