SMS¶

Short Message Service (SMS)¶

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

Odchozí služba 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"
  ]
}

Poznámka

Seznam příjemců bude rozdělen, pokud MAX_ALLOWED_RECIPIENTS překročí limit 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

Odchozí zprávy lze načíst pomocí prostředku GET.

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

Odchozí zprávy lze odstranit pomocí prostředku DELETE.

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

Kódy odezvy brány¶

Brána může reagovat s následujícími kódy odpovědí.

Tabulka: Kódy odezvy brány

Služba příchozích 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"
}

Příchozí zprávy lze načíst pomocí prostředku GET

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

Příchozí zprávy lze odstranit pomocí prostředku DELETE

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

Chcete-li importovat všechny nepřečtené zprávy

POST /api/sms/inbound/import

Tabulka: Parametry dotazu uživatele

Správa služby brány¶

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

Konfiguraci lze aktualizovat poskytnutím konfigurací uid a gateway, jak je uvedeno níže

PUT /api/33/gateways/{uids}

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

DELETE /api/33/gateways/{uid}

Výchozí bránu lze načíst a aktualizovat.

GET /api/33/gateways/default

Výchozí bránu lze nastavit pomocí metody PUT.

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

Konfigurace brány¶

Webové rozhraní API umožňuje vytvářet a aktualizovat konfigurace brány. Pro každý typ brány jsou v zátěži JSON různé parametry. Níže jsou uvedeny příklady užitečných zatížení JSON pro jednotlivé brány. Pro vytvoření konfigurace se používá POST a pro aktualizaci PUT. Parametr hlavičky lze použít v případě brány GenericHttpGateway k odeslání jednoho nebo více parametrů jako hlavičky http.

Clickatell¶

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

Bulksms¶

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

SMPP Brána¶

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

Obecný HTTP¶

{
  "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
}

V obecné bráně http lze přidat libovolný počet parametrů.

Tabulka: Obecné parametry SMS brány

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

SMS příkazy¶

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

Seznam příkazů lze vyvolat pomocí GET.

GET /api/smsCommands

Jeden konkrétní příkaz lze načíst pomocí GET.

GET /api/smsCommands/uid

Jeden konkrétní příkaz lze aktualizovat pomocí PUT.

PUT /api/smsCommands/uid

Příkaz lze vytvořit pomocí POST.

POST /api/smsCommands

Jeden konkrétní příkaz lze odstranit pomocí DELETE.

DELETE /api/smsCommands/uid

Typy příkazů SMS¶

Typy příkazů SMS pro Android¶

Tyto typy příkazů může aplikace pro Android používat k odesílání dat pomocí SMS, když není k dispozici internet. SMS se skládá z aplikace pro Android.