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"
}
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."
}
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);
InputStream body = request.getInputStream();
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!');
?>
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,
));
}
}
?>
<?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);
}
?>
