Introduction Last updated: 02-03-2024
Mobile Sasa APIs offer you a seamless way to automate SMS, short code messages and USSD services. We have implemented plug and play APIs that anyone can connect to to automate communication. To do integrations, you need an API key. To get your API key, log into sms.mobilesasa.com then select "API Integration". Click on "Show/Hide My API TOKEN" link yo get the API key as shown below:
NOTE: Mobile Sasa supports sending SMS to both plain phone numbers (for example, 0722002222) and hashed Safaricom numbers (for example, acd12test4f661ff9b2f81a5b366199292cdf06f2f5913621744da7a24c2fdf011). Simply pass the plain or hashed phone in the phone field and be guaranteed that your message will be delivered.
Get Phone Number Details
This end point is used to validate a phone number and convert it to the standard 254******** format. It also indicates the local network that the phone number belongs to. NOTE: you need to have credit in your wallet to validate phone numbers at KES 0.10 per validation.
Base URL: https://api.mobilesasa.com/v1/msisdns/load-details
NOTE: Send a POST request
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json body
{
"phone": "0782229227"
}
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/msisdns/load-details' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"phone": "0782229227"
}'
Success Response
{
"status": true,
"responseCode": "0200",
"networkName": "airtel",
"formattedPhone": "254782229227"
}
Failed Response
{
"status": false,
"responseCode": "0422",
"message": "Invalid phone number"
}
Networks as as shown below:
| Response Parameter | Telco Company |
|---|---|
| safaricom | Safaricom PLC |
| airtel | Airtel Kenya Limited |
| telkom | Telkom Kenya Limited |
| equitel | Equitel (Finserve Africa Limited) |
a) Sending a single SMS
You can send a single SMS using POST Form data request, Json POST request and GET request
1. JSON POST Request
You can send a Json POST Request as shown below:
Base URL: https://api.mobilesasa.com/v1/send/message
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json Body
{
"senderID": "MOBILESASA",
"message": "Dear Mercy, Your water bill of KES 8,200 is due on 02 Sept 2027. STOP *456*9*5#",
"phone": "2547078614XX"
}
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/send/message' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"senderID": "MOBILESASA",
"message": "Dear customer, thanks for shopping with us! Bonus of 44 added to your a/c.",
"phone": "25470786XXX"
}'
Success Response
{
"status":true,
"responseCode":"0200",
"message":"Accepted",
"messageId":"9b8a028b-f9bb-49f6-bc89-a5214ff1ba93"
}
Failed Response
{
"status":false,
"responseCode":"0422",
"message":"The Sender ID is Invalid!"
}
2. POST Form Data Request
You can also send a message using a POST request with form data parameters. To do so, send the form data parameters as below:
Base URL: https://api.mobilesasa.com/v1/send/message
NOTE: The parameter names are case sensitive
| Parameter Name | Description | Example |
|---|---|---|
| senderID | Your registered sender ID | MOBILESASA |
| message | Message to be sent to the recipient | This is a sample message |
| phone | Recipient phone number | 254722002222 |
| api_token | Your API key. | Your-api-token_HERE |
Success Response
{
"status":true,
"responseCode":"0200",
"message":"Accepted",
"messageId":"9b8a028b-f9bb-49f6-bc89-a5214ff1ba93"
}
Failed Response
{
"status":false,
"responseCode":"0422",
"message":"The Sender ID is Invalid!"
}
3. GET Request
You can send an SMS using a GET request. To do so send a request as below:
https://api.mobilesasa.com/v1/send/messageget?senderID=MOBILESASA&message=Test_message&phone=0722002222&api_token=testOlBJzS6K2Obn8ynFIeuOYdDMuLrrpThApDMnI4i4Zxcapikey
Success Response
{
"status":true,
"responseCode":"0200",
"message":"Accepted",
"messageId":"9b8a01af-4233-47f5-83f8-7d12c9605e51"
}
Failed Response
{
"status":false,
"responseCode":"0401",
"message":"Unauthenticated"
}
b) Bulk SMS
You can broadcast a single SMS to multiple contacts in a single request. It is recommended that you send 50 messages per request. The parameters are as below:
Base URL: https://api.mobilesasa.com/v1/send/bulk
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json Body
{
"senderID": "MOBILESASA",
"message": "Dear member, this is a reminder that this is a test message for bulk",
"phones": "07257125xx,2547078614xx"
}
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/send/bulk' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"senderID": "MOBILESASA",
"message": "Hello, this is a reminder that our Annual AGm is today at 2PM. Keep time.",
"phones": "254707XXXXXX,25411XXXXX"
}'
Success Response
{
"status": true,
"responseCode": "0200",
"message": "Accepted",
"bulkId": "9b8a0969-b3ea-4ac9-a7c7-a79b53d6b019"
}
Failed Response
{
"status": false,
"responseCode": "0422",
"message": "The Sender ID is Invalid!"
}
c) Personalized Messages
This is used to send multiple messages in a single request. Each phone receives a different message. It is recommended that you send 50 messages per request. The parameters are as below:
Base URL: https://api.mobilesasa.com/v1/send/bulk-personalized
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json Body
{
"senderID": "MOBILESASA",
"messageBody": [
{
"phone": "2547078614xx",
"message": "Vin, your water bill of KES 6700 is due on 23rd."
},
{
"phone": "07267125xx",
"message": "Hey Faith, your water bill of KES 400 is due today."
}
]
}
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/send/bulk-personalized' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"senderID": "MOBILESASA",
"messageBody": [
{
"phone": "2547078614xx",
"message": "Caro, your water bill of KES 6700 is due on 23rd."
},
{
"phone": "2541118810xx",
"message": "Dear James, your water bill of KES 40100 is due on 31st."
}
]
}'
Success Response
{
"status":true,
"responseCode":"0200",
"message":"Accepted",
"bulkId":"9b8a0f37-419d-454d-931d-0f5d4ddc4xxx"
}
Failed Response
{
"status":false,
"responseCode":"0422",
"message":"The Sender ID is Invalid!"
}
d) SMS Delivery Status (Callback URL)
You can register a callback URL on your account to receive delivery status of messages sent out. To do so, go to "Company Management" then View/Update Details" to update your callback URL. The following Json payload will be sent to your end point.
{
"deliveryStatus":"DeliveredToTerminal",
"deliveryTime":"2024-03-12 11:52:47",
"reference":"9b8b7a66-abbc-44bd-9098-4331fb264400",
"msisdn":"25470xxxxxx",
"cost": "0.12"
}
e) SMS Delivery Status (Query)
You can query delivery status of a message using the message id generated when sending a message:
Base URL: https://api.mobilesasa.com/v1/dlr
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json Body
{
"messageId": "9b899e2d-fde0-4361-997b-b802364ff736"
}
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/dlr' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"messageId": "9b899e2d-fde0-4361-997b-b802364ff736"
}'
Success Response
{
"status":true,
"responseCode":"0200",
"messages":[
{
"phone":"254705xxxxxx",
"message":"Your MobileSasa login OTP is 446679 and will expire at 2024-03-11 13:46:06",
"parts":1,
"cost":"0.80",
"sentTime":"2024-03-11 13:41:07",
"deliveryStatus":{
"status":"DeliveredToTerminal",
"deliveryTime":"2024-03-11 13:41:11"
}
}
]
}
Failed Response
{
"status": false,
"responseCode": "0422",
"message": "No messages found"
}
List of Delivery Statuses
| Delivery Status | Description |
|---|---|
| DELIVRD/Delivered/DeliveredToTerminal | Message successfully delivered to recipient |
| ACCEPTED | Message accepted by network provider but delivery unknown |
| EXPIRED | Message took long to be delivered and expired. Occurs when number is unreachable |
| ENROUTED | The message is currently being delivered and awaiting delivery receipt confirmation from the carrier. |
| Sent | Message is successfully sent awaiting delivery status |
| UNDELIV | Failed to deliver |
| DELETED | The message has failed due to "Barred", "Absent Subscriber", or "Delivery Failure". |
| UNDELIVERABLE | Message cannot reach recipient |
| UNKNOWN | No delivery status was received after a specific amount of time therefore delivery is not known |
| REJECTED | The message was successfully submitted to the carrier for delivery but has actively been refused. |
| Undelivered | After attempting for a period of time, the carrier has failed to deliver the message to the destination handset. Please confirm the recipient's number is correct, and the handset is on and within reception range. |
| BLACKLISTED/SenderName Blacklisted | Promotional message has been blocked by recipient |
| AbsentSubscriber/Absent Subscriber | Phone number does not exist |
| DeliveryImpossible/Delivery Impossible | Message cannot be delivered |
| Network Failure | A network issue has caused delivery failure |
f) GET SMS Balance
You can get the SMS balances for both local and international accounts using this end point. It also gives you the local and international accounts numbers used for payments
NOTE: Send a GET request to get balance
Base URL: https://api.mobilesasa.com/v1/get-balance
Headers
Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:
Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json
Json body should be empty
Below is a sample CURL request
curl --location 'https://api.mobilesasa.com/v1/get-balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE'
Success Response
{
"status": true,
"responseCode": "0200",
"balance": 3245,
"internationalBalance": 100,
"localAccountNumber": "testlocal",
"internationalAccountNumber": "IN-test",
"emailWhatsAppAccountNumber": "EW-test",
"walletAccountNumber": "WL-test"
}
Failed Response
{
"status": false,
"responseCode": "0401",
"message": "Unauthenticated"
}
