• http://www.gongmsgn.com/wp-content/uploads/2012/12/services_banner.jpg

    Blog

http://www.gongmsgn.com/wp-content/themes/flare/images/shadow-1.png

Transparent PIN Delivery Flow Explained

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 GONG HTTP REST API* we’ll provide expert insight into:

*To get more familiar with GONG 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.gongmsgn.com/restapi/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 /restapi/sms/1/text/advanced HTTP/1.1
Host: api.gongmsgn.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
   "messages":[
      {
         "from":"DemoSMS",
         "destinations":[
            {
               "to":"2348056661831"
            }
         ],
         "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": "2348056661831",
      "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 GONG 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 GONG 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": "2348056661831",
      "sentAt": "2015-10-04T13:01:52.933+0000",
      "doneAt": "2015-10-04T13:02:00.134+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 1.2000000000,
        "currency": "NGN"
      },
      "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 GONG 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": "2348056661831",
      "sentAt": "2015-06-04T13:01:52.937+0000",
      "doneAt": "2015-06-04T13:02:01.204+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 1.2000000000,
        "currency": "NGN"
      },
      "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 GONG 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.gongmsgn.com/restapi/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 /restapi/ct/1/log/end/9304a5a3ab19-1ca1-be74-76ad87651ed25f35 HTTP/1.1
Host: api.gongmsgn.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" 
} 

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@gongmsgn.com!

Share Button

About GONG:

GONG is a global mobile transaction cloud service connecting mobile and IP service providers and enterprises through an in-house developed and operated communication services cloud. Our converged messaging, m-payments, push notifications, voice and unified communication services bring a mobile and IP dimension to any business. Offices in Nigeria and strategic partnerships with major telco groups enable us to provide seamless integration, delivery and user experience. Always looking for innovation and new ideas, fostering a customer-first business philosophy and having the reach to every part of the world makes us the reliable provider for many clients in Nigeria and worldwide.