Eindpunten
Wat je ten eerste moet weten, is waarnaartoe je jouw API verzoek moet sturen. My-Cool-SMS accepteert GET, POST en JSON verzoeken via port 80 of SSL op port 443. Je kunt respectievelijk verbinding maken met de volgende URL's.HTTP
Het API eindpunt voor HTTP verzoeken is:
http://www.my-cool-sms.com/api-socket.php
HTTPS
Indien je een beveiligde verbinding benodigt, kun je de API via SSL op port 443 gebruiken. Het API eindpunt voor HTTPS verzoeken is:
https://www.my-cool-sms.com/api-socket.php
API Componenten
My-Cool-SMS heeft twee soorten van API componenten. Functies en Callbacks.Functies
Functies worden gerbuikt om bijv. een SMS tekstbericht verzending te verzoeken, jouw saldo te bekijken of om afleveringsrapporten op te halen. Een functie kan opgeroepen worden door een HTTP verzoek structuur zoals beneden geschetst te gerbuiken.Callbacks
Callbacks zijn doorstuur verzoeken verstuurd door My-Cool-SMS naar jouw server. Een callback wordt in real-time opgeroepen zodra iets gebeurt zoals een SMS of een nieuwe afleveringsrapport ontvangen. De callback wordt voor verwerking geretourneerd naar een URL op jouw server.Verzoek Structuur
Je kunt verzoeken via HTTP POST, GET of JSON sturen. Hoewel My-Cool-SMS jou tegen het gebruiken van POST of GET niet tegenhoudt, is het ten zeerste aanbevolen JSON verzoeken te gebruiken. JSON is een lichte gegevens-uitwisseling formaat welke makelijk voor mensen te lezen en te schrijven en makkelijk te ontleden en te genereren voor de programmeertaal van uw keuze is. JSON is bovendien zeer robuust bij het versturen van Unicode SMS tekstberichten en vereist geen invoeren van ingewikkelde UCS2 codeer- en decodeerprocedures. Als je ooit met en cross-server Unicode moest werken, is het een zegen al bekende UCS2 or GSM7 codering en decodering te voorkomen. Meer informatie over JSON hier.Inloggegevens en Functie Selectors
Een verzoek aan de My-Cool-SMS API moet altijd jouw gebruikersnaam, wachtwoord en een functie selector bevatten, die aan de API doorgeeft wat je wil doen.JSON
Laten we eens kijken naar een JSON voorbeeld dat je zou gebruiken bij het bekijken van jouw saldo:
{
"username":"xxx",
"password":"yyy",
"function":"getBalance"
}
POST/GET
Hetzelfde verzoek met POST of GET zou als volgend eruitzien:
username=xxx&password=yyyy&function=getBalance
Verplichte en Optionele Parameters
De gebruikersnaam, het wachtwoord en de functie parameters zijn altijd verplicht, elke functie kan echter specifieke verplichte en optionele parameters hebben, van welke de functie moet voorzien zijn. Bij het ophalen van een afleveringsrapport bijvoorbeeld, ga je ook willen specificeren voor welke SMS je een afleveringsrapport wil. Je doet dat indien je gewoon een additionele parameter toevoegt, in dit geval "id".
{
"username":"xxx",
"password":"yyy",
"function":"getDeliveryReport",
"id":"ce184cc0a6d1714d1ac763f4fe89f521"
}
Respons Structuur
Een API verzoek retourneerd altijd een JSON object. Elke respons bevat een succes parameter welke aangeeft of het verzoek met succes kon worden verwerkt of niet. Afhankelijk daarvan of deze parameter true of false is, ga je de respons op verschillende manier willen behandelen.Gelukte Respons
Een met succes gestelde verzoek aan de getDeliveryReport functie, gaat een JSON object retourneren zoals het volgende:
{
"success":true,
"smsid":"ce184cc0a6d1714d1ac763f4fe89f521",
"status":"SMS_STATUS_DELIVERED"
}
Fout Respons
Aangenomen, je hebt een typo in de wachtwoord parameter gemaakt. In dit geval gaat de API een JSON object met de volgende structuur retourneren:
{
"success":false,
"errorcode":"101",
"description":"Login Failed. Wrong Username or Password."
}
Omgang Responsen
Read Respons
De API respons wordt altijd in JSON formaat verstuurd. Alles wat je moet doen is de responsgegevens in een object te converteren. Dat is echt eenvoudig, omdat vrijwel elke programmeertaal natieve methoden om precies dat te doen aanbiedt. Om meer informatie over JSON voor de programmeertaal van jouw keuze te vinden, ga naar deze pagina en scroll een beetje naar beneden. In PHP ga je iets van de volgende rijen doen om de API respons te verwerken:
// 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);
}
Omgang Callbacks
Read Input
Callbacks verschillen niet zo zeer van functie responsen en je kunt ze in een object converteren precies zoals boven. Wat je wel moet weten is hoe men de HTTP Raw Request Input inneemt. De callback wordt ook niet via GET of POST verzonden maar als HTTP Raw Data welke je kunt lezen zoals volgend geschetst. In PHP ga je iets van de volgende rijen doen om de callback verzoek te verwerken:
//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 Voorbeelden
Functie: sendSms
Laat ons even bekijken hoe een eigenlijke code om een SMS te sturen eruitziet. Je wil zeker de API zo implementeren, dat je zo weinig mogelijk lijnen van code gebruikt. Dus, wat denk je van het volgende?
<?php
$oMyCoolSMS = new MyCoolSMS();
$oMyCoolSMS->sendSms('+12309876543', 'Have a nice day!');
?>
PHP SMS Starter Kit
Download PHP SMS Starter Kit
De starter kit bevat good-to-go code om API functies op te roepen en callbacks te hanteren.
Voor Techies
Ben je een beetje meer tech-savvy, misschien wil je dan even een eigenlijke klas welke verzoeken hanteert bekijken:
<?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);
}
?>
