Mobile Sasa API version: 1.0.x

Introduction


Mobile Sasa enables you to seamlessly integrate SMS alerts, short codes, USSD codes and airtime with other systems. Our simplified APIs enable you to simply plug and play. Security has been given the highest priority to ensure that your communication takes place in a secure environment.

Prerequisites


To get started, log into your Mobile Sasa account. Select “Settings” then “API Integration” on the menu. Click on "Create App" button to create a new app then enter app name and callback URL. The app name will enable you remember which integration it is for example “XYZ Sacco SMS Integration”. The callback URL is where you receive SMS status informing you of the delivery status as per the documentation.



The API key is generated when you sign up and is visible when you slide the Show Legacy API Key button. After creating an app, you will get ClientID and Secret that are used in generating access token.


Generating Access Token


This is a security token used to authenticate a request. Mobile Sasa uses bearer authentication to authenticate requests. The token is sent as the Authorization header when making requests.

End point: https://account.mobilesasa.com/oauth/token

Request Parameter Details

Field Name Description Data Type Mandatory/Optional Example
grant_type Refers to the way an application gets an access token String M client_credentials
client_secret Client secret generated after creating an app String M 67451322-ed6d-22e8-ac8f-977d3660293c
client_id Client id generated after creating an app String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf

# Headers Params Response
1 Content-Type: application/json
{
  "grant_type":"client_credentials",
  "client_secret":"your_app_client_secret",
  "client_id":"your_app_client_id"
}
		
{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "generated_access_token"
}
		
2 Accept: application/json


Curl example:


curl -X POST \
https://account.mobilesasa.com/oauth/token \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
          "grant_type":"client_credentials",
          "client_secret":"your_client_id",
          "client_id":"your_client_secret"
 }'                                




Response Parameter Details

Field Name Description Data Type Example
token_type The type of token generated String Bearer
expires_in Time taken for the token to expire String 3599
access_token The generated token String eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni IsImp0aSI6ImI2ZWJjNzkzYeyJ0eXAiOiJK V1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImI2 ZWJjNzkzYWRiNDQzNjg0NzVhNzBjNmMyZ WJlOGNlZjFjN2Y1NTAwMjY0OGYzMjgyYTU2 Nzg3M2Q3NzkwMzNhMzEyZmE2MDdkZjE2YTN lIn0.eyJhdWQiOiIyMDE0ZTkzMC04OGY5LT ExZTktOWNjMy04NzZkY2NkYWU0MTkiLCJqd GkiOiJiNmViYzc5M2FkYjQ0MzY4NDc1YTcw YzZjMmViZThjZWYxYzdmNTUwMDI2NDhmMzI 4MmE1Njc4NzNkNzc5MDMzYTMxMmZhNjA3ZG YxNmEzZSIsImlhdCI6MTU1OTg5NTMyMSwibm JmIjoxNTU5ODk1MzIxLCJleHAiOjE1NTk4OT g5MjEsInN1YiI6IiIsInNjb3BlcyI6W119. H7O6QaknYx39bNxS5D3vmAXLHorcXLji_J5 kVqXLAemTR5lb3FsRt61B5NFXUx-9EZCtjTO Ibozzyj1cdrqb1d6twTbIEQ0WdOXplfoa1cl yJRoZj1Vpo0RyRVbzH3oG-UTOzLzVd643cYl NJKsTPMlrLcHuWqzU17kXB2XUUtdfUWkiGVT YaZPV_1OcNX_IE0NSRLqvjw5wdjs157Wb-Ed 5cSs7TAXqMuf5CoZ75vlS4jgwgsKuwDMRe8B 2hRNqPtqSkeMzc9HQbncxLSHf8gaNeUS614T qMVBIiI-W8T0osWlmv2v6w5YhHIy7VNmNiVe M2_tw1E6dfbnX067rca8k_5A


Send Single SMS (Without Access Token)


This is used to send a single SMS to a single contact. The user sends a normal POST form request to the end point which delivers the message. This endpoint is recommend for systems that allows your just plug in a POST URL that sends a message directly. Note that this request is x-www-form-urlencoded like the way a web form submits data.

Endpoint: https://account.mobilesasa.com/api/express-post

Request Parameter Details

Field Name Description Data Type Mandatory/Optional Example
phone Recipient phone number. When sending to international numbers prepend + and country code String M 254726712505
message Text message to be sent to the recipient String M This is a test message
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf
username Your account username String M johndoe

# Headers Params Response
1 Content-Type: application/json
"senderID": "MOBILESASA"
"phone": "phone_number"
"message": "your message"
"api_key": "api_key"
"username": "your_username"
         
{
    "code": 1,
    "messageID": [
        "5d822610-5cfa-11e9-aa96-d9074c80734c"
    ],
    "status": "Queued",
    "smsCost": 0.8
}
        	
2 Accept: application/json

Curl example:


    curl -X POST \
    https://account.mobilesasa.com/api/express-post \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -F 'api_key=your_api_key' \
    -F senderID=MOBILESASA \
    -F phone=0707070707 \
    -F message=Helloooooooooooo \
    -F username=your_username                            


Response Parameter Details

Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
messageID A unique identifier for the message String 5d822610-5cfa-11e9-aa96-d9074c80734c
status Description of the status String Queued
smsCost Total SMS cost Double 0.8

Send Single SMS (With Access Token)


This is used to send a single SMS to a single contact with a Bearer token.

Endpoint: https://account.mobilesasa.com/api/post-sms

Request Parameter Details

Field Name Description Data Type Mandatory/Optional Example
phone Recipient phone number. When sending to international numbers prepend + and country code String M 254726712505
message Text message to be sent to the recipient String M This is a test message
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf

# Headers Params Response
1 Content-Type: application/json
"senderID": "MOBILESASA"
"phone": "phone_number"
"message": "your message"
"api_key": "api_key"
         
{
    "code": 1,
    "messageID": [
        "5d822610-5cfa-11e9-aa96-d9074c80734c"
    ],
    "status": "Queued",
    "smsCost": 0.8
}
        	
2 Accept: application/json
3 Authorization: Bearer access_token

Curl example:


curl -X POST \
  http://code-slayer:8000/api/post-sms \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "senderID": "MOBILESASA",
  "phone": "0707070707",
  "message": "Hello world!",
  "api_key": "your_api_key"
}'                        


Response Parameter Details

Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
messageID A unique identifier for the message String 5d822610-5cfa-11e9-aa96-d9074c80734c
status Description of the status String Queued
smsCost Total SMS cost Double 0.8

Send Multiple SMS


This is used to send different messages to different phones in one request. An access token is passed in the Authorization header.

Endpoint: https://account.mobilesasa.com/api/send-sms/diffMsg-diffPhones

Request Parameter Details

Field Name Description Data Type Mandatory/Optional Example
senderID The sender ID registered and mapped to your account String M MOBILESASA
MessageBody An array of phone and message pair String M [ {"070707070": "Message one"}, {"070070707": "Message two."} ]
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf

# Headers Params Response
1 Content-Type: application/json
{
    "senderID": "MOBILESASA",
    "MessageBody": [
        {"070707070": "Message one"},
        {"070070707": "Message two."}
      ],
      "api_key": "your_api_key"
}
     
{
    "code": 1,
    "messageID": [
        "6d250c40-5d00-11e9-9639-cd2d13e5b436",
        "6d280e60-5d00-11e9-b008-27c6cf27bfca"
    ],
    "status": "Queued",
    "smsCost": 1.6
}
2 Accept: application/json
3 Authorization: Bearer access_token


Curl example:

   
  curl -X POST \
    'https://account.mobilesasa.com/api/send-sms/diffMsg-diffPhones' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer access_token' \
    -H 'Content-Type: application/json' \
    -d '{
    "senderID": "MOBILESASA",
    "MessageBody": [
      {"070707208": "Message one"},
      {"070070707": "Message two!"}
    ],
    "api_key": "your_api_key"
  }'                                           
   
   

Response Parameter Details

Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
messageID An array of unique identifiers for messages sent. The Ids are in the order of the messages sent String [ "6d250c40-5d00-11e9-9639-cd2d13e5b436", "6d280e60-5d00-11e9-b008-27c6cf27bfca" ]
status Description of the status String Queued
smsCosts Total SMS cost Double 0.8

Schedule SMS


Coming Soon...


Get Delivery Status


When a message is sent, the system forwards delivery status to your application through the callback URL you specified when creating an application. The parameters are as shown below:


Field Name Description Data Type Example
id Unique message identifier String 6d250c40-5d00-11e9-9639-cd2d13e5b436
msisdn Phone number to which the message was sent String 254722002222
date_time The date and time message status was last updated DateTime 2019-04-09T10:36:54.000Z
code Delivery status code Int 0 = SENT
1 = ENROUTED
2 = DELIVERED
3 = EXPIRED
4 = DELETED
5 = UNDELIVERABLE
6 = ACCEPTED
7 = UNKNOWN
8 = REJECTED
100 = QUEUED
101 = BLACKLISTED
state Delivery state String SENT
ENROUTED
DELIVERED
EXPIRED
DELETED
UNDELIVERABLE
ACCEPTED
UNKNOWN
REJECTED
QUEUED
BLACKLISTED


Query Delivery Status


Coming Soon...


Get Balance


This is used to get SMS account balance in KES.

Endpoint: https://account.mobilesasa.com/api/balance

Request Parameter Details
Field Name Description Data Type Mandatory/ Optional Example
username Your account username String M johndoe
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf
# Headers Params Response
1 Content-Type: application/json
{
    "username": "your_username",
    "api_key": "api_key"
}
            
{
    "code": 1,
    "balance": 0.4,
    "message": "success"
}
            
2 Accept: application/json

Curl example:

   
curl -X POST \
https://account.mobilesasa.com/api/balance \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
            "username":"your_username",
            "api_key":"your_api_key"
   }'                                               
   
   

Response Parameter Details
Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
balance Your current account balance Double 1035.00
message Request status String success


My Groups


This is used to get all groups registered on your account. An access token is passed in the Authorization header to get groups.

Endpoint: https://account.mobilesasa.com/api/groups

Request Parameter Details

Field Name Description Data Type Mandatory/ Optional Example
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf
# Headers Params Response
1 Content-Type: application/json
{
    "api_key": "api_key"
}
			            
{
    "code": 1,
    "message": "success",
    "groups": [
        {
            "GroupID": "60cb9630-5127-11e9-95c3-7feac8e8c84d",
            "GroupName": "name",
            "GroupDescription": "description"
        },
        {
            "GroupID": "f23c7fe0-4fa3-11e9-86fb-3b9a6ce3c9fb",
            "GroupName": "new group",
            "GroupDescription": "new"
        }
    ]
}
			            
2 Accept: application/json
3 Authorization: Bearer access_token

Curl example:

   
curl -X POST \
  https://account.mobilesasa.com/api/groups \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer access_token' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "your_api_key"
}'

   
Response Parameter Details
Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
message Request status String success
groups An array of groups Array [ { "GroupID": "60cb9630-5127-11e9-95c3-7feac8e8c84d", "GroupName": "name", "GroupDescription": "description" }, { "GroupID": "f23c7fe0-4fa3-11e9-86fb-3b9a6ce3c9fb", "GroupName": "new group", "GroupDescription": "new" } ]
GroupID A unique group identifier String 60cb9630-5127-11e9-95c3-7feac8e8c84d
GroupName The name of the group String New Group
GroupDescription The description of the group String This is a test group


Add Contact to Group


This is used to add a contact to a group. The GroupID in the URL is the GroupID of the group you want to add contact to. This is found in the SMS groups in the web platform.

Endpoint: https://account.mobilesasa.com/api/group/Your-GroupID-here/add-contact

Request Parameter Details

Field Name Description Data Type Mandatory/ Optional Example
api_key Your account API Key String M dPchfhydDTYP2kdhdNTCtNythgJmhOM8l4CGvz2iFhSf
# Headers Params Response
1 Content-Type: application/json
{
	"api_key": "api_key",
	"ContactPhone":"070707070",
	"ContactName": "Kevv Doe"
}
{
	"code": 1,
	"message": "Phone added succefully"
}
2 Accept: application/json
3 Authorization: Bearer access_token

Curl example:

   
curl -X POST \
  https://account.mobilesasa.com/api/group/72de5dd0-2479-11e9-8530-ab317d1f95b7/add-contact \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key": "your_api_key",
  "ContactPhone": "0707070707",
  "ContactName": "@kevv_db"
}'

   

Response Parameter Details
Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
message Request status String Phone added succefully


Delete Contact from Group


Use this option to delete a contact from a group. You send a DELETE request by passing an access token in the authorization header.

End point: http://account.mobilesasa.com/api/group/fd799550-b8a7-11ea-ab06-c79f1ad1a0e5/remove-contact

NOTE: fd799550-b8a7-11ea-ab06-c79f1ad1a0e5 is the group ID

Request Parameter Details
Field Name Description Data Type Mandatory/ Optional Example
phone Phone number to be deleted String M 254722002222
# Headers Params Response
1 Content-Type: application/json
{
	"phone":"25470707070"
}
{
	"code": 1,
	"message": "Contact Queued for deletion"
}
2 Accept: application/json
3 Authorization: Bearer access_token

Curl example:

   
curl -X POST \
  http://account.mobilesasa.com/api/group/fd799550-b8a7-11ea-ab06-c79f1ad1a0e5/remove-contact \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d '{
  "phone": "254707070707"
}'

   
Response Parameter Details
Field Name Description Data Type Example
code Request status code. 1 indicates success and 0 indicates failed Int 1
message Request status description String Contact Queued for deletion


Short Code Receive SMS


Content comming soon



Short Code send SMS


Content comming soon



USSD Integration


USSD stands for Unstructured Supplementary Service Data. When a user dials a USSD code or selects an option and sends request, the USSD gateway forwards it to the user’s USSD application which processes the request and sends response back. The response is sent back to the user’s phone. The USSD gateway appends a * and user response every time the user enters an input which is sent to the user’s application for processing. For example


User Dials/Inputs *123# Welcome to XYZ Sacco 1. Balance Enquiry 2. Mini-statement 3. Profile Details 4. Contact Us
1 1 Select Account 1. Savings 2. Shares 3. Loan
3 1*3 Enter your PIN
1234 1*3*1234 Your loan balance is KES 100,000. 00. Back to main menu
00 1*3*1234*00 Welcome to XYZ Sacco 1. Balance Enquiry 2. Mini-statement 3. Profile Details 4. Contact Us


The user application processes request based on the string sent to their application. The user registers a callback URL to which their application listens for requests. To indicate that a session is continuing, the response is prepended with CON key word and to end the session, the response is prepended with END key word.