shortcodes

SECTION 2: SHORT CODE MESSAGING

1. Receiving Inbound Messages

The client will provide an endpoint that accepts the following JSON data through a POST request. In cases where a client wants the data pushed over a secure connection such as over SSL, the client will provide the necessary certificates to be configured in our application.

{
  "api_token": "944a73412bed1240b5a2afa381a928a6",
  "message": "Test inbox",
  "shortcode": "70700",
  "mobile": "254726770792",
  "inbox_id": "4448236",
  "service_id": "32",
  "network_name": "Safaricom",
  "timestamp": "20180217065028",
  "link_id": "763723672367236526261"
}

Where

Variable	Type	Description	Example
api_token	String	The token supplied by a partner for our service request authentication purposes. This can be an encrypted value of their username, server IP, timestamp, and password.	944a73412bed1240b5a2afa381a928a6
timestamp	String	Timestamp in the format YmdHis to be used in password decryption.	20180217065028
mobile	String	The user mobile number that should receive the payment. All mobile numbers are validated before a request is accepted.	254726770792
message	String	The message as received from the end user.	Test inbox
shortcode	String	The short code associated with the service.	70700
inbox_id	Int	A unique identifier of the message.	4448236
service_id	Int	The service identifier for the service.	34
network_name	String	A network identifier e.g Safaricom, Airtel, Yu, Equitel & Telkom	Safaricom
link_id	String	Received for On-Demand shortcode messages. This should be used when sending out replies.	326372781291728

On successful reception of an inbound message, the client should reply (echo back) with the following JSON string:

{
  "result_code": 1,
  "result_desc": "OK",
  "result_message": "Thank you for your message."
}

where

Variable	Type	Description	Example
request_code	Int	This is a status of the pushed message: 1 – Success; 0 – Failed. A message might fail to be received on the client’s side due to internal server errors etc.	1 or 0
request_desc	String	This is a brief description of the request. OK for successful reception; FAILED for a failed request.	OK or FAILED
result_message	String	This is a message our system should send back to the end user. Leave this empty to process a user request and reply back later through the sendSms API.	Thank you for your message

Sending short code messages

This is the same as sending a bulk message. The only difference is that a service_id will be added to this request. See example JSON below:

{
  "api_key": "1ts3bK2QVbr7caV9211b28kf0dd3kfIm7C2mGOLQca4",
  "sender_name": "22915",
  "mobile": "0708400000",
  "message": "This is a message from Ndovubase",
  "service_id": "44",
  "link_id": ""
}

where

Variable	Type	Description	Example
api_key	Int	The authentication string provided to the customer	qw566wqtwgqyw65wq
sender_name	String	The origination alphanumeric or numeric code	22915
message	String	The message our system should send to the end user. The message can be up to 920 characters long.	Click on the following link to download your content
mobile	String	Mobile number to receive the MT message	0708400000
service_id	Int	An identifier of the service allocated to the customer	44
link_id	Long	Used for On-Demand messages. Leave empty for subscription services	12345678987654321

The data is posted to the following endpoint:

sendSms endpoint: https://bulk.ndovubase.com/sms/v3/sendsms

Success Response Packet:

{
  "status_code": "1000",
  "status_desc": "Success",
  "message_id": "sms.5ed0e9e9619937.17151728",
  "mobile_number": "254708400000",
  "network_name": "Safaricom",
  "message_cost": "1",
  "credit_balance": "-1"
}

Failed response packet:

{
  "status_code": "1003",
  "status_desc": "Invalid mobile number 26770792",
  "message_id": "0",
  "mobile_number": "0",
  "network_name": "Not set",
  "message_cost": "0.00",
  "credit_balance": ""
}

Receiving (un)Subscription Requests

The client will register an endpoint with us that accepts JSON post requests. See a request sample below:

{
“api_token”:“23627367236232ghgge23g22gh2gh2”,
"network_name": "Safaricom",
"shortcode": "22915",
"service_id": "44",
"mobile": "254708400000",
"update_type": "activation",
"keyword": "GAME",
"subscriber_ref": "12345",
"timestamp": "20200528124756"
}

Subscription/Unsubscription Reque

The client will register an endpoint with us that accepts JSON post requests. Below is a sample request:

{
  "api_token": "2tyy23ty43y434hj3h43u4u3u4u",
  "timestamp": "20200528124756",
  "mobile": "254708400000",
  "update_type": "activation",
  "shortcode": "22915",
  "keyword": "GAME",
  "subscriber_ref": 12345,
  "service_id": 44,
  "network_name": "Safaricom"
}

where

The client will register an endpoint with us that accepts JSON post requests. Below is a sample request:

Variable	Type	Description	Example
api_token	String	Token for service request authentication	2tyy23ty43y434hj3h43u4u3u4u
timestamp	String	Timestamp in the format YmdHis	20200528124756
mobile	String	User mobile number	254708400000
update_type	String	Customer request type (activation/deactivation)	activation
shortcode	String	Short code associated with the service	22915
keyword	String	Exact keyword used when subscribing to the service	GAME
subscriber_ref	Int	Unique identifier of the customer in our services	12345
service_id	Int	Service identifier for the service	44
network_name	String	Network of the customer (e.g., Safaricom)	Safaricom

(Un)Subscription Response:

On successful reception of the (un)subscription request, the client should reply (echo back) with the following JSON string:

{
  "request_code": 1,
  "request_desc": "OK",
  "result_message": "Thank you for subscribing to our service."
}

Where

Variable	Type	Description	Example
request_code	Int	Status of the request (1 – Success; 0 – Failed). A failed request will be retried automatically after 3 minutes for up to 3 times.	1
request_desc	String	Brief description of the request (OK for successful reception; FAILED for a failed request).	OK
result_message	String	Message for our system to send back to the customer. Leave this empty to process a user request and reply back later through the sendSms API.	"Thank you for subscribing to our service."

(Un)Subscription API

This service is invoked by a client to activate or deactivate a customer on a certain service.

Endpoint: https://bulk.ndovubase.com/sms/v3/subscribermanage Activation Request Packet:

{
  "api_key": "1ts3bK2QVbr7caV9211b28kf0dd3kfIP95eb5bvEjAPScd12of1Pm7C2mGOLQca4",
  "service_id": "44",
  "mobile": "254708400000",
  "option": "activation"
}

Deactivation request packet:

{
  "api_key": "1ts3bK2QVbr7caV9211b28kf0dd3kfIP95eb5bvEjAPScd12of1Pm7C2mGOLQca4",
  "service_id": "44",
  "mobile": "254708400000",
  "option": "deactivation"
}

In both cases, you will receive the following responses:

{
  "status_code": "1",
  "status_desc": "Success",
  "mobile": "254708400000",
  "network_name": "Safaricom"
}

Response Variables

Variable	Type	Description	Example
status_code	Int	Status of your request: 1 – Success; else Failed.	1, 0, 1009
status_desc	String	Brief description of the request.	Success, Failed...
mobile	String	Reformatted mobile number of the customer.	254708400000
network_name	String	Detected network of the customer.	Safaricom, Airtel, Telkom, Equitel