# RESTful Application Development Guide

# Multimedia Messaging

## Operations

The RESTful Multimedia Messaging interfaces allow an application to send an MMS and to fetch information on MMSs for the application that have been received and stored on Oracle Communications Services Gatekeeper. They allow the application to fetch those messages. The application can also get delivery status on sent messages, and start and stop a notification.

Note: | The actual message is sent as an attachment. See Attachments for more information.

In the listings below, bold indicates a required attribute, <> a descriptive comment.

Note: | An HTML version of this information is at `http://host:port/rest/multimedia_messaging/index.html` where host and port depend on the Oracle Communications Services Gatekeeper installation.

### Send Message

Sends a multimedia message

#### Request

##### URI

`http://host:port/rest/multimedia_messaging/messages`

##### Request Content-Type

multipart/form-data

##### Message Part Name

messagePart

##### Message Part Content-Type

application/json

##### Message Part Content

{

`` `"addresses"``: ["URI"],`<The recipient(s)>

`"charging": {`<This entire attribute is optional>

`` `"description"``: "String",`<Text to be used for information and billing>

`"amount": "BigDecimal",`<The amount to be charged>

`"code": "String",`<A charging code, from an existing contractual description>

`"currency": "String"`<A currency identifier as defined in ISO 4217 [9]>

`},`

`"priority": "Default|Low|Normal|High",` <The message priority>

`"receiptRequest": {`<This entire attribute is optional>

`` `"correlator"``: "String",<`A correlator used to connect the receipt to the inital message>

`` `"endpoint"``: "URI",`<The endpoint address to which the receipt should be delivered>

`` `"interfaceName"``: "String"<`Descriptive only, a string to identify the type of receipt`>`

`},`

`"senderAddress": "String",`<The sender of the MMS>

`"subject": "String"` <The subject line of the MMS>

`}`

Note: | The request bodies for Send Message may contain a `receiptRequest` attribute in the input message. This is a way of requesting a delivery receipt for the message being sent, and it includes an application endpoint for returning the delivery notification. Currently it is possible to specify either a SOAP (a Web Service implemented by the application) endpoint or a RESTful endpoint (a channel beginning with “/bayeux/${appInstanceId}”). Specifying a SOAP endpoint for a notification for a message sent using RESTful interfaces, however, works only if the SOAP and RESTful interfaces reside in the same cluster. For more information on channels, see Notifications and Publish/Subscribe.

##### HTTP Method

POST

#### Response

##### Response Content-Type

application/json

##### Body

`{``"result"``: "String"}`

The request identifier, a string used to identify the request for later correlation

##### Header

key= “Location” value = host:port/rest/multimedia_messaging/delivery-status/${result}”

${result}: The request identifier returned in the body

The URI of the pub/sub server

#### Error Response

Service Exception

Policy Exception

### Get Received Messages

Retrieves an array of network-triggered messages for the application that have arrived at Oracle Communications Services Gatekeeper. If the content of the messages is pure ASCII, the response body contains the message. Otherwise the response body contains an identifier that can be used to fetch the actual message.

#### Request

##### URI

`http://host:port/rest/multimedia_messaging/receive-messages`

##### Request Content-Type

application/json

##### Body

`{`

`` `"registrationIdentifier"``: "String", <`A String that is set up with the off-line provisioning step that enables the application to receive notification of MMS reception according to specified criteria>a

`"priority": "Default|Low|Normal|High"` <The priority of the messages to poll for. All messages of the specified priority and higher will be retrieved. The default value is the same as Low: all messages are returned.>

`}`

##### HTTP Method

POST

#### Response

##### Response Content-Type

application/json

##### Body

`{"result": [{`

`` `"messageServiceActivationNumber"``: "String",`<The number associated with the invoked Message service, that is the destination address used to send the message>

`` `"priority"``: "Default|Low|Normal|High",`<The message priority>

`` `"senderAddress"``: "URI",` <The sender of the message>

`"dateTime": "Calendar",`<The time the message was sent in ISO 8601 extended format >``

`"message": "String",`<The text of the message, if the message is purely ASCII text>

`"messageIdentifier": "String",`<An identifer used for fetching the message if it is not pure ASCII text>

`"subject": "String"`<The subject line of the MMS>

`}]}`

#### Error Response

Service Exception

Policy Exception

### Get Message

Fetches a network-triggered message for the application from Oracle Communications Services Gatekeeper. The actual message is returned as an attachment.

#### Request

##### URI

`http://host:port/rest/multimedia_messaging/message/${messageRefIdentifier}`

${messageRefIdentifier}: A string, the message identifier from Get Received Messages or a Notify Message Reception.

##### HTTP Method

GET

#### Response

##### Response Content-Type

multipart/mixed

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

### Get Message Delivery Status

Gets the delivery status of a previously sent message

#### Request

##### URI

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

${requestIdentifier}: The identifier returned in the result object of the initial request

##### HTTP Method

GET

Note: | It is possible to query the delivery status of an MMS only if a callback reference was not defined (in the `receiptRequest` attribute of the input message) when the MMS was sent. If a callback reference was defined, Notify Message Delivery Receipt is invoked by Oracle Communications Services Gatekeeper and the delivery status is not stored. If the delivery status is stored in Oracle Communications Services Gatekeeper, it is stored for a configurable period of time.

#### Response

##### Response Content-Type

application/json

##### Body

`{"result": [{`<This is an optional attribute>

`` `"address"``: "URI",`<The address to which the initial message was sent>

`` `"deliveryStatus"``: "DeliveredToTerminal|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToNetwork|DeliveryNotificationNotSupported"` <Possible status values: see `Table 6-1``>`

`}]}`

Table 6-1 Enumeration values
Value | Meaning
--- | ---
`DeliveredToNetwork` | Successful delivery to network enabler responsible for distributing the message further in 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.
`DeliveryNotificationNotSupported` | Unable to provide delivery receipt notification.

#### Error Response

Service Exception

Policy Exception

### Start MMS Notification

Starts a notification for the application

#### Request

##### URI

`http://host:port/rest/multimedia_mesaging/notification`

##### Request Context-Type

application/json

##### Body

`{`

`` `"messageServiceActivationNumber"``: "URI",` <The number associated with the invoked Message service, that is the destination address used to send the message>

`` `"reference"``: {`

`` `"correlator"``: "String",<`A correlator used to identify the notification>

`` `"endpoint"``: "URI",`<The endpoint address to which the notification should be delivered>

`` `"interfaceName"``: "String"<A` descriptive string to identify the type of notification`>`

`},`

"criteria": "String" <Text to match against in determining whether or not the application should receive the notification>

}

##### HTTP Method

PUT

#### Response

Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications and Receipts.

##### Header

key= “Location” value = host:port/rest/multimedia_messaging/notifications”

The URI of the pub-sub server

#### Error Response

Service Exception

Policy Exception

### Stop Message Notification

Stops a notification for the application

#### Request

##### URI

`http://host:port/rest/multimedia_messaging/notification/${correlator)`

${correlator}: A string, the correlator that identifies the notification, passed in with the initial start notification request

##### HTTP Method

DELETE

#### Response

Empty

#### Error Response

Service Exception

Policy Exception

## Notifications and Receipts

The content of notifications and receipts delivered to the designated endpoint

#### Notify Message Reception

`{"notifyMessageReception": {`

`` `"correlator"``: "String",<`A correlator used to identify the notification>

`` `"message"``: {`

`` `"messageServiceActivationNumber"``: "String",`<The number associated with the invoked Message service, that is the destination address used to send the message>

`` `"priority"``: "Default|Low|Normal|High",`<The message priority>

`` `"senderAddress"``: "URI",` <The sender of the MMS>

`"dateTime": "Calendar",`<The time the message was sent in ISO 8601 extended format >

`"message": "String",`<The text of the message, if the message is purely ASCII text>

`"messageIdentifier": "String",`<An identifer used for fetching the message if it is not pure ASCII text>

`"subject": "String"` <The subject line of the MMS>

`}`

`}}`

#### Notify Message Delivery Receipt

`{"notifyMessageDeliveryReceipt": {`

`` `"correlator"``: "String",<`A correlator used to connect the receipt to the inital message>

`` `"deliveryStatus"``: {`

`` `"address"``: "URI",`<The recipient of the initial message>

`` `"deliveryStatus"``: "DeliveredToNetwork|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToTerminal|DeliveryNotificationNotSupported"` <Possible status values: see Table 6-1>

`}`

`}}`

## Errors

The content of possible error messages.

### Service Exception

{`"error"`:{

`"type":`"org.csapi.schema.parlayx.common.v2_1.ServiceException"

`"message"`:"String"

}}

### Policy Exception

{`"error"`:{

`"type"`:"org.csapi.schema.parlayx.common.v2_1.PolicyException"

`"message"`:"String"

}}