SMS¶

Serviço de mensagens curtas (SMS)¶

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

Serviço de envio de SMS¶

The Web API supports sending outgoing SMS using the POST method. SMS can be sent to 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.

/api/sms/outbound

{
  "message":"Sms Text",
  "recipients": [
    "004712341234",
    "004712341235"
  ]
}

** Nota **

A lista de destinatários será particionada se o tamanho exceder o limite de MAX_ALLOWED_RECIPIENTS de 200.

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

/api/sms/outbound?message=text&recipient=004712341234

Outbound messages can be fetched using GET resource.

GET /api/sms/outbound
GET /api/sms/outbound?filter=status:eq:SENT
GET /api/sms/outbound?filter=status:eq:SENT&fields=*

Outbound messages can be deleted using DELETE resource.

DELETE /api/sms/outbound/{uid}
DELETE /api/sms/outbound?ids=uid1,uid2

Códigos de resposta de gateway¶

O gateway pode responder com os seguintes códigos de resposta.

Serviço de entrada de SMS¶

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/sms/inbound

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

Inbound messages can be fetched using GET resourcef

GET /api/sms/inbound
GET /api/sms/inbound?fields=*&filter=smsstatus=INCOMING

Inbound messages can be deleted using DELETE resource

DELETE /api/sms/inbound/{uid}
DELETE /api/sms/inbound?ids=uid1,uid2

To import all un parsed messages

POST /api/sms/inbound/import

Administração de serviço de gateway¶

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/33/gateways

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

GET /api/33/gateways/{uid}

New gateway configurations can be added using POST. POST api requires type request parameter and currently its value can have either one http,bulksms,clickatell,smpp. First added gateway will be set to default. Only one gateway is allowed to be default at one time. Default gateway can only be changed through its api. If default gateway is removed then the next one the list will automatically becomes default.

POST / api / 33 / gateways

A configuração pode ser atualizada fornecendo configurações de uid e gateway conforme mencionado abaixo

PUT /api/33/gateways/{uids}

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

DELETE / api / 33 / gateways / {uid}

O gateway padrão pode ser recuperado e atualizado.

GET /api/33/gateways/default

O gateway padrão pode ser definido usando o método PUT.

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

Configuração de gateway¶

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¶

{
  "type" : "clickatell",
  "name" : "clickatell",
  "username": "clickatelluser",
  "authToken": "XXXXXXXXXXXXXXXXXXXX",
  "urlTemplate": "https://platform.clickatell.com/messages"
}

Bulksms¶

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

Gateway SMPP¶

{
  "type": "smpp",
  "name": "smpp gateway2",
  "systemId": "smppclient1",
  "host": "localhost",
  "systemType": "cp",
  "numberPlanIndicator": "UNKNOWN",
  "typeOfNumber": "UNKNOWN",
  "bindType": "BIND_TX",
  "port": 2775,
  "password": "password",
  "compressed": false
}

HTTP genérico¶

{
  "type": "http",
  "name": "Generic",
  "configurationTemplate": "username=${username}&password=${password}&to=${recipients}&countrycode=880&message=${text$}&messageid=0",
  "useGet": false,
  "sendUrlParameters":false,
  "contentType": "APPLICATION_JSON",
  "urlTemplate":"https://samplegateway.com/messages",
  "parameters": [
    {
      "header": true,
      "encode": false,
      "key": "username",
      "value": "user_uio",
      "confidential": true
    },
    {
      "header": true,
      "encode": false,
      "key": "password",
      "value": "123abcxyz",
      "confidential": true
    },
    {
      "header": false,
      "encode": false,
      "key": "deliveryReport",
      "value": "yes",
      "confidential": false
    }
  ],
  "isDefault": false
}

No gateway HTTP genérico, qualquer número de parâmetros pode ser adicionado.

HTTP.OK will be returned if configurations are saved successfully otherwise Error

Comandos SMS¶

SMS commands are being used to collect data through SMS. These commands belong to specific parser type. Each parser has different functionality.

A lista de comandos pode ser recuperada usando GET.

GET /api/smsCommands

Um comando específico pode ser recuperado usando GET.

GET /api/smsCommands/uid

Um comando específico pode ser atualizado usando PUT.

PUT /api/smsCommands/uid

O comando pode ser criado usando POST.

POST / api / smsCommands

Um comando específico pode ser excluído usando DELETE.

DELETE / api / smsCommands / uid

Tipos de comando SMS¶

Tipos de comando SMS para Android¶

Esses tipos de comando podem ser usados pelo aplicativo Android para envio de dados via SMS quando a internet não estiver disponível. O SMS é composto pelo app Android.