Development

Transparent PIN Delivery Flow Explained

Have you ever wondered why secure PINs aren't delivered instantly? Do you want to be able to immediately tell what happened to the message containing your user's PIN?

December 28 2015

Sending PINs to help your users authenticate their accounts isn’t exactly news, but having a transparent flow, knowing where exactly your PIN is, why it’s not delivered, being able to communicate this to your clients – that’s a completely new and exciting story.

SMS-based 2-factor authentication flows are simple. As soon as your user tries to log into his account, he gets an SMS message with their personal identification number (PIN), which provides additional security upon access. This can help prevent this.

It seems really easy, you write a couple of lines of code, implement it into your app, and voilà - you’ve added the entire 2-factor authentication logic. Just like this, you’ve boosted end-user account security.

Usually, messages are delivered to users in just a couple of seconds, but what happens if they aren’t? Sometimes the message is not delivered instantly. Have you ever wondered why? Do you want to be able to immediately tell what happened to your message? Good, because that’s exactly what we’re going to show you.

With this step-by-step tutorial for integrating our full Messaging Suite into your processes using Infobip HTTP API* we’ll provide expert insight into:

*To get more familiar with Infobip SMS HTTP API, visit our Getting started tutorial.

Send SMS

In order to start sending your SMS messages, you’ll need to create a HTTP POST request to https://api.infobip.com/sms/1/text/advanced

Your Header should contain authorization and content type.

  • Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  • Content-Type: application/json

We will show you examples of how to Send SMS, set a parameter to receive Intermediate and Final delivery report, and how to set SMS tracking for Conversion rates.

JSON


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

{
   "messages":[
      {
         "from":"InfoSMS",
         "destinations":[
            {
               "to":"41793026731"
            }
         ],
         "text":"Your PIN code is 1a2B3c. Enjoy our app!",
         "intermediateReport":true,
         "notifyUrl":"http://www.example.com/sms/advanced"
      }
    ],
   "tracking":{
         "track":"SMS",
         "type":"One_Time_Pin"
   }
}

As a response you should receive a 200 OK status with message details in the response body:

JSON


HTTP/1.1 200 OK
Content-Type: application/json

{
  "bulkId": "1446634544520356423",
  "messages": [
    {
      "to": "41793026731",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ENROUTE",
        "description": "Message sent to next instance"
      },
      "smsCount": 1,
      "messageId": "8ef699bc-d4c6-4cf6-8d6e-9a9aa62ad93a"
    }
  ]
}

One of the parameter received in the response is messageId that used for Submitting Conversion rates to Infobip platform.

For further explanation and examples for sending messages, visit this Documentation page.

Intermediate delivery reports

Intermediate delivery reports are used for receiving real time information about your messages.

As soon as any non-permanent GSM error has been received (i.e. EC_ABSENT_SUBSCRIBER) by the Infobip system, it will be forwarded to the specified Notify URL* on your callback server. Besides GSM errors, we will also send you the real-time pricing information, message status, and network and country codes.

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

For more information regarding GSM error codes and message statuses, check out our Response codes page.

Below is an example of Intermediate delivery report that will be pushed to your callback server:

JSON


{
  "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
      }
    }
  ]
}

Final Delivery reports

As soon as final delivery reports for sent messages have been received by the Infobip system, they will be forwarded to specified Notify URL on your callback server.

You will receive the result on your Notify URL, which will have the same structure as the intermediate delivery report:

JSON


{
  "results": [
    {
      "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": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "error": {
        "groupId": 0,
        "groupName": "OK",
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "permanent": false
      }
    }
  ]
}

Conversion tracking solution

When you're conducting an SMS campaign, one of the most important things is to track its performance and measure your user conversion rates. For example, if you are sending one-time PINs over SMS, it’s really important to track conversion rates so you can optimise your flow and processes.

Conversion tracking has to be initiated every time your process starts and ended when the conversion happens. Only once this loop has been closed, we consider it as a successful conversion.

INITIATE CONVERSION TRACKING PROCESS

Our SMS tracking solution will automatically track every message sent over the Infobip platform. Just set the track parameter, put the type of your campaign and SMS tracking will be done automatically.

These features are set in the tracking objects when Sending an SMS message.

CONVERSION RATE SUBMISSION

When a user successfully performs the action after receiving the SMS, for example enters the one-time PIN in your app, you can send that info to us so we can measure conversion rates.

For conversion rate submission, you need to provide only the messageId received after Sending an SMS message. The messageId has to be submitted to our endpoint as the conversion happens. The Endpoint for submitting conversion rates: https://api.infobip.com/ct/1/log/end/{messageId}.

Example: Submitting the messageId for converted messages

This example shows you how to submit the messageId when the conversion happens.

JSON


POST /ct/1/log/end/9304a5a3ab19-1ca1-be74-76ad87651ed25f35 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

As a response, you will receive a processKey that is used for getting conversion rates and statistics:

JSON

{
    "processKey": "A37D448C1ACCA02FABA745522558326C" 
} 

For more help in providing a more transparent 2FA flow your business, contact us over support@infobip.com!