The SMS Gateway service is configured in four sections:

At a high level, the SMS Gateway configuration can be visualised as:

  // General configuration options
  "routes": [
     // Outbound routes to send translated, built short messages.
  "correlation": {
     // Configuration for correlation document storage and retrieval.

General Configuration

The SMS Gateway’s general configuration options are as per the common application configuration parameters.

Route Configuration

Messages received from the JSLEE are processed through configured SMS Gateway routes in the order defined. Transformation and delivery is tried on each matching route’s destinations in order until either the matching routes are exhausted or the generated message (or all messages where segmentation occurs) are delivered.

Routes are examined for delivery in the order defined. The next route is examined if:

If all routes are exhausted, the SMS input is rejected with a temporary error.

The destination-addresses parameter creates a dependency for each route - the route will be disabled if there is not at least one instance of this address available and incoming traffic for delivery will not be advertised.

The following configuration options are available for each route in the SMS Gateway routes array:

Field Type Required? Default Description
name String No (generated) A reference name for this route. If not provided, will take the form <source name> -> <destination addresses, comma-separated>.
source-name String No - The service and endpoint name to match for this route, in the format <service name>/<endpoint name>. The endpoint name is not required, in which case all endpoints for the sending service will be matched. If this key is not specified at all, all sources will match.
source-message-type String No - The incoming message type to match for this route. The content of the message must be in JSON format and match the expected SMS input. Possible values are:
  • - a data value retrieved from Redis storage, generated by the JSLEE Redis service
destination-addresses Array (Strings) Yes - The service and endpoint name values to send matched messages for this route, in the format <service name>/<endpoint name>. The endpoint name is not required, in which case the receiving service will choose one. If this key is not specified at all, all message types will match. Delivery is attempted to the addresses listed here in the order defined. These addresses are also used when processing returned receipts.
receipt-addresses Array (Strings) No (empty) The service and endpoint name values to expect delivery receipts from for this route, in addition to the values in destination-addresses. These values are normally used when separate TX/RX connections are used to SMSCs.
destination-message-type String Yes - The outgoing message type to generate for this route. The available types are:
  • - an SMPP short message, sent via the JSLEE SMPP service
message-timeout-ms Integer No 30000 The number of milliseconds to wait for a response from the destination service. Once this expires, HA handling is invoked (if configured). This applies on a per-message-attempt basis. This timeout should always be higher than the largest expected timeout across all possible endpoint deliveries to avoid duplication.
correlation-key-override String No - A correlation key override to use when storing correlation information for this route.

An example routes configuration might be:

  "routes": [
      "destination-addresses": [ "smpp/endpoint1-1", "smpp2/endpoint1" ],
      "destination-message-type": "",
      "source-name": "redis/endpoint1",
      "source-message-type": "",
      "message-timeout-ms": 500
      "destination-addresses": [ "smpp/endpoint2" ],
      "destination-message-type": "",
      "smpp-encoding-set": "alternate"

Correlation Configuration

When translated messages are sent by the SMS Gateway, correlation information is produced in order to report message delivery information. Correlation documents provide information in JSON format on the received input, the sent short message, the received short message acceptance messages, the received delivery status message, and its response.

Correlation information may be kept in either or both of a local cache or an external persistent storage. When a delivery receipt is received, the previous correlation document is retrieved and updated with the delivery receipt’s details before being moved to a final location.

If no correlation configuration is provided, no correlation documents will be produced on message submission and no storage will be used when delivery receipts are received.

When storing correlation documents in Redis, the key used is normally in the format <service name>:[<endpoint name>:]<message ID>, where:

Correlation key overrides may also be specified in either or both route or additional correlation override configuration.

When storage-service is specified, it creates a dependency. If at least one instance of this service is not available, the SMS Gateway will not start nor process traffic; all routes will be disabled until this dependency (and any route dependencies) are satisfied.

The following correlation configuration options are available for the SMS Gateway:

Field Type Required? Default Description
cache-name String No - The configured cluster-wide map name (see below). If not specified, no caching will occur.
storage-service String Conditional - The configured service name of the JSLEE service to use for persistent storage.
storage-message-type String Conditional - The message type to generate for persistent storage. Available types are:
  • - store persistent correlation documents in Redis, using a SET command
storage-complete-name String Conditional - The protocol-specific destination identifier for persistent storage of correlation documents after their delivery receipt has been processed. When the storage-service used is Redis, this will be the Redis list to append to.
storage-expiry-duration Duration No - An ISO-8601 Duration to set as the initial expiry value for persistently-stored correlation documents. If not specified, documents will be created with no expiry.
error-on-correlation-failure Boolean No false Whether to indicate to the submitting service that an error occurred when storing correlation documents after SMS submission.
message-timeout-ms Long No 30000 The number of milliseconds to wait for a response from the storage service. Once this expires, HA handling is invoked (if configured). This applies on a per-message-attempt basis.
additional-correlation-key-overrides Object No - Additional correlation override configuration.

When specifying persistent storage, either all or none of storage-service, storage-message-type, and storage-complete-name must be specified.

An example correlation section configuration might be:

"correlation": {
  "cache-name": "smsgw",
  "storage-service": "redis",
  "storage-expiry-duration": "P1H",
  "storage-message-type": "",
  "storage-complete-name": "complete",
  "error-on-correlation-failure": true,
  "message-timeout-ms": 10000

When the cache-name parameter is specified , the cache will only be active if it is also configured in the JSLEE Hazelcast configurationm, e.g.:

    <map name="smsgw">
        <max-size policy="PER_NODE">5000</max-size>

For more information on these parameters, refer to the Hazelcast Map documentation. Entries that are found in the cache will not be retrieved from persistent storage as part of correlation processing.

Correlation Override

Instead of using the correlation key defaults when storing or retrieving correlation documents from the cache and/or persistent storage, override values may be used to group logical entities together. When an override is used, the key used becomes <correlation override>:<message ID> instead of using the service and endpoint.

Overrides may be defined at the routes level for use when sending messages, and additional overrides can be specified in the correlation section as required, e.g. when a custom high availability setup is used. Additional correlation key overrides are specified as:

        "correlation": {
            "additional-correlation-key-overrides": {
                "<override key>": [

The addresses used for each key are as defined in route configuration.

Note that, in order to prevent unexpected correlation overrides being applied, the SMS Gateway does not allow: