Callbacks

SMS callbacks

Receive MO SMS via API callback.

The system can dispatch mobile originated (MO) SMS from endpoints as HTTP POST requests toward a user-configurable URL. The URL of the receiving server needs to be specified in a service profile that the endpoint has assigned. The emnify system then sends the MO SMS as a JSON payload if the destination address of the SMS is an invalid MSISDN (that is, 7 digits or less).

Example service profile with an API callback URL and API secret:

1{
2   "organisation_id": "1337",
3   "name": "SMS MO Callback",
4   "description": "This service profile demonstrates the API callback URL and signing key",
5   // Application server URL
6   "api_callback": {
7      "organisation_id": "1337",
8      "url": "http://my-application-server.io",
9      "created": "2019-10-11 08:54:20",
10      "purpose": "Receiving SMS-MO",
11      "id": 12
12   },
13   // This secret is used to sign the JWT included in the Authorization header of callbacks.
14   // These secrets should be kept securely as they are used to validate the authenticity of incoming POST requests to your callback URL.
15   // Note: API secrets may be created (POST) and retrieved (GET) via /api/v1/api_secret
16   "api_secret":{
17      "organisation_id":"1337",
18      "purpose":"Custom Signing Key",
19      "id":123
20   },
21  // ...
22}

The application server receiving the API callback needs to respond with HTTP Code 2XX to accept the request.

API callback secret

If an API secret is provided in the service profile, callbacks using this URL contain an Authorization header with a JSON Web Token (JWT) included. The api_secret is used as the signing key of the JWT in this header.

API callback auth header:

1{
2  "Authorization": "Bearer JWT_SIGNED_WITH_API_SECRET"
3}

By verifying the signing key of the JWT, your server can ensure the request is coming from emnify. If no api_secret exists in the service profile, the request won’t contain an Authorization header.

Example request body sent to API callback URL:

1{
2   "submit_date": "2019-10-29 10:36:01",
3   "dcs": 0,
4   "pid": 0,
5   "organisation": {
6      "id": "1337"
7   },
8   "multi_part_info": {
9      "identifier": 20426339,
10      "partno": 1,
11      "total": 1
12   },
13   "payload": "The SMS Content",
14   "endpoint": {
15      "id": "10",
16      "name": "My Test SIM"
17   },
18   "id": "12345",
19   "source_address": "42366391012345",
20   "dest_address": "12345"
21}

If you’re new to JWTs, here are some helpful resources:

  • JWT.io lists libraries designed for decoding and encoding JWTs.
  • JJWT is a library for creating and verifying JWTs on the Java Virtual Machine (JVM) and Android.

Delivery receipts

The callback URL may also be used to receive SMS delivery receipts in the form of a PATCH request. When the SMS interface for an endpoint is set to use the REST API in the corresponding service profile, mobile terminated (MT) messages triggered via API generate payloads toward the callback URL with a payload in the following format:

1{
2  "organisation": {
3    "id": "1337"
4  },
5  "id": "20801096",
6  "final_date": "2019-11-15 09:35:18",
7  "submit_date": "2019-11-15 09:35:14",
8  "endpoint": {
9    "id": "9689516",
10    "name": "My Test SIM"
11  },
12  "status": {
13    "id": "4",
14    "status": "DELIVERED"
15  }
16}

A2P and P2P routing

The emnify system distinguishes application-to-peer (A2P) SMS from peer-to-peer (P2P) SMS based on the length of the source (MO SMS) or the destination (MT SMS) address.

  • If there are 7 digits or less (that is, an invalid MSISDN), an SMS is considered A2P.
  • If there are 8 digits or more, an SMS is processed as MSISDN and considered P2P.

To dispatch SMS MO to your application (A2P) and at the same time have P2P SMS enabled, the destination number (dest_address) must be limited to 7 digits or less.

1{
2  "id": 123,
3  "endpoint": {
4    "id": 1,
5    "name": "Your endpoint"
6  },
7  "organisation": {
8    "id": 4,
9    "name": "Your organization name"
10  },
11  "source_address": 432311234,
12  "dest_address": 1234567,
13  "payload": "This is the message text",
14  "dcs": 0,
15  "pid": 0,
16  "submit_date": {}
17}