SMS Messenger (Pty) Ltd REST API

Our REST API helps developers integrate SMS Messenger (Pty) Ltd with their existing systems quickly and easily.

Here's the short version of what you need to do:

• Register — once you have created your SMS Messenger (Pty) Ltd account, create an API token on the Developer Settings page
• Be a good API citizen — read, understand, and abide by the terms of use
• Authenticate — all API requests need to be authenticated
• Build cool stuff :)

Requests to SMS Messenger (Pty) Ltd are authenticated by providing your account email address and API token as request header attributes named email and token respectively. Your API key is securely encrypted by the SSL channel. Basic Authentication is also supported, using your email address and API token as the username and password.

You may also provide the email and token as URL parameters, although this is only recommended for testing purposes as your API token will not be encrypted.

Please note that SMS uses GSM7 character encoding by default, which allows for 160 characters in a single SMS. Should you send messages in non-GSM7 character encoding, the available character count is reduced to 70.

You are able to get the credit cost of an SMS, the number of SMS parts that it would require to send a specific message, as well as the encoding which would be used through the frontend or via API. It is your responsibility to ensure you are sending using the desired character encoding.

Our Interactive API provides detailed documentation and allows live interaction with the following functions:

• Retrieving your account balance
• Sending and scheduling an SMS
• Managing your contacts
• Managing your groups
• Managing your messages
• Managing your templates

SMS Messenger (Pty) Ltd provides two possible methods for receiving replies by API, either by Webhooks or by Polling. Using Webhooks is the preferred method as it allows messages to be received efficiently and in real-time.

When using webhooks, all replies received are sent as a POST request to a specified URL. To set the message forward URL please log in to SMS Messenger (Pty) Ltd, click on your company name, click on "Developer settings" and paste the URL to which inbound replies are to be forwarded.

Note that while polling the server for new replies is possible, should this result in high server load, the requests may be rate limited resulting in a delay in receiving replies.

http://yourserver.com/receive-sms.php?
    from=+27725551234
    &repliedToMessageId=121212
    &messageId=124567
    &message=REPLY
    &date=201404282055
    &campaign=shoe campaign
    &dataField=custom
    &nonce=89430dc5-cac1-4795-9dd0-46c9b8233e52
    &nonce-date=20140428210027
    &checksum=180f27d80dd05886e81da0c2ccebf830bc85c7ae

Similar to receiving replies, all delivery reports received are sent as a POST request to a specified URL. To set the delivery report URL please log in to SMS Messenger (Pty) Ltd, click on your company name, click on "Developer settings" and paste the URL to which delivery reports are to be forwarded.

http://yourserver.com/delivery/report.php?
    nonce=6110900b-a3e3-4ae7-9c80-c446086f8882
    &status=DELIVERED
    &messageId=40124213
    &checksum=195e39edfffed7e5ac87e85f3a6dd70ed8684b22
    &nonce-date=20160120103235

A shared secret key is used to generate an HMAC-SHA1 checksum based on the unencoded parameter data sent from SMS Messenger (Pty) Ltd to your server. This checksum is sent as a parameter with the other data. If an attacker were to alter any of the parameters, the checksum will no longer match and you should reject the request.

An expiry date field named nonce-date, also included in the checksum, is sent as a parameter with each request. This expiry date may be used to ensure requests are not resent.

$privateKey = 'secret';
$params['to']='+27725551234';
$params['from']='+27726661234';
$params['campaign']='campaign'; // (if not null)
$params['dataField']='data'; // (if not null)
$params['date']='201405161005';
$params['messageId']='24567';
$params['message']='Test + Message';
$params['nonce']='e273f177-6275-974f-1a12-0d8b92c5b3cb';
$params['nonce-date']='2014051610050102'; // format: yyyyMMddHHmmss

ksort($params);
$message = "";
foreach ($params as $key => $val) { $message .= "$key=$val&"; }
$message = substr($message, 0, -1);
$checksum = hash_hmac('sha1', $message, $privateKey);

/*
  Expected message to be hashed (i.e. $message, split across lines for readability)
  campaign=campaign
    &dataField=data
    &date=201405161005
    &from=+27726661234
    &message=Test + Message
    &messageId=24567
    &nonce=e273f177-6275-974f-1a12-0d8b92c5b3cb
    &nonce-date=2014051610050102
    &to=+27725551234

  Expected checksum (i.e. $checksum):
  9d0e933a457eabf94a73d7e15dd8849e89834464
*/