Products

Intermediate Delivery Reports - Make The Most Of 2-Factor Authentication

How and why receiving a real-time SMS delivery report can improve your one-time PIN distribution.

April 19 2016

When sending one-time PINs (OTP) in SMS messages to your clients or users phones as part of the 2-factor authentication process, you need to take care about couple of things. More often than not, you’ll need one-time PIN codes delivered in real time, or near real time, and this has been the critical aspect of the 2FA service for online companies and mobile apps for quite some time now. Failed or delayed delivery of the SMS message which carries an authentication code is directly related to conversion rates – i.e. successful mobile app activations, successful login etc.

There are many reasons why your message can't be delivered this exact second – sometimes it happens because your user turned off the phone, or their phone storage is full, the list goes on and on. Waiting for a final delivery report or SMS message timeout period to expire so you get a GSM error code is time-consuming and really not an option if you want to provide your users with real-time 2-Factor Authentication (2FA).

Intermediate delivery report is set as one of the parameters of the Fully featured textual message API method. It is pushed over the same Notify URL as the final Delivery report.

As soon as any non-permanent GSM error has been received (i.e. EC_ABSENT_SUBSCRIBER) by the Infobip system, our SMS API based intermediate reports (delivered in real time) will forward it to your Notify URL placed to your callback servers.

Besides GSM errors, you will also receive real-time pricing information, message status, network and country codes.

If you want more info regarding GSM error codes and message statuses, check out our Response codes page.

*Notify URL is set as one of the parameters of the fully-featured textual message API method.

The example bellow shows how to set intermediateReport for instant message information as well as notifyURL, notifyContentType for the reports and the user's callbackData.

POST /sms/1/text/advanced HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
   "bulkId":"BULK-ID-123-xyz",
   "messages":[
      {
         "from":"InfoSMS",
         "destinations":[
            {
               "to":"41793026727",
               "messageId":"MESSAGE-ID-123-xyz"
            },
            {
               "to":"41793026731"
            }
         ],
         "text":"Mama always said life was like a box of chocolates. You never know what you're gonna get.",
         "intermediateReport":true,
         "notifyUrl":"http://www.example.com/sms/advanced",
         "notifyContentType":"application/json",
         "callbackData":"There's no place like home."
      }
    ]
}

The result you will receive on your Notify URL will have the same structure as the Final delivery report.

{
  "results": [
    {
      "bulkId": "BULK-ID-123-xyz",
      "messageId": "c9823180-94d4-4ea0-9bf3-ec907e7534a6",
      "to": "41793026731",
      "sentAt": "2015-10-04T13:01:52.933+0000",
      "doneAt": "2015-10-04T13:02:00.134+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0.0001000000,
        "currency": "EUR"
      },
      "status": {
        "groupId": 3,
        "groupName": "PENDING",
        "id": 1,
        "name": "PENDING_WAITING_DELIVERY",
        "description": "Message sent, waiting for delivery report"
      },
      "error": {
        "groupId": 1,
        "groupName": "HANDSET_ERRORS",
        "id": 27,
        "name": "EC_ABSENT_SUBSCRIBER",
        "description": "Absent Subscriber",
        "permanent": false
      },
      "callbackData":"There's no place like home."
    },
    {
      "bulkId": "BULK-ID-123-xyz",
      "messageId": "MESSAGE-ID-123-xyz",
      "to": "41793026727",
      "sentAt": "2015-06-04T13:01:52.937+0000",
      "doneAt": "2015-06-04T13:02:01.204+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0.0001000000,
        "currency": "EUR"
      },
      "status": {
        "groupId": 3,
        "groupName": "PENDING",
        "id": 1,
        "name": "PENDING_WAITING_DELIVERY",
        "description": "Message sent, waiting for delivery report"
      },
      "error": {
        "groupId": 1,
        "groupName": "HANDSET_ERRORS",
        "id": 27,
        "name": "EC_ABSENT_SUBSCRIBER",
        "description": "Absent Subscriber",
        "permanent": false
      },
      "callbackData":"There's no place like home."
    }
  ]
}