SMS Forwarding Service

Automating the Reception of MO-SMS and DLR for MT-SMS.

With the SMS Forwarding Server, MO-SMS messages and Delivery Reports (DLR) for MT-SMS are forwarded to a customer-specified HTTP REST endpoint as JSON objects. Once the customer endpoint acknowledges the receipt, the event is consumed and will not be resent again. The SMS Forwarding Service can be set up in the Connectivity Management Platform (CMP). Details on how to configure the HTTP endpoint URL can be found in the Getting Started guide.

REST Interface

The application server on the customer side needs to provide a REST Interface, which accepts HTTP PATCH/HTTP POST requests from the SMS Forwarding Service. For the SMS the HTTP POST method must be allowed and for the DLR the HTTP PATCH must be allowed to receive by the customers application. When an HTTP POST/HTTP PATCH request is successfully received, the server should reply with an HTTP 200 status code. This indicates that the forwarded event was received and will not be resent afterward. In case another HTTP status code is returned, the event will be repeated until it is successfully received or the 24-hour timeout is reached.

Endpoint URL

The provided endpoint URL in the CMP needs to be valid. URL with public IP addresses (https://<server-ip>:<port>/<endpoint>/) are not supported. Custom ports for the endpoint can be configured via the URL (https://<server-domain>:<port>/<endpoint>/).

Certificate

The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using Let's Encrypt certificates.

Warnings & Errors

A warning event record (HTTP 500) is written in the Data Streamer if an event delivery to the specified server was unsuccessful. In this case, verify that the endpoint is reachable and returns HTTP 200 to the incoming HTTP POST/HTTP PATCH request.

MO-SMS

The 1NCE SMS Forwarding Service offers the basic functionality to receive all MO-SMS messages from devices with 1NCE SIM in a uniform JSON format through a custom HTTP endpoint.

SMS Messages

MO-SMS originating from devices with a 1NCE SIM are delivered as JSON objects in a fixed format to the specified customer HTTP endpoint. An example of such a JSON Object is listed below:

{
    "multi_part_info": {
        "partno": 1,
        "total": 1,
        "identifier": 6202
    },
    "payload": "message text",
    "submit_date": "2018-08-17 16:31:51",
    "dest_address": "12345",
    "organisation": {
        "id": 4567
    },
    "pid": 0,
    "id": 6202,
    "endpoint": {
        "id": 8765432,
        "name": "8988280666000000037"
    },
    "source_address": "882285100000037",
    "dcs": 0
}

MT-SMS

Unlike the MO-SMS case, in the MT-SMS case the SMS Forwarding Service is not sending the SMS message itself to the application server. Instead, only the Delivery Report (DLR) is sent to the customer application. The DLR indicates the successful delivery of the MT-SMS using a 1NCE SIM card.

Delivery Reports

When a MT-SMS is sent to a device via the CMP or the 1NCE Management API, the SMS Forwarding Service provides a Delivery Report (DLR) in a JSON format. This notification report is sent once the MT-SMS was successfully received and confirmed by a device with 1NCE connectivity services. In order to receive the DLR on the setup HTTP endpoint, the server application must allow and accept HTTP HTTP PATCH requests. An example of a DLR JSON object sent towards an endpoint is shown below:

{
    "final_date": "2020-06-09 15:06:38",
    "id": 2819195,
    "submit_date": "2020-06-09 15:06:34",
    "organisation": {
        "id": 4567
    },
    "endpoint": {
        "name": "endpoint_name",
        "id": 8765432
    },
    "status": {
        "id": 4,
        "status": "DELIVERED"
    }
}

Testing SMS Forwarding

For demo and testing purposes, we recommend using a Postman Mock Server or a similar tool. Create a simple HTTP REST endpoint with a valid, not self-signed certificate that can consume HTTP POST requests and answers with HTTP 200. Once an SMS is sent from a device with a 1NCE SIM, the message will be forwarded to the server URL configured in the CMP.


Did this page help you?