| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the operations in the Short Messaging interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Short Messaging interface to send an SMS, a ringtone, or a logo, to fetch SMSes 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".
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.
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.
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.
The request body for the Send Sms operation accepts the following parameters:
addresses. Array of string values. Required. The set of addresses of the recipients as an array of SIP-formatted URIs.
message. String. Required. The text of the message.
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. If a delivery receipt is required, provide values for each of the following parameters which define this object:
correlator. String. Required. Used to correlate the receipt with the initial message.
If the callback reference correlator is defined in the receiptRequest attribute of the Send Sms request message, Services Gatekeeper will invoke the Notify Sms Delivery Receipt operation and discard the delivery status information.
endpoint. String. Required. The endpoint address (URI) to which the receipt must be delivered.
interfaceName. String. Required. A description provided to identify the type of receipt.
senderName. String. Optional. The sender's name.
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"
}
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".
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"}
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.
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.
The request body is a nested JSON object containing the following parameters:
addresses. Array of string values. Required. The set of addresses of the recipients as an array of SIP-formatted URIs.
ringtone. String. Required. The ringtone data in Extended Ringtone (RTX) format.
smsFormat. String. Required. The encoding format for the ringtone entered as one of the following:
Ems
SmartMessaging
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. If a delivery receipt is required, provide values for each of the following parameters which define this object:
correlator. String. Required. Used to correlate the receipt with the initial message.
If the callback reference correlator is defined in the receiptRequest object of the Send Sms request message, Services Gatekeeper will invoke the Notify Sms Delivery Receipt operation and discard the delivery status information.
endpoint. String. Required. The endpoint address (URI) to which the receipt must be delivered.
interfaceName. String. Required. A description provided to identify the type of receipt.
senderName. String. Optional. The sender's name.
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"
}
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".
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"}
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.
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.
The request body for the Send Sms operation accepts the following parameters:
addresses. Array of string values. Required. The set of addresses of the recipients as an array of SIP-formatted URIs.
image. String. Required. The logo data, a base64-encoded image in GIF, PNG or JPG format.
smsFormat. String. Required. The encoding format for the logo entered as one of the following:
Ems
SmartMessaging
charging. a JSON object. Optional. Use this object to define 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. If a delivery receipt is required, provide values for each of the following parameters which define this object:
correlator. String. Required. Used to correlate the receipt with the initial message.
If the callback reference correlator is defined in the receiptRequest object of the Send SMS request message, Services Gatekeeper will invoke the Notify Sms Delivery Receipt operation and discard the delivery status information.
endpoint. String. Required. The endpoint address (URI) to which the receipt must be delivered.
interfaceName. String. Required. A description provided to identify the type of receipt.
senderName. String. Optional. The sender's name.
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"
}
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".
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"}
The Get Received Sms operation polls the Services Gatekeeper for the SMSes 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 SMSes 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.
http://host:port/rest/sms/receive-messages/${registrationIdentifier}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
registrationIdentifier is the value previously set up to enable the application to receive notification of SMS reception according to specified criteria.
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".
The response body contains an array of structures as the value for result. Each element in the array contains values for the following parameters.
message. String. The text of the Sms message.
senderAddress. String. The SIP-formatted URI of the sender.
smsServiceActivationNumber. String. URI. The number associated with the invoked Message service, that is the destination address used to send the message.
dateTime. String. The start time for the call in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
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"
}]}
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.
http://host:port/rest/sms/delivery-status/${requestIdentifier}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
requestIdentifier is the identifier returned in the result object of the corresponding Send operation.
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".
The response body contains an array of structures as the value for result. Each element in the array contains values for the following parameters.
address. String. The SIP-formatted URI to which the initial message was sent.
deliveryStatus: Enumeration value. Table 7-1 lists the possible status:
Table 7-1 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to network. In case of concatenated messages, only when all the SMS-parts have been successfully delivered to the network. |
|
DeliveryUncertain |
Delivery status unknown, for example, if it was handed off to another network. |
|
DeliveryImpossible |
Unsuccessful delivery; the message could not be delivered before it expired. |
|
DeliveredToTerminal |
Successful delivery to terminal. In case of concatenated messages, only when all the SMS-parts have been successfully delivered to the terminal. |
|
DeliveryNotificationNotSupported |
Unable to provide delivery receipt notification. |
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"
}]}
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:
The response header will contain the URI of the publish/subscribe server.
A data object associated with the result of the short message operation will be sent to the endpoint address specified in the request body. This data object will contain the appropriate notification (that the message was received or a delivery receipt for the call).
When the Start Sms notification request is successful, the application can access the endpoint address to retrieve the specific call event notifications.
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.
The request body for the Start Sms Notification operation accepts the following parameters:
criteria. String. Optional. The text to match against in determining whether or not the application should receive the notification:
notifySmsReception
notifySmsDeliveryReceipt
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.
smsServiceActivationNumber. String. Required. The number associated with the invoked Message service, that is the destination address used to send the message
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"
}
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".
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:
correlator. String. Required. The correlator used to identify the notification.
message. Nested JSON object. Required. It contains the following:
message. String. Required. The contents of the Sms message.
senderAddress. String. Required. The SIP-formatted URI of the sender of the Sms message.
smsServiceActivationNumber. String. Required. The number associated with the invoked Message service, that is the destination address used to send the message.
dateTime. String. Optional. The time at which the message was sent in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
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:
correlator. String. The correlator used to identify the notification.
deliveryStatus. Enumeration value. Table 7-2 lists the possible status:
Table 7-2 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to network. In case of concatenated messages, only when all the SMS-parts have been successfully delivered to the network. |
|
DeliveryUncertain |
Delivery status unknown, for example, if it was handed off to another network. |
|
DeliveryImpossible |
Unsuccessful delivery; the message could not be delivered before it expired. |
|
DeliveredToTerminal |
Successful delivery to terminal. In case of concatenated messages, only when all the SMS-parts have been successfully delivered to the terminal. |
|
DeliveryNotificationNotSupported |
Unable to provide delivery receipt notification. |
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"
}
}}
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.
http://host:port/rest/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 Sms Notification request body.
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".
|
 Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|