17 Binary Short Messaging

This chapter describes the operations in the Binary Short Messaging interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About the Binary Short Messaging Interface

Applications use the RESTful Binary Short Messaging interface allows an application to send any generic binary object attachments to the network using SMS. The supported binary content is broader than the logos and ringtones specified by the Parlay X SMS Web service, extending to other types of binary content such as vCards (a file format standard for electronic business cards).

These interfaces also provide operations to start and stop notifications for SMSes with binary content.

Send Binary Sms

The Send Binary Sms operation sends an SMS that includes content in binary format.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/binary_sms/messages

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Send Binary Sms operation accepts the following parameters:

addresses. String. Required. The set of end-user terminal addresses of the recipients as an array of SIP-formatted URIs.
binaryMessage. An array of JSON objects. Required. The message to be sent as an array of User Data Header (UDH) elements and message elements. Note that the entire array must be less than of equal to 141 bytes.

Each element in the array contains:
- message. String in base64Binary. Binary Message data formatted as TP-User Data (TP-UD) excluding the TP-User-Data-Indicator (TP UDHI).
- udh. String in base64Binary. Specifies if the TP-User Data (TP-UD) field contains only the short message, or if it also contains the header formatted as the TP-User-Data-Indicator (TP UDHI).
dcs: Byte. Required. The data-encoding scheme for the binaryMessage parameter.
protocolId. Byte. Required. TP-Protocol-Identifier according to 3GPP 23.040 6.5.0
charging. A JSON object. Optional. This object defines the cost charging properties for the operation. The entry "charging": null indicates no charge. If a charge is to be applied, provide values for the following in the charging object:
- description. String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
- amount. Number (integer, or decimal). Optional. The amount to be charged.
- code. String. Optional. The charging code, from an existing contractual description.
- currency. String. Optional. The currency identifier as defined in ISO 4217 [9].
receiptRequest. a JSON object. Optional. Used to notify the application that the message has been delivered to the terminal, or that delivery is impossible.

If a delivery receipt is required, provide values for each of the following parameters which define this object:
- correlator. String. Used to correlate the receipt with the initial message.
- endpoint. String. The endpoint address (URI) to which the receipt must be delivered.
- interfaceName. String. A description provided to identify the type of receipt.
senderName. String. Optional. The sender's name.
validityPeriod. String. The validity period of the short message, formatted as a validity-period parameter as described in SMPP v3.4.

The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:

{
  "addresses":["URI"],
  "binaryMessage":[{
    "message":"base64Binary"
    "udh":"base64Binary"
  }],
  "dcs":"Byte",
  "charging": {
    "description": "String",
    "amount": "BigDecimal",
    "code": "String",
    "currency": "String"
  }
  "protocolId":"Byte",
  "receiptRequest": {
    "correlator": "String",
    "endpoint": "URI",
    "interfaceName": "String"
  },
  "senderName":"String",
  "validityPeriod":"String",
}

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

The response body is a JSON object which contains the result attribute. The identifier for the delivery request is the string value for result.

{"result":"String"}

Start Binary Sms Notification

The Start Binary SMS Notification operation starts a notification for short messages that contain binary content.

Authorization

Basic

HTTP Method

PUT

URI

http://host:port/rest/binary_sms/notification

where host and port are the host name and port of the machine on which Services Gatekeeper is installed.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

The request body for the Start Binary SMS Notification operation accepts the following parameters:

smsServiceActivationNumber. String. Required. The destination address, as URI, of the short message.
reference. JSON object. Required. Use this object to provide the following information about the endpoint that is to receive the notification:
- correlator. String. Required. The correlator used to identify the notification.
- endpoint. String. Required. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID.
  
  For more information on application instances, see the discussion on creating and maintaining service provider and application accounts in Oracle Communications Services Gatekeeper Accounts and SLAs Guide.
- interfaceName. String. Required. A descriptive string to identify the type of notification.

The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:

{
  "reference": {
    "correlator": "String",
    "endpoint": "URI",
    "interfaceName": "String"
  },
  "smsServiceActivationNumber":"String",
}

Response Header

The Location header field contains the URI of the publish/subscribe server:

http://host:port/rest/binary_sms/notifications

If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body. The appropriate notifications (described below) are sent to the endpoint address provided by the application in the request body of this operation.

Notification of Binary SMS Reception

When a Binary SMS has been received for an application, its designated endpoint address on the pub-sub server receives a nested JSON object.

This nested JSON object contains the following as the value for the attribute notifyBinarySmsReception:

correlator. String. The correlator used in the request body for this operation.
message. a nested JSON object. It contains the data-encoding scheme for the set of messages in the notification, and the messages as an array of User Data Header (UDH) elements and message elements.
- dcs. Byte. The data-encoding scheme for the binary messages included in this object.
- message. Array of JSON objects. Table 17-1 lists the contents of each message object:
  
  Table 17-1 Attributes of Message Object
  
  Attribute Description
  
  message
  
  Message data as a string base64Binary format
  
  udh
  
  Information specifying the message data format
senderAddress. String. The sender's address, as a URI.
smsServiceActivationNumber. String. The destination address for the binary message, as a URI.
dateTime. String. The date and time the message was received in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
protocolId. Byte. The TP-Protocol-Identifier according to 3GPP 23.040 6.5.0.

Attribute	Description
message	Message data as a string base64Binary format
udh	Information specifying the message data format

The notification data object delivered to the endpoint address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:

{"notifyBinarySmsReception": {
  "correlator":"String",
  "message":{
    "dcs":"Byte",
    "message":[{
        "message":"base64Binary"
        "udh":"base64Binary"
      }],
  "senderAddress":"URI",
  "smsServiceActivationNumber": "URI",
  "dateTime":"Calendar"
  "protocolId":"Byte"
  }
}}

Stop Binary Sms Notification

The Stop Binary Sms Notification operation terminates a previously-started notification for messages that contain binary content.

To stop a previously set up binary Sms notification, provide the correlator for the notification passed earlier in the Start Binary Sms Notification request.

There is no request or response body for Stop Binary Sms Notification. If the request fails, the body of the error response will contain the identifier for the notification and the type of exception.

Authorization

Basic

HTTP Method

DELETE

URI

The Request-URI used in the DELETE method for Stop Sms Notification is:

http://host:port/rest/binary_sms/notification/${correlator}

where:

host and port are the host name and port of the machine on which Services Gatekeeper is installed.
correlator is the correlator for the notification provided in the reference object of the initial Start Binary Sms Notification request.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".

Response Body

There is no response body.