Skip Headers
Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide
Release 5.0

Part Number E16621-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

5 Short Messaging

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

About the Short Messaging Interface

Applications use the RESTful Short Messaging interface to send an SMS, a ringtone, or a logo, to fetch SMSs and delivery status reports; and to start and stop a notification.

When the request body for an SMS operation contains a request for a delivery receipt, the application provides a correlator for the message being sent and includes an endpoint address for returning the delivery notification.

For such operations, the application client subscribes to and uses the Bayeux channel to which Services Gatekeeper is subscribed. The application provides the Bayeux channel name as the location for Services Gatekeeper to publish the notifications that the application client requires. See "Notifications and Publish/Subscribe".

REST Service Descriptions Available at Run-time

When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at

http://host:port/rest/sms/index.html

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


Send Sms

The Send Sms operation delivers a text message.

To send an Sms message, provide the SIP-formatted URI of the addresses which must receive the message in the request body. If there is to be a charge for the messaging, the request body should contain the required charging object. If the sender requires a delivery receipt, specify the required parameters for the receipt.

If the Send Sms operation is successful, the Location header field in the response will contain the request identifier (which is also provided in the response body for this operation).

If the application requested a receipt for delivery of the message, the application must access the endpoint address to retrieve the delivery notifications.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/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 Sms operation accepts the following parameters:

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

{
  "addresses": ["URI"],
  "message": "String",
  "charging": {
    "description": "String",
    "amount": "BigDecimal",
    "code": "String",
    "currency": "String"
  },
  "receiptRequest": {
    "correlator": "String",
    "endpoint": "URI",
    "interfaceName": "String"
  },
  "senderName": "String"
}

Response Header

The Location header field contains the URI:

http://host:port/rest/sms/delivery_status/result

where, result is the string identifier returned in the response body.

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 body of the response contains the request identifier as the string value for the result attribute. It is the request identifier returned in the Location header field of the response message. The application uses this request identifier (in the Get Sms Delivery Status operation) to retrieve the delivery status for the sent message.

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

{"result": "String"}

Send Sms Ringtone

The Send Sms Ringtone operation delivers a ringtone.

To send an Sms Ringtone message, provide the SIP-formatted URI of the addresses which must receive the message, the ringtone data and its format in the request body for this operation. If there is to be a charge for the messaging, the request body should contain the required charging object. If the sender requires a delivery receipt, specify the required parameters for the receipt.

If the Send Sms Ringtone operation is successful, the Location header field in the response will contain the request identifier (which is also provided in the response body for this operation).

If the application requested a receipt for delivery of the message, the application must access the endpoint address to retrieve the delivery notifications.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/sms/ringtones

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 is a nested JSON object containing the following parameters:

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

{
  "addresses": ["URI"],
  "ringtone": "String",
  "smsFormat": "Ems|SmartMessaging",
  "charging": {
    "description": "String",
    "amount": "BigDecimal",
    "code": "String",
    "currency": "String"
  },
  "receiptRequest": {
    "correlator": "String",
    "endpoint": "URI",
    "interfaceName": "String"
  },
  "senderName": "String"
}

Response Header

http://host:port/rest/sms/delivery_status/result

where, result is the string identifier returned in the request body.

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 body of the response contains the result attribute whose value is the request identifier returned in the Location header field of the response message. The application uses this request identifier (in the Get Sms Delivery Status operation) to retrieve the delivery status for the sent message.

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

{"result": "String"}

Send Sms Logo

The Send Sms Logo operation delivers a logo.

To send an Sms Logo, provide the SIP-formatted URI of the addresses which must receive the message, the logo data and its format in the request body for this operation. If there is to be a charge for the messaging, the request body should contain the required charging object. If the sender requires a delivery receipt, specify the required parameters for the receipt.

If the Send Sms Logo operation is successful, the Location header field in the response will contain the request identifier (which is also provided in the response body for this operation).

If the application requested a receipt for delivery of the message, the application must access the endpoint address to retrieve the delivery notifications.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/sms/logo

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 Sms operation accepts the following parameters:

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"],
  "image": "base64Binary",
  "smsFormat": "Ems|SmartMessaging",
  "charging": {
    "description": "String",
    "amount": "BigDecimal",
    "code": "String",
    "currency": "String"
  },
  "receiptRequest": {
    "correlator": "String",
    "endpoint": "URI",
    "interfaceName": "String"
  },
  "senderName": "String"
}

Response Header

The Location header field contains the URI:

http://host:port/rest/sms/delivery_status/result

where, result is the string identifier returned in the request body.

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 contains the result attribute whose value is the request identifier returned in the Location header field of the response message. The application uses this request identifier (in the Get Sms Delivery Status operation) to retrieve the delivery status for the sent message.

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

{"result": "String"}

Get Received Sms

The Get Received Sms operation polls the Services Gatekeeper for the SMSs that have been received from the network for an application.

The request header for the Get Received SMS operation contains the registration identifier necessary to retrieve the required SMSs intended for the application. This registration value should have been set up with the off-line provisioning step that enables the application to receive notification of SMS reception.

There is no request body.

If the Get Received Sms operation is successful, the response body will contain the message, the URI of the sender, the SMS service activation number and the date and time when the message was sent.

Authorization

Basic

HTTP Method

POST

URI

http://host:port/rest/sms/receive-messages/${registrationIdentifier}

where:

Request Header

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

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

The response body contains an array of structures as the value for result. Each element in the array contains values for the following parameters.

The response 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:

{"result": [{
  "message": "String",
  "senderAddress": "URI",
  "smsServiceActivationNumber": "URI",
  "dateTime": "Calendar"
}]}

Get Sms Delivery Status

The Get Sms Delivery Status operation retrieves the delivery status of a message that was previously sent using Send Sms, Send Sms Ringtone or Send Sms Logo operation.

The Get Sms Delivery Status operation is valid only if the correlator callback reference was not defined in the receiptRequest attribute of the initial request to send the short message. In such a scenario, Services Gatekeeper stores the delivery status for a configurable period of time.

(When the correlator callback reference is defined in the receiptRequest object of the initial request to send the short message, Services Gatekeeper will invoke the Notify Sms Delivery Receipt operation and discard the delivery status information.)

The request header for Get Sms Delivery Status contains the request identifier from the initial Send operation for the short message.

If Get Sms Delivery Status is successful, the response body will contain the SIP-formatted URIs from the address field in the request body of the Send operation for the short message and corresponding delivery status for each message.

Authorization

Basic

HTTP Method

GET

URI

http://host:port/rest/sms/delivery-status/${requestIdentifier}

where:

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

The response body contains an array of structures as the value for result. Each element in the array contains values for the following parameters.

The response 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:

{"result": [{
  "address": "URI",
  "deliveryStatus": "DeliveredToNetwork|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToTerminal|DeliveryNotificationNotSupported"
}]}

Start Sms Notification

The Start Sms Notification operation starts a notification for the application.

To set up an Sms notification, provide the criteria which will trigger notifications and a reference object for the delivery of the notifications. The criteria can be a string which, when matched, could be the notification of an Sms received or of a delivery receipt. The reference object (also a JSON object) contains the correlator for the notification, the endpoint address (a specific Bayeux channel name) to which the call direction notifications must be sent and, optionally, the interface name (a string to identify the notification).

If the Start Sms Notification request is successful:

When the Start Sms notification request is successful, the application can access the endpoint address to retrieve the specific call event notifications.

Authorization

Basic

HTTP Method

PUT

URI

http://host:port/rest/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 Sms Notification operation accepts the following parameters:

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": "URI",
  "criteria": "String"
}

Response Header

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

http://host:port/rest/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 Data Object for Sms Reception (notifySmsReception)

When an Sms is successfully retrieved by the called party and the value for criteria in the request body is notifySmsReception, Services Gatekeeper will send a nested JSON data object to the endpoint address.

This nested JSON object contains the following as the value of the attribute name notifySmsReception:

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

{"notifySmsReception": {
  "correlator": "String",
  "message": {
    "message": "String",
    "senderAddress": "URI",
    "smsServiceActivationNumber": "URI",
    "dateTime": "Calendar"
  }
}}

Notification Data Object for Sms Delivery Receipt (notifySmsDeliveryReceipt)

When an Sms is successfully retrieved by the called party and the value for criteria in the request body is notifySmsDeliveryReceipt, Services Gatekeeper sends a nested JSON data object to the endpoint address.

This nested JSON object contains the following as the value of the attribute name notifySmsDeliveryReceipt:

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

{"notifySmsDeliveryReceipt": {
  "correlator": "String",
  "deliveryStatus": {
    "address": "URI",
    "deliveryStatus": "DeliveredToNetwork|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToTerminal|DeliveryNotificationNotSupported"
  }
}}

Stop Sms Notification

The Stop Sms Notification operation terminates a previously set up Sms notification for the application.

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

There is no request or response body for the Stop Sms Notification operation. 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

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

where:

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.

Examples

Example 5-1 Stop Message Notification Request

DELETE /rest/sms/notification/12345 HTTP/1.1
X-Session-ID: app:4130997928482260925
Authorization: Basic ZG9tYWluX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host:10.182.100.218.8002

Example 5-2 Stop Message Notification Response

HTTP/1.1 204 No Content
Connection: close
Date: Thu, 04 Nov 2101 09:59:05 GMT
Content-Length: 0
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1