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:

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. POST 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"
}

Short Codes

Short codes are 5-digit numbers such as 23358 that provide two way SMS communication. This enables an organization to automate communication via SMS. This can be used to provide feedback, perform customer care functions among many other uses.

1) Receiving Short Code SMS

You can receive SMS details sent to the short code by providing us a callback URL where the details are sent to. A Json payload is sent to the end point as below:

{
   "reference":"0128b6d6-db68-4bc2-868d-4acc0c93c72a",
   "shortCode":"23358",
   "msisdn":"254723xxxxxx",
   "message":"This is a sample message",
   "receivedAt":"20240312095937"
}

The parameters are explained below:

Parameter Name	Description	Example
reference	The unique identifier of the message	0128b6d6-db68-4bc2-868d-4acc0c93c72a
shortCode	Your registered short code number	23358
msisdn	Sender phone number	254722002222
message	Message sent by the sender	This is a sample message
receivedAt	Time the message was sent by sender	20240312095937

2) Sending A short Code Message

To enable sending out short code messages, for example, to automate replies, the short code is registered as an SMS sender ID. You can therefore send out SMS using the send SMS options explained in the first section and use the short code as the senderId.

Groups

Groups are used to segment contacts. A group can have contacts with phone, name and email. You can add and delete contacts from group

1) Get SMS Groups

This is used to get a list of registered groups in an account.

NOTE: Send a GET request to get groups

Base URL: https://api.mobilesasa.com/v1/groups

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/groups' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "groups": [
        {
            "groupId": "9b51731e-2ed4-4649-8ba8-7be1c4a56345",
            "name": "Test Group"
        }
    ]
}

Failed Response

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

2) Add Contacts to Group/Edit contact

You can automatically add contacts to group. If the contact (phone number) exists, the name and email will be updated

Base URL: https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/add-contact

NOTE: The group UUID should be passed in the URL. 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": "0705xxxxxx",
    "name": "Test Contact",
    "email": "[email protected]"
}

Below is a sample CURL request


curl --location 'https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/add-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"phone": "0705xxxxxx",
"name": "Test Contact",
"email": "[email protected]"
}'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact Added"
}

Failed Response

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

3) Delete Contact from Group

You can automatically delete contact from group.

Base URL: https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/remove-contact

NOTE: The group UUID should be passed in the URL. Send a DELETE 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": "0705xxxxxx"
}

Below is a sample CURL request


curl --location 'https://api.mobilesasa.com/v1/groups/GROUP-UUID-HERE/remove-contact' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
"phone": "0705xxxxxx"
}'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "message": "Contact deleted!"
}

Failed Response

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

USSD Codes

USSDs are numbers such as *657# that are used to provide interactive menus for users to access certain functions. It can be used by financial institutions to provide self-service functions such as balance enquiry, loan application, payments etc

1) Receiving USSD Request

To receive a USSD request, register a callback URL on your extension. to do so, go to "Shared USSD" and then click on the "Update Extension" button then change as below:

This callback will receive POST form data parameters as shown below:

Parameter Name	Description	Example
sessionId	The unique identifier of the session	88867484
networkCode	Telco network	1
serviceCode	USSD code	*657#
phoneNumber	Phone number of the person dialing	254722002222
text	Text dialled by the user. NOTE: every input by the user is concatenated to the previous and separated by *	1234John Doe[email protected]

2) Sending Feedback

The USSD code sends back response that you return to the user. The response must begin with CON or END. CON is used when the session is still active, for example, when you need further input but END is used to end the session.

Request Type	Example
Continue	CON Enter your pin number
End	END You will receive your confirmation shortly

Mobile Survey

You can trigger surveys to be sent to specific contacts. The survey must be set on the survey portal accessible at getsurvey.co.ke. Log into the account to get your API Key

a) Trigger Survey

To trigger a survey, send a POST request as shown below:

Base URL: https://api.getsurvey.co.ke/api/trigger

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

{
    "survey": "test-660a-4009-a592-uuid",
    "send_now": true,
    "start_time": null,
    "end_time": null,
    "members": [
     {
            "name": "John Doe",
            "phone": "0722002222"
     }
    ]
}

Success Response

{
    "status": true,
    "message": "Survey initiated successfully",
    "errors": []
}

Failed Response

{
    "status": false,
    "message": "Survey could not be initiated",
    "errors": [
        "Survey does not exist"
    ]
}

The parameters are as shown below:

Parameter Name	Description
survey	The unique identifier of the survey. It can be found when you log into the survey portal
send_now	It's either true or false. If set to true, the message is sent instantly. If set to false, message is scheduled. If set to true, start_time and end_time will be null. If set to false, then start_time and end_time must be set in the format specified
start_time	If send_now is false, this is the time when survey is scheduled to start. Format is Y-m-d H:i:s
end_time	If send_now is false, this is the time when survey is scheduled to end. Format is Y-m-d H:i:s
members	These are recipients of the survey which are name and phone pairs