# Communication Service Reference

# Parlay X 2.1 Short Messaging Communication Service

This chapter describes the Parlay X 2.1 Short Messaging communication service in detail:

- An Overview of the Parlay X 2.1 Short Messaging Communication Service

- Processing Application-initiated Requests
- Processing Network-triggered Requests
- Supported Network Protocols
- Short Code Translation

- Configuration Specifics for the Parlay X 2.1 Short Messaging Communication Service

- Charging Data Records
- Event Data
- Statistics
- Supported Address Schemes

## An Overview of the Parlay X 2.1 Short Messaging Communication Service

The SOAP Service Facade Short Messaging communication service implements the Parlay X 2.1 Short Messaging set of interfaces. For the exact version of the standard this communication service supports, see “Appendix A: Standards and Specifications” in Concepts and Architectural Overview, another document in this set.

Note: | The RESTful Service Facade Short Messaging interfaces provide RESTful access to this same functionality. The internal representations are identical, and for the purposes of creating SLAs and reading CDRs, etc., they are the same.

Using a Short Messaging communication service, an application can:

- Send short messages to one or many destination addresses. The payload in these short messages can be text, logos, or ringtones

Note: | Logos must be in either SmartMessaging or EMS format. The image is not scaled. Ringtones must be in either SmartMessaging or EMS (iMelody) format.

- Ask to be notified that delivery receipts for sent short messages have been received from the network
- Receive delivery receipts on sent short messages that have arrived from the network
- Explicitly query Oracle Communications Services Gatekeeper for delivery receipts on sent short messages
- Sign up to be notified if specified short messages for the application have been received from the network
- Receive notifications that specified short messages for the application have arrived from the network. These notifications include the short message payload
- Explicitly poll Oracle Communications Services Gatekeeper for short messages sent to the application that have arrived from the network and been stored in Oracle Communications Services Gatekeeper

Requests can flow in two directions using the Parlay X 2.1 Short Messaging communication service: from the application to the network (called application-initiated or mobile terminated) and from the network to the application (called network-triggered or mobile originated). Both of these scenarios are covered below.

### Processing Application-initiated Requests

After an application has sent a short message to one or more destination addresses, two different types of responses can be returned:

- Send Receipts
- Delivery Receipts

#### Send Receipts

Send receipts are merely acknowledgements that the network node has received the short message from the application by means of Oracle Communications Services Gatekeeper. Although a single short message may be sent to multiple destination addresses, normally only one send receipt is returned to the application by Oracle Communications Services Gatekeeper. The receipt is returned synchronously in the response message to the `sendSms` operation.

#### Delivery Receipts

Delivery receipts contain the delivery status of the short message; that is, whether the short message has actually been delivered by the network to the mobile terminal. There is one delivery receipt per destination address, with one of three possible states:

- Successful. In the case of concatenated short messages, this is returned only when all the parts have been successfully delivered. (see the Note below)
- Unsuccessful. The short message could not be delivered before it expired.
- Delivery notification for this address is not supported. This can occur if the originating network supports delivery receipts but is unable to acquire the appropriate information for one or more destination addresses. This status is reported for each address for which this is the case.

Because actual delivery of the short message may take several hours, or even days (if, for example, the mobile terminal is turned off at the time the short message is sent), delivery receipts are returned asynchronously. Applications can either choose to have delivery receipts delivered to them automatically by supplying Oracle Communications Services Gatekeeper with a callback interface or they can chose to poll Oracle Communications Services Gatekeeper.

If the application supplies a callback interface, there are two possible outcomes:

- Oracle Communications Services Gatekeeper sends the delivery receipt and the application receives and acknowledges it
- Oracle Communications Services Gatekeeper sends the delivery receipt but the application does not acknowledge reception. In this case, Oracle Communications Services Gatekeeper stores the delivery receipt in a reliable storage. The application can poll Oracle Communications Services Gatekeeper for these receipts. Each stored delivery receipt is timestamped and, after a configurable time period, is removed.

If the application chooses not to supply a callback interface, Oracle Communications Services Gatekeeper stores the delivery receipt in reliable storage. The application can poll Oracle Communications Services Gatekeeper for these receipts. Each stored delivery receipt is timestamped and, after a configurable time period, is removed.

To correlate a sent message with a delivery receipt form the network node, information about the message is stored in Gatekeeper for a period of time. This information has a lifespan. If the delivery receipt does not arrive prior to the expiration of the message, a cancel request for the message is sent to the SMSC.

Note: | The Short Messaging communication service does not put any limitation on the size of the payload in a short message. If the network protocol used restricts the size of the payload, Oracle Communications Services Gatekeeper splits the short message into appropriately sized parts.

### Processing Network-triggered Requests

Two sorts of traffic destined for an application can arrive at Oracle Communications Services Gatekeeper from the network, including:

- Delivery receipts for application-initiated sent short messages (see “Delivery Receipts”).
- Mobile-originated short messages destined for the application

In order for an application to receive short messages from the network, it must register its interest in these short messages by setting up a subscription in Oracle Communications Services Gatekeeper. A subscription, or notification, is defined by a Service Activation Number, the destination address to which the mobile sender directs the short message. This is usually a Short Code.

Additional criteria can be tied to the Service Activation Number, such as the first word of the text in the short message payload. For Oracle Communications Services Gatekeeper to accept a message, both the Service Activation Number and the additional criteria must match the details set up in the subscription. Each registered subscription must be unique, and subscription attempts with overlapping criteria are rejected. The application may choose either to poll Oracle Communications Services Gatekeeper for received short messages or it may include a callback interface in setting up the original subscription.

If a short message that matches a subscription arrives at Oracle Communications Services Gatekeeper from the network and the original subscription includes a call-back interface, there are two possible results:

- Oracle Communications Services Gatekeeper sends the short message to the application, and the application receives and acknowledges it. In this case Oracle Communications Services Gatekeeper simply acknowledges the reception of the short message to the network.
- Oracle Communications Services Gatekeeper sends the short message on to the application, but the application does not acknowledge reception. In this case, Oracle Communications Services Gatekeeper can store the short message in reliable storage, if offline provisioning has occurred and a `registrationIdentifier` has been established. In such a case, Oracle Communications Services Gatekeeper acknowledges the reception of the short message to the network. If no provisioning has been done, Oracle Communications Services Gatekeeper returns an error to the network. The application can poll Oracle Communications Services Gatekeeper for any stored short messages. Messages are removed after the polling application has had the chance to consume them. Each stored short message is timestamped and, after a configurable time period, is removed from the storage.

If a short message that matches a subscription arrives at Oracle Communications Services Gatekeeper, and the original subscription does not include a callback interface, the short message is stored in reliable storage and Oracle Communications Services Gatekeeper acknowledges the reception of the short message to the network. The application can poll Oracle Communications Services Gatekeeper for any such short messages. Each stored short message is timestamped and, after a configurable time period, is removed.

If a short message arrives at Oracle Communications Services Gatekeeper and no matching subscription is found, Oracle Communications Services Gatekeeper does not acknowledge reception to the network. It is the responsibility of the network node to handle any further processing of the short message.

Note: | The Short Messaging communication services do not put any limitations on the size of the payload in a message. If the network protocol used restricts the size of the payload, Oracle Communications Services Gatekeeper can concatenate short message segments into one single short message before delivering it to an application. If configured to concatenate segments, it is also configurable whether to deliver parts of the message to the application regardless if all segments have arrived to Oracle Communications Services Gatekeeper or not, and after which time period the segments are considered as lost and the message is propagated to the application.

### Multiple Connections and Multiple Plug-in Instances

The SMPP plug-in for Parlay X 2.1 Short Messaging can bind as an ESME transmitter/receiver or transceiver towards an SMSC. If more than one account in the SMPP SMSC is used, create one plug-in instance for each account. If more than one SMSC is used, create a plug-in instance for each account in each of the SMSCs.

Each plug-in instance can establish a set of connections (binds) towards an SMSC. If the SMSC has a throughput limit per connection, configure the number of connections to use to meet the required overall throughput requirements. On plug-in instance level, it is possible to specify the maximum allowed number of unacknowledged SMPP operations per connection. This setting can be used to protect the SMSC from overload.

Each plug-in instance executes on all Network Tier servers and a shared storage is used, so network-triggered messages and delivery notifications can be accepted by all Network Tier servers and match them with all application subscriptions and thus create a robust configuration with high availability.

### Supported Network Protocols

Off the shelf, the Short Messaging communication service can be configured to support the following network protocol:

- SMPP v3.4

#### SMPP v3.4

When Oracle Communications Services Gatekeeper is configured to use this protocol, it connects to an SMSC using SMPP v3.4. See “Appendix A: Standards and Specifications” in Concepts and Architectural Overview for the exact version of the standard Oracle Communications Services Gatekeeper supports. See System Administrator’s Guide for a description of how the plug-in connects to an SMPP v.3.4 compliant SMSC.

Note: | The SMPP protocol expects the sender name value to be in ASCII characters. The use of non-ASCII characters may cause the request to become garbled or even to be removed at the SMSC.

### Short Code Translation

A common feature of messaging-capable networks is the use of short codes and message prefixes to help route traffic and to make access to certain features easier for the end user. Instead of having to use the entire address, users can enter shorter sequences when they dial, which are then mapped to the full address in the network. The Parlay X 2.1 Short Messaging to SMPP communication service supports short codes and message prefixes, which allow the same short code to be mapped to multiple addresses, based on what is prepended to the enclosed message.

Examples include:

Short message sent to 1243 with the first word in the message being WEATHER routes the message to an application that provides a weather service.

Short message sent to 4567 with the first word in the message being NEWS routes the message to an application that provides a news service.

## Configuration Specifics for the Parlay X 2.1 Short Messaging Communication Service

Communication services share many common features, covered in “Introducing Communication Services” in Concepts and Architectural Overview, but each one has a few characteristics that are specific only to that service. This section describes those specific features for the Parlay X 2.1 Short Messaging communication service, including:

- Charging Data Records
- Event Data
- Statistics

### Charging Data Records

#### Generation of CDRs

There are three Short Messaging/SMPP-specific CDRs. They occur when the following criteria are met:

- After a `sendSms` is sent from Oracle Communications Services Gatekeeper to the network, using either plug-in
- After a `reportNotification` is sent from the network to Oracle Communications Services Gatekeeper, indicating that a delivery receipt has been returned for the application, using either plug-in
- When a mobile-originated message has been successfully delivered to the application

### Event Data

Table 7-1 lists EDR IDs created by the Short Messaging/SMPP communication service. This list does not include EDRs created when exceptions are thrown. For more information, see Events, Alarms, and Charging.

Table 7-1 Event types emitted in the Short Messaging/SMPP communication service
EdrId | Method Called
--- | ---
6000 | notifySmsDeliveryReceipt
6001 | notifiySmsReception
7000 | sendSms
7001 | sendSmsLogo
7002 | sendSmsRingtone
7003 | startSmsNotification
7004 | stopSmsNotification
7005 | sendSubmit
7006 | receivedSMSDeliveryReport
7007 | receivedMobileOriginatedSMS
7008 | sendDeliverSMResp
7009 | sendSubmitMulti
7010 | sendCancel

### Statistics

Table 7-2 outlines the correlation between the methods being invoked from either the application (in application-initiated requests) or the telecom network (in network-initiated requests) and the transaction type collected by the statistics counters in Oracle Communications Services Gatekeeper for the Parlay X 2.1 Short Messaging/SMPP communication service:

Note: | Method names for network-initiated requests are specified by the internal Gatekeeper name, which is not necessarily the same as the message from the network.

Table 7-2 Transaction types for Parlay X 2.1 Short Messaging communication service
Method | Transaction type
--- | ---
sendSms | TRANSACTION_TYPE_MESSAGING_SEND
sendSmsLogo | TRANSACTION_TYPE_MESSAGING_SEND
sendSmsRingtone | TRANSACTION_TYPE_MESSAGING_SEND
receivedMobileOriginatedSMS | TRANSACTION_TYPE_MESSAGING_RECEIVE

### Supported Address Schemes

The Parlay X 2.1 Short Messaging/SMPP communication service supports the`tel:` address scheme.