1.52 Short Message Service (SMS)

This section covers the SMS Web API for sending and receiving short text messages.

1.52.1 Outbound SMS service

The Web API supports sending outgoing SMS using the POST method. SMS can be sent to a single or multiple destinations. One or more gateways need to be configured before using the service. An SMS will not be sent if there is no gateway configured. It needs a set of recipients and message text in JSON format as shown below.

NOTE: Recipients list will be partitioned if its size exceed MAX_ALLOWED_RECIPIENTS limit which is 200.

/api/26/sms/outbound

{
  "message":"Sms Text",

  "recipients": [
    "47XXXXXX1",
    "47XXXXXX2"
  ]

}

The Web API also supports a query parameter version, but the parametrised API can only be used for sending SMS to a single destination.

/api/26/sms/outbound?message=text&recipient=47XXXXXX

1.52.1.1 Gateway response codes

Gateway may response with following response codes.

Gateway response codes
Response code Response Message Detail Description
RESULT_CODE_0 success Message has been sent successfully
RESULT_CODE_1 scheduled Message has been scheduled successfully
RESULT_CODE_22 internal fatal error Internal fatal error
RESULT_CODE_23 authentication failure Authentication credentials are incorrect
RESULT_CODE_24 data validation failed Parameters provided in request are incorrect
RESULT_CODE_25 insufficient credits Credit is not enough to send message
RESULT_CODE_26 upstream credits not available Upstream credits not available
RESULT_CODE_27 exceeded your daily quota You have exceeded your daily quota
RESULT_CODE_40 temporarily unavailable Service is temporarily down
RESULT_CODE_201 maximum batch size exceeded Maximum batch size exceeded
RESULT_CODE_200 success The request was successfully completed
RESULT_CODE_202 accepted The message(s) will be processed
RESULT_CODE_207 multi-status More than one message was submitted to the API; however, not all messages have the same status
RESULT_CODE_400 bad request Validation failure (such as missing/invalid parameters or headers)
RESULT_CODE_401 unauthorized Authentication failure. This can also be caused by IP lockdown settings
RESULT_CODE_402 payment required Not enough credit to send message
RESULT_CODE_404 not found Resource does not exist
RESULT_CODE_405 method not allowed Http method is not support on the resource
RESULT_CODE_410 gone Mobile number is blocked
RESULT_CODE_429 too many requests Generic rate limiting error
RESULT_CODE_503 service unavailable A temporary error has occurred on our platform - please retry

1.52.2 Inbound SMS service

The Web API supports collecting incoming SMS messages using the POST method. Incoming messages routed towards the DHIS2 Web API can be received using this API. The API collects inbound SMS messages and provides it to listeners for parsing, based on the SMS content (SMS Command). An example payload in JSON format is given below. Text, originator, received date and sent date are mandatory parameters. The rest are optional but the system will use the default value for these parameters.

/api/26/sms/inbound

{
  "text": "sample text",
  "originator": "47XXXXXXXX",
  "gatewayid": "unknown",
  "receiveddate": "2016-05-01",
  "sentdate":"2016-05-01",
  "smsencoding": "1",
  "smsstatus":"1"
}

The Web API also supports a query parameter-based version.

/api/26/sms/inbound?message=text&originator=47XXXXXX&gateway=clickatel
User query parameters
Parameter Type Description
message String This is mandatory parameter which carries the actual text message.
originator String This is mandatory parameter which shows by whom this message was actually sent from.
gateway String This is an optional parameter which gives gateway id. If not present default text “UNKNOWN” will be stored
receiveTime Date This is an optional parameter. It is timestamp at which message was received at the gateway.

1.52.3 Gateway service administration

The Web API exposes resources which provide a way to configure and update SMS gateway configurations.

The list of different gateways configured can be retrieved using a GET method.

GET /api/26/gateways

Configurations can also be retrieved for a specific gateway type using GET method.

GET /api/26/gateways/{uid}

Configurations can be removed for specific gateway type using DELETE method.

DELETE /api/26/gateways/{uid}

Default gateway can be retrieved with the GET method.

GET /api/26/gateways/default

Default gateway can be set using the PUT method.

PUT /api/26/gateways/default/{uid}

1.52.4 Gateway configuration

The Web API lets you create and update gateway configurations. For each type of gateway there are different parameters in the JSON payload. Sample JSON payloads for each gateway are given below. POST is used to create and PUT to update configurations. Header parameter can be used in case of GenericHttpGateway to send one or more parameter as http header.

Clickatell

{
  "name" : "clickatell",
  "username": "clickatelluser",
  "password": "abc123",
  "Auth-token": "XXXXXXXXXXXXXXXXXXXX",
}

Bulksms

{
  "name": "bulkSMS",
  "username": "bulkuser",
  "password": "abc123",
}

GenericHttp

{
  "name" : "generic",
  "messageParameter": "message",
  "recipientParameter": "msisdn",
  "urlTemplate": "http://localhost:template",
  "parameters": [
    {
      "key": "username",
      "value": "user12",
      "classified": "false",
      "header": "false"
    },
    {
      "key": "password",
      "value": "XXX",
      "classified": "true",
            "header": "false"
    }
  ]
}

HTTP.OK will be returned if configurations are saved successfully. In all other cases HTTP.ERROR will be returned.

The various gateway configurations can be instantiated using the endpoints listed below.

Gateway api end points
Gatway Type Method API End Points
Clickatell POST/PUT /api/26/gateways/clickatell
Bulksms POST/PUT /api/26/gateways/bulksms
Generichttp POST/PUT /api/26/gateways/generichttp