| 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 Multimedia Messaging interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Multimedia Messaging interface to send a multimedia message (MMS) and to fetch information on MMSes that have been received for the applications and stored on Services Gatekeeper.
They use the interface to fetch those messages, get delivery status on sent messages, and start and stop a notification.
The actual message is sent as an attachment. See "Headers for Multipart Messages with Attachments" for more information.
In order for an application to be informed of an MMS that has been received for a party or a delivery receipt for a message sent, the application includes an application endpoint address for such delivery notifications in the body of the request message. This address resides on a publish/subscribe server. For more information, 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/multimedia_messaging/index.html
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The Send Message operation delivers a multimedia message.
To send a multimedia (MMS) message, provide the SIP-formatted URI of the addresses which the 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 and the SIP formatted URI address of the sender. Also, a priority value, and a subject line can be provided in the request body.
If the Send Message operation successful, the response header will contain the URI of the pub-sub server and the request identifier which is also provided in the response body for this operation.
http://host:port/rest/multimedia_messaging/messages
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request headers depend on the type of message:
If the message content is in the form of an attachment, the request will be multipart and therefore, the request header must contain the header fields that describe the parts of the message.
If the message does not contain an attachment, the special headers associated with the multipart messaged are not used.
See Example 8-1 for a listing of both types of headers.
The Message Part Content for the Send Message operation accepts the following parameters:
addresses. Array of string values. Required. The set of addresses of the recipients as an array of URIs.
subject. String. Optional. The text of the message.
priority. String. Optional. The message priority specified as one of the following:
Default
Low
Normal
High
senderAddress. String. Optional. The sender's address (URI).
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 Message request, Services Gatekeeper will invoke Notify Message Delivery Receipt and discard the delivery status information.
endpoint. String. The endpoint address (URI) to which the receipt must be delivered, a Bayeux protocol channel name that is the client application's application instance account ID.
interfaceName. String. Required. A description provided to identify the type of receipt.
The Message Part Content 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"],
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
},
"priority": "Default|Low|Normal|High",
"receiptRequest": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"senderAddress": "String",
"subject": "String"
}
The Location header field contains the URI of the publish/subscribe server as:
http://host:port/rest/multimedia_messaging/delivery_status/result
where, result is the string identifier for the request that is 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 returned in the Location header field of the response message as value for result.
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"}
Example 8-1 Send Message Requests
This section contains two examples. The first example shows a POST method with a message.
POST /rest/multimedia_messaging/messages HTTP/1.1
X-Session-ID: app:-7603991555266551180
Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host: localhost:8001
Content-Length: 253
Content-Type: application/json
{
"addresses":["tel:8765","tel:7654","tel:6543"],
"subject":"Meeting starts at 2 p.m.",
"priority":null,
"senderAddress":"tel:1234",
"charging":null
"receiptRequest":
{
"correlator":"981234",
"endpoint":"http://10.182.100.229:13444/jaxws/MessageNotification",
"interfaceName":"interfaceName",
}
}
The second example shows a POST method with a multipart message. Note the use of header fields to describe the content and the boundary attribute to distinguish the message parts.
POST /rest/multimedia_messaging/messages HTTP/1.1
X-Session-ID: app: -123456789012346789
Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host: localhost:8001
Content-Length: 1215
Content-Type: multipart/form-data; boundary=kboiiFPAakDPYKeY7hBAW9I5c0rT48
--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="messagePart"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit
{
"addresses":["tel:8765","tel:7654","tel:6543"],
"subject":"Hello World",
"priority":null,
"senderAddress":"tel:1234",
"charging":null,
"receiptRequest":
{
"correlator":"981234",
"endpoint":"http://10.182.100.229:13444/jaxws/MessageNotification",
"interfaceName":"interfaceName"
}
}
--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="Attachment-txt-1"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Oracle Communications Services Gatekeeper is a powerful, flexible, secure interface which provides a simple way for application developers to include telephony-based functionality in their software applications and guarantee the security, stability, and performance required by network operators and demanded by their subscribers.
--kboiiFPAakDPYKeY7hBAW9I5c0rT48
The Get Received Messages operation retrieves an array of network-triggered messages that have arrived at Services Gatekeeper.
The request body for Get Received Messages contains the registration identifier necessary to retrieve the required MMSs intended for the application and, optionally, it may also contain a priority for the retrieval. The registration identifier should have been set up with the off-line provisioning step completed earlier.
If the Get Received Messages operation is successful, the response body will contain the data about the message. If the content of the message is pure ASCII, the response body contains the message. Otherwise the response body contains an identifier that is used to fetch the actual message.
http://host:port/rest/multimedia_messaging/receive-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 Get Received Messages operation accepts the following parameters:
registrationIdentifier. String. Required. The value previously set up to enable the application to receive notification of MMS reception according to specified criteria.
For more information on provisioning offline notifications, see "Managing and Configuring Multimedia Messaging Communication" in the Oracle Communications Services Gatekeeper System Administrator's Guide, another document in this document set.
priority. String. Optional. The message priority specified as one of the following:
Default
Low
Normal
High
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:
{
"registrationIdentifier": "String",
"priority": "Default|Low|Normal|High"
}
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.
messageServiceActivationNumber. String. The number associated with the invoked Message service, that is the destination address used to send the message.
priority. String. The message priority value from the request.
senderAddress. String. The SIP-formatted URI of the sender.
dateTime. String. The start time for the call in ISO 8601 extended format yyyy-mm-ddThh-mm-ss.
message. String. Present if the text of the message is purely ASCII text.
messageIdentifier. String. An identifier used to fetch the message, when it is not purely ASCII text. This value is used in the URI of the request for the "Get Message" operation.
subject. String. The subject line of the multimedia message.
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": [{
"messageServiceActivationNumber": "String",
"priority": "Default|Low|Normal|High",
"senderAddress": "URI",
"dateTime": "Calendar",
"message": "String",
"messageIdentifier": "String",
"subject": "String"
}]}
The Get Message operation fetches a network-triggered message for the application from Services Gatekeeper.
To get a message, provide the appropriate message identifier in the URI for the GET method.
The actual message is returned as an attachment.
http://host:port/rest/multimedia_messaging/message/${messageRefIdentifier}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
messageRefIdentifier is the value for messageIdentifier in:
the response body of the "Get Received Messages" operation
notifyMessageReception data object. See "Notification Data Object for Message Reception (notifyMessageReception)"
The MIME-type for the Content-Type header field is multipart/mixed.
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 Get Message Delivery Status operation retrieves the delivery status of a previously sent message.
This operation is valid only if the correlator callback reference was not defined in the receiptRequest attribute of the initial request to send the MMS message. In such a scenario, Services Gatekeeper stores the delivery status for a configurable period of time. (If the callback reference correlator is defined in the receiptRequest attribute of the initial request to send the MMS message, Services Gatekeeper will invoke the Notify Message Delivery Receipt operation and discard the delivery status information.)
The request header for the Get Message Delivery Status operation contains the request identifier from result object of the initial request.
If the Get Message Delivery Status operation is successful, the response body will contain the SIP-formatted URI from the address field in the Send Message request and corresponding delivery status for the message.
http://host:port/rest/multimedia_messaging/delivery_status/${requestIdentifier}
where:
host and port are the host name and port of the machine on which Services Gatekeeper is installed.
requestIdentifier is a string returned in the result object of the initial Send Message request.
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 8-1 lists the possible statuses:
Table 8-1 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to network. In case of concatenated messages, only when all the MMS-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. |
|
MessageWaiting |
The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states. |
|
DeliveredToTerminal |
Successful delivery to terminal. In case of concatenated messages, only when all the MMS-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": "DeliveredToTerminal|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToNetwork|DeliveryNotificationNotSupported"
}]}
The Start Message Notification operation starts a notification for the application.
To set up a multimedia message 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 MMS 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 Message 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 application receives such a response, it must access the endpoint address to retrieve the specific call event notifications.
http://host:port/rest/multimedia_messaging/notification
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:
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.
messageServiceActivationNumber. String. Required. The number associated with the invoked Message service, that is the destination address used to send the message
criteria. String. Optional. The text to match against in determining whether or not the application should receive the notification:
notifyMessageReception
notifyMessageDeliveryReceipt
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:
{
"messageServiceActivationNumber": "URI",
"reference": {
"correlator": "String",
"endpoint": "URI",
"interfaceName": "String"
},
"criteria": "String"
}
The Location header field contains the URI of the publish/subscribe server:
http://host:port/rest/multimedia_messaging/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 Message Reception (notifyMessageReception)
When a multimedia message is successfully retrieved by the called party and the value for criteria in the request body is notifyMessageReception, 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 notifyMessageReception:
correlator. String. The correlator used to identify the notification.
message. Nested JSON object. It contains the following:
message. String. The contents of the multimedia message.
senderAddress. String. The SIP-formatted URI of the sender of the multimedia message.
smsServiceActivationNumber. String. The number associated with the invoked Message service, that is the destination address used to send the message.
dateTime. String. 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 notifyMessageReception is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"notifyMessageReception": {
"correlator": "String",
"message": {
"messageServiceActivationNumber": "String",
"priority": "Default|Low|Normal|High",
"senderAddress": "URI",
"dateTime": "Calendar",
"message": "String",
"messageIdentifier": "String",
"subject": "String"
}
}}
Notification Data Object for MMS Delivery Receipt (notifyMessageDeliveryReceipt)
When a multimedia message is successfully retrieved by the called party and the value for criteria in the request body is notifyMessageDeliveryReceipt, 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 notifyMessageDeliveryReceipt:
correlator. String. The correlator used to identify the notification.
deliveryStatus. Enumeration value. Table 8-2 lists the possible statuses:
Table 8-2 Enumeration Values for Delivery Status
| Value | Description |
|---|---|
|
DeliveredToNetwork |
Successful delivery to network. In case of concatenated messages, only when all the MMS-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 MMS-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 notifyMessageDeliveryRecipt is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{"notifyMessageDeliveryReceipt": {
"correlator": "String",
"deliveryStatus": {
"address": "URI",
"deliveryStatus": "DeliveredToTerminal|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToNetwork|DeliveryNotificationNotSupported"
}
}}
The Stop Message Notification operation terminates a previously set up multimedia message notification for the application.
To stop a previously set up MMS notification, provide the correlator for the notification passed earlier in the Start Message Notification request.
There is no request or response body for the Stop Message 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/multimedia_messaging/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 Message Notification 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".
|
 Copyright © 2007, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|