# RESTful Application Development Guide

# Short Messaging

## Operations

The RESTful Short Messaging interfaces allow an application to send an SMS, a ringtone, or a logo, and to fetch SMSs and delivery status reports for the application that have been received and stored on Oracle Communications Services Gatekeeper. They also allows an application to start and stop a notification.

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/sms/index.html` where host and port depend on the Oracle Communications Services Gatekeeper installation.

### Send Sms

Sends a text SMS

#### Request

##### URI

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

##### Request Content-Type

application/json

##### Body

`{`

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

`` `"message"``: "String",` <The message to be sent>

`"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]>

`},`

`"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`>`

`},`

`"senderName": "String"` <The sender of the SMS>

`}`

Note: | The request bodies for Send Sms, Send Sms Ringtone, and Send Sms Logo 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/sms/delivery-status/${result}”

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

The URI of the pub/sub server

#### Error Response

Policy Exception

Service Exception

### Send Sms Ringtone

Sends a ringtone

#### Request

##### URI

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

##### Request Content-Type

application/json

##### Body

`{`

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

`` "ringtone"`: "String",`<The ringtone data in RTX format>

`` "smsFormat"`: "Ems|SmartMessaging",`<The ringtone encoding>

`"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]>

`},`

`"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" <A` descriptive string to identify the type of receipt`>`

`},`

`"senderName": "String"`

`}`

##### 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/sms/delivery-status/${result}”

${result}: A string, the request identifier returned in the body

The URI of the pub/sub server

#### Error Response

Policy Exception

Service Exception

### Send Sms Logo

Sends a logo

#### Request

##### URI

`http://host:port/rest/sms/logos`

##### Request Content-Type

application/json

##### Body

`{`

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

`` `"image"``: "base64Binary",` <The logo data, base64 encoded image in gif, jpg, or png format>

`` `"smsFormat"``: "Ems|SmartMessaging",`<The logo encoding>

`"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]>

`},`

`"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"<A` descriptive string to identify the type of receipt`>`

`},`

`"senderName": "String"`

`}`

##### 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/sms/delivery-status/${result}”

${result}: A string, the request identifier returned in the body

The URI of the pub/sub server, for getting the delivery status

#### Error Response

Policy Exception

Service Exception

### Get Received Sms

Polls Oracle Communications Services Gatekeeper for SMSs for the application that have been received from the network

#### Request

##### URI

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

${registrationIdentifier}: A String that is set up with the off-line provisioning step that enables the application to receive notification of SMS reception according to specified criteria

##### HTTP Method

POST

#### Response

##### Response Content-Type

application/json

##### Body

`{"result": [{`

`` `"message"``: "String",`<The text of the SMS message>

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

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

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

`}]}`

#### Error Response

Policy Exception

Service Exception

### Get Sms Delivery Status

Gets the delivery status of a previously sent message

#### Request

##### URI

`http://host:port/rest/sms/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 SMS only if a callback reference was not defined (in the `receiptRequest` attribute of the input message) when the SMS was sent. If a callback reference was defined, Notify Sms 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"``: "DeliveredToNetwork|DeliveryUncertain|DeliveryImpossible|MessageWaiting|DeliveredToTerminal|DeliveryNotificationNotSupported"` <Possible status values: see Table 5-1>

`}]}`

Table 5-1 Enumeration values
Value | Meaning
--- | ---
`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.
`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 SMS-parts have been successfully delivered to the terminal.
`DeliveryNotificationNotSupported` | Unable to provide delivery receipt notification.

#### Error Response

Policy Exception

Service Exception

### Start Sms Notification

Starts a notification for the application

#### Request

##### URI

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

##### Request Content-Type

application/json

##### Body

`{`

`` `"reference"``: {`<Notification endpoint information>

`` `"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`>`

`},`

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

`"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/sms/notifications”

The URI of the pub-sub server

#### Error Response

Policy Exception

Service Exception

### Stop Sms Notification

Stops a notification for network-triggered messages in Oracle Communications Services Gatekeeper

#### Request

##### URI

`http://host:port/rest/sms/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

Policy Exception

Service Exception

## Notifications and Receipts

The content of notifications and receipts delivered to the designated endpoint

### Notify Sms Reception

`{"notifySmsReception": {`

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

`` `"message"``: {`

`` `"message"``: "String",`<The contents of the received SMS>

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

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

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

`}`

`}}`

### Notify Sms Delivery Receipt

`{"notifySmsDeliveryReceipt": {`

`` `"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 5-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"

}}