This chapter describes the Oracle Communications Services Gatekeeper OneAPI Short messaging/SMPP communication service in detail.
Applications use the RESTful OneAPI SMS interface to send and fetch SMS messages, deliver status reports, and start and stop notifications.
When the request body for an SMS operation contains a request for a delivery receipt, the application provides a notifyURL correlator for the message being sent and includes an endpoint address for returning the delivery notification.
The Services Gatekeeper OneAPI SMS interface complies with Open Mobile Alliance (OMA) specifications. See the discussion on OneAPI short messaging in Services Gatekeeper Statement of Compliance for a reference to the supported specification and RESTful bindings schema.
See "Using the OneAPI RESTful Interfaces" in Services Gatekeeper Application Developer's Guide for information on using the Services Gatekeeper OneAPI interfaces.
The information provided in this chapter is based on the OneAPI specification and is provided here for convenience.
When the Administration Server for your Services Gatekeeper domain is in the running state, the OneAPI REST service descriptions of these operations are located here:
http://host:port/oneapi/1/smsmessaging/application.wadl
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
To send an SMS message, provide the OneAPI-formatted URI of the addresses that must receive the message in the request body. 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 contains the request identifier (which is also provided in the response body for this operation).
If the application requires a receipt for delivery of the message, the application must provide the notifyURL to which notifications are to be sent in the message body.
http://host:port/oneapi/1/smsmessaging/outbound/senderAddress/requests
Where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
senderAddress is the subscriber for which the message is being sent.
The MIME-type for the Content-Type header field can be application/x-www-form-urlencoded, application/json or application/xml.
The request body for the OneAPI send SMS operation accepts the following parameters:
address: String. At least one address is the URL-escaped end user ID; in this case the MSISDN including the 'tel:' protocol identifier and the country code preceded by ’+'. i.e., tel:+15415550100.
message: String. Must be URL-escaped as per RFC 1738. Messages over 160 characters may be sent as two or more messages by the operator.
senderAddress: String. The address to whom a responding SMS may be sent.
clientCorrelator: String. Optional. Uniquely identifies this create SMS request. If there is a communication failure during the request, using the same client correlator when retrying the request allows the operator to avoid sending the same SMS twice.
senderName: String. Optional. The URL-escaped name of the sender to appear on the terminal. This is the address to whom a responding SMS may be sent.
If the senderName parameter is present, Services Gatekeeper displays the senderName value as the sender entry in the SMS message delivered to the mobile subscriber.
If the senderName parameter is not present, Services Gatekeeper displays the value in the senderAddress parameter as the sender entry in the SMS message delivered to the mobile subscriber.
notifyURL: anyURL. The URL-escaped URL to which a notification of delivery sent. The notifyURL will be ignored if a notification subscription already exists for the senderAddress. The format of this notification is shown in Example 21-1.
callbackData: String. Will be passed back in this notification, so you can use it to identify the message the receipt relates to or any other useful data, such as a function name.
The Location header field contains the URI:
http://host:port/oneapi/1/smsmessaging/outbound/address/requests/requestID
Where requestID 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. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The body of the response contains the request identifier as the string value for the resourceReference attribute. It is the request identifier returned in the Location header field of the response message and is also included in the resourceReference body. The application uses this request identifier 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:
{"resourceReference": {"resourceURL": "String"}}
Example 21-1 shows a sample OneAPI Send SMS request.
Example 21-1 OneAPI Send SMS Request
POST http://example.com/oneapi/1/smsmessaging/outbound/tel%3A%2B5550100/requests HTTP/1.1 Host: example.com:80 Content-Type: application/x-www-form-urlencoded Accept: application/json address=tel%3A%2B15415550100& address=tel%3A %2B15415550101& senderAddress=tel:%2B5550100& message=Hello%20World& clientCorrelator=123456& notifyURL=http://application.example.com/notifications/DeliveryInfoNotification& callbackData=some-data-useful-to-the-requester& senderName=ACME%20Inc.
Example 21-2 shows a sample Send SMS response.
Example 21-2 OneAPI Send SMS Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/1/smsmessaging/outbound/ tel%3A%2B5550100/requests/abc123
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"resourceReference": {"resourceURL": " http://example.com/oneapi/1/smsmessaging/outbound/ tel%3A%2B5550100/requests/abc123"}}
The Query Delivery Status operation retrieves the delivery status of a previously-sent message by using the system-generated requestID returned when the message was created.
If the Query Delivery Status is successful, the response body contains the delivery status for each of the addresses contained in the original send SMS request.
http://host:port/oneapi/1/smsmessaging/outbound/senderAddress/requests/requestID/deliveryInfos
Where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
senderAddress is the address to which a responding SMS may be sent.
requestID 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” in Using the OneAPI RESTful Interfaces for more information.
The response body contains an array of structures as the value for deliveryInfo. Each element in the array contains values for the following parameters.
address: String. The telephone number to which the initial message was sent.
deliveryStatus: Enumeration value. Table 21-1 lists the possible statuses:
Table 21-1 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to the network. For concatenated messages, returned 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 the terminal. For concatenated messages, returned only when all the SMS-parts have been successfully delivered to the terminal. |
|
MessageWaiting |
The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states. |
resourceURL: A reference to the response.
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:
{"deliveryInfoList": {
"deliveryInfo": [
{ "address": "String",
"deliveryStatus": "String"},
{ "address": "String",
"deliveryStatus": "String"}],
"resourceURL": " http://example.com/oneapi/1/smsmessaging/outbound/senderAddress/requests/requestID/deliveryInfos"
}}
Example 21-3 shows a sample OneAPI Query Delivery Status request.
Example 21-3 OneAPI Query Delivery Status Request
GET http://example.com/oneapi/1/smsmessaging/outbound/tel%3A%2B5550100/requests/abc123/deliveryInfos HTTP/1.1 Accept: application/json
Example 21-4 shows a sample OneAPI Query Delivery Status response.
Example 21-4 OneAPI Query Delivery Status Response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"deliveryInfoList": {
"deliveryInfo": [
{ "address": "tel:+15415550100",
"deliveryStatus": "MessageWaiting"},
{ "address": "tel:+15415550101",
"deliveryStatus": "MessageWaiting"}],
"resourceURL": " http://example.com/oneapi/1/smsmessaging/outbound/tel%3A%2B5550100/requests/abc123/deliveryInfos "
}}
The Subscribe to SMS Delivery Notification operation creates a subscription to delivery notifications for an application.
To set up an SMS notification, provide the criteria which will trigger notifications and a notifyURL 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 request body contains the correlator for the notification, the notifyURL to which the call direction notifications must be sent and, optionally, the callbackData (a string to identify the notification).
If the subscription 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 notifyURL 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).
http://host:port/oneapi/1/smsmessaging/outbound/senderAddress/subscriptions
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
senderAddress is the address to whom a responding SMS may be sent.
The MIME-type for the Content-Type header field can be application/json, application/xml, or application/x-www-form-urlencoded.
The request body for the subscription operation accepts the following parameters:
notifyURL: URL. This will be used by the server to POST the notifications to you, so include the URL of your own listener application
clientCorrelator: String. Optional. Uniquely identifies this create subscription request. If there is a communication failure during the request, using the same client correlator when retrying the request allows the operator to avoid creating a duplicate subscription.
callbackData: String. Optional. A function name or other data that you would like included when the POST is received.
The Location header field contains the URI of the notification server:
http://host:port/oneapi/1/smsmessaging/outbound/subscriptions/subscriptionID
Where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the reference to the created subscription.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The response body contains a confirmation deliveryReceiptSubscription JSON data structure consisting of the parameters supplied in the subscription request.
{"deliveryReceiptSubscription": {
"callbackReference": {
"callbackData": "String",
"notifyURL": " www.yourURL.here ",
"criteria":"String"
},
"resourceURL": " URL "}}
A resourceURL is included as a reference to the response.
Notification Data Object for SMS Delivery Receipt Sent to notifyURL
After a OneAPI SMS subscription is made, Services Gatekeeper delivers a message receipt notification to the notifyURL specified in the subscription request.
This nested JSON object contains the following as the value of the attribute name deliveryInfoNotification:
callbackData: String. The correlator used to identify the notification.
deliveryInfo: JSON Object. Contains the following two parameters:
address: String. The message recipient's subscriber ID.
deliveryStatus: Enumeration value. Table 21-2 lists the possible statuses:
Table 21-2 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to the network. For concatenated messages, returned 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 the terminal. For concatenated messages, returned only when all the SMS-parts have been successfully delivered to the terminal. |
The notification data object delivered to the notifyURL address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"deliveryInfoNotification": {
"callbackData": "String",
"deliveryInfo": {
"address": "String",
"deliveryStatus": "Enumeration Value"},
}}
Example 21-5 shows a sample OneAPI Subscribe to SMS Delivery Notifications request.
Example 21-5 OneAPI Subscribe to SMS Delivery Notifications Request
POST http://example.com/oneapi/1/smsmessaging/outbound/ tel%3A%2B5550100/subscriptions HTTP/1.1 Host: example.com:80 Content-Type: application/x-www-form-urlencoded Accept: application/json notifyURL=http://www.oracle.com& criteria="GIGPICS"& callbackData=doSomething()
Example 21-6 shows a sample OneAPI Subscribe to SMS Delivery Notifications response.
Example 21-6 OneAPI Subscribe to SMS Delivery Notifications Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/oneapip/1/smsmessaging/outbound/subscriptions/sub789
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"deliveryReceiptSubscription": {
"callbackReference": {
"callbackData": "doSomething()",
"notifyURL": " www.oracle.com ",
"criteria":"Urgent"
},
"resourceURL": " http://example.com/oneapi/1/smsmessaging/outbound/subscriptions/sub789 "}}
Example 21-7 shows a sample OneAPI SMS Delivery Notification message.
The Stop Subscription to Delivery 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 Subscribe to SMS Delivery Notification request.
There is no request or response body for the Stop Subscription to Delivery 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/oneapi/1/smsmessaging/outbound/subscriptions/subscriptionID
Where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the reference to the created subscription.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
Example 21-8 shows a sample OneAPI Stop Subscription to SMS Delivery Notifications request.
Example 21-8 OneAPI Stop Subscription to Deliver Notification Request
DELETE http://example.com/oneapi/1/smsmessaging/outbound/subscriptions/sub789 HTTP/1.1 Accept: application/json Host: example.com:80
Example 21-9 shows a sample OneAPI Stop Subscription to SMS Delivery Notifications response.
The OneAPI Retrieve Messages Sent to Web Application operation polls Services Gatekeeper for the SMS messages that have been received from the network for an application.
The request header for the Retrieve Messages SMS operation contains the registration identifier necessary to retrieve the SMS messages 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 that SMS messages have been received.
There is no request body.
If the Retrieve Messages Sent to Web Application 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/oneapi/1/smsmessaging/inbound/registrations/registrationID/messages?maxBatchSize=X
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
registrationId is the value previously set up to enable the application to receive notification that SMS messages have been received according to specified criteria.
The value of maxBatchSize is the maximum number of message to return.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The response body is an inboundSMSMessageList containing an array of structures as the value for inboundSMSMessage. The response body also contains the following parameters:
inboundSMSMessage: Array. Contains the following parameters:
dateTime: dateTime. The date and time when the message was received.
destinationAddress: String. The number or shortcode for the application.
messageID: String. A server generated message identifier.
message: String. The SMS message.
resourceURL: URL. Link to the message.
senderAddress: String. The MSISDN of the sender.
numberOfMessagesInThisBatch: Integer. The total number of messages in the batch.
resourceURL: URL Self-referring resource URL.
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:
"inboundSMSMessage": [
{ "dateTime": "dateTime",
"destinationAddress": "String",
"messageId": "String",
"message": "String",
"resourceURL": "URL",
"senderAddress": "String"},
Example 21-10 shows a sample OneAPI Retrieve Messages request.
Example 21-10 OneAPI Retrieve Messages Request
GET http://example.com/oneapi/1/smsmessaging/inbound/registrations/3456/messages?maxBatchSize=2 HTTP/1.1 Host: example.com:80 Accept: application/json
Example 21-11 shows a sample OneAPI Retrieve Messages response.
Example 21-11 OneAPI Retrieve Messages Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"inboundSMSMessageList": {
"inboundSMSMessage": [
{ "dateTime": "2009-11-19T12:00:00",
"destinationAddress": "3456",
"messageId": "msg1",
"message": "Let's Go Sharks!!",
"resourceURL": "http://example.com/oneapi/1/smsmessaging/inbound/registrations/3456/messages/msg1",
"senderAddress": "+15415550100"},
{ "dateTime": "2009-11-19T12:00:00",
"destinationAddress": "3456",
"messageId": "msg2",
"message": "Thorton Shoots! He Scores! Goal!",
"resourceURL": " http://example.com/oneapi/1/smsmessaging/inbound/registrations/3456/messages/msg2",
"senderAddress": "+15415550100"}
], "numberOfMessagesInThisBatch": "2",
"resourceURL": "http://example.com/oneapi/1/smsmessaging/inbound/registrations/3456/messages",
"totalNumberOfPendingMessages": "20"}}
The Subscribe to Notifications Sent to Application operation creates a subscription to delivery notifications for when an application receives a message.
To set up an application notification, provide the destinationAddress that will trigger notifications and a notifyURL for the delivery of the notifications. The destinationAddress is the MSISDN, or code set up in Services Gatekeeper, to which subscribers may send an SMS to your application.
If the subscription request is successful:
The response header contains the URI of the publish/subscribe server.
The response contains a resourceURL indicating the URI of the newly created subscription.
http://host:port/oneapi/1/smsmessaging/inbound/subscriptions
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The MIME-type for the Content-Type header field is application/x-www-form-urlencoded.
The request body for the subscription operation accepts the following parameters:
destinationAddress: String. The MSISDN, or code agreed upon by the operator, to which subscribers may send an SMS to your application.
notifyURL: URL. Is used by the server to POST the notifications to you, so include the URL of your own listener application.
criteria: String. Optional. Case-insensitive text to match against the first word of the message, ignoring any leading whitespace. This allows you to reuse a short code among various applications, each of which can register its own subscription with different criteria.
notificationFormat: Content Type. Optional. The content type in which notifications will be sent; for OneAPI only JSON is supported.
clientCorrelator: String. Optional. Uniquely identifies this create subscription request. If there is a communication failure during the request, using the same client correlator when retrying the request allows the operator to avoid creating a duplicate subscription.
callbackData: String. Optional. A function name or other data that you would like included when the POST is received.
The Location header field contains the URI of the publish/subscribe server:
http://host:port/oneapi/1/smsmessaging/inbound/subscriptions/subscriptionID
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the reference to the created subscription.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The response body contains a confirmation resourceReference JSON data structure consisting of the parameters supplied in the subscription request.
{"resourceReference": {"resourceURL": "URL"}}
The resourceURL indicates the URI of the newly created subscription.
Notification Data Object for Application Notification Message Sent to notifyURL
After a OneAPI Application Notification subscription is made, Services Gatekeeper delivers a message receipt notification to the specified notifyURL in the subscription request.
This nested JSON object contains the following parameters as the value of the attribute name inboundSMSMessageNotification:
callbackData: String. The correlator used to identify the notification.
inboundSMSMessage: Array. Contains the following parameters:
dateTime: dateTime. The date and time when the message was received.
destinationAddress: String. The number or shortcode for the application.
messageID: String. A server-generated message identifier.
message: String. The SMS message.
resourceURL: URL. A link to the message.
senderAddress: String. The MSISDN of the sender.
The notification data object delivered to the notifyURL address is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"inboundSMSMessageNotification": {
"callbackData": "String",
"inboundSMSMessage": {
"dateTime": "dateTime",
"destinationAddress": "String",
"messageId": "String",
"message": "String",
"senderAddress": "String"
}
}}
Example 21-12 shows a sample OneAPI Subscribe to Notifications of Messages Sent to Applications request.
Example 21-12 OneAPI Subscribe to Notifications of Messages Sent to Applications Request
POST http://example.com/oneapi/1/smsmessaging/inbound/subscriptions HTTP/1.1Host: example.com:80 Content-Type: application/x-www-form-urlencoded Accept: application/json destinationAddress=3456& notifyURL=http://www.yoururl.here/notifications/DeliveryInfoNotification& criteria=Vote& notificationFormat=JSON& callbackData=doSomething()& clientCorrelator=12345
Example 21-13 shows a sample OneAPI Subscribe to Notifications of Messages Sent to Applications response.
Example 21-13 OneAPI Subscribe to Notifications of Messages Sent to Application Response
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/oneapi/1/smsmessaging/inbound/subscriptions/sub678
Content-Length: 254
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"resourceReference": {"resourceURL": "http://example.com/oneapi/1/smsmessaging/inbound/subscriptions/sub678"}}
Example 21-14 shows a sample OneAPI Application Notification Message.
Example 21-14 OneAPI Application Notification Message
{"inboundSMSMessageNotification": {
"callbackData": "12345",
"inboundSMSMessage": {
"dateTime": "2009-11-19T12:00:00",
"destinationAddress": "3456",
"messageId": "mes1234",
"message": "Vote for Mega Boy Band",
"senderAddress": "+15415550100"
}
}}
The Stop Subscription to Application Message Notification operation terminates a previously set up application message notification subscription.
To stop a previously set up subscription, provide the correlator for the notification passed earlier in the Subscribe to Notifications of Messages Sent to Application request.
There is no request or response body for the Stop Subscription to Notifications of Messages Sent to Application 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/oneapi/1/smsmessaging/inbound/subscriptions/subscriptionID
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
subscriptionID is the reference to the created subscription.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. For more information, see "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
Example 21-15 shows a sample OneAPI Stop Subscription to Notifications of Messages Sent to Application request.
Example 21-15 OneAPI Stop Subscription to Notifications of Messages Sent to Application Request
DELETE http://example.com/oneapi/1/smsmessaging/inbound/subscriptions/sub123 HTTP/1.1 Accept: application/json Host: example.com:80
Example 21-16 shows a sample OneAPI Stop Subscription to Notifications of Messages Sent to Application response.