Missed Call Guideline

# Overview

The Missed Call (known as Reverse CLI) method is based on a missed call sent by CheckMobi on the user's phone number. Then in order to validate the number the application has to send back the last 4 digits from the incoming call number as pin.

# Implementation

In the next diagram you can see how Missed Call (Reverse Caller ID validation) is working with CheckMobi services:

CheckMobi Missed Call Validation Flow

Basically this method involves 2 different steps:

  • Request for a validation.
  • Checking the pin by sending back the last 4 digits from where the call was received.

# 1. Request for a validation

In order to request a new validation you need to call the Request Validation API.

Within this API call you will have to populate inside the JSON payload the type property using reverse_cli (for missed call validation) and the number property with the number you want to validate. (of course, you can also populate the platform property as well, and we strongly recommend you to do this even if is not mandatory, for better analytics.).

In the client, after this API call, you will wait for the incoming call a certain amount of time (you decide how much - we recommend 30 - 40 seconds).

# 2. Verifying the PIN

This process is done using the Verify PIN API. During this process the last 4 digits from the caller id (number from where the call was received) are used as the pin.

You should take into account the following scenarios:

# 2a. Client doesn't get the call in the desired timeframe

In case the client doesn't get any call in the desired timeframe you decided, you can fire the Verify PIN API resource populating the properties as follow:

  • id - the value of the id property received in response to the call from step 1.
  • use_server_hangup - set this to true, in order to force the server to hangup the call.
  • pin - set this to string HANGUP

You can call as well the Hangup API which will have the same effect (but we prefer the first approach described because we have better-debugging info in case you report issues).

Both methods are doing the same thing: will tell the server to hangup immediately the call because that validation is no longer possible (maybe user put a wrong number and the phone is ringing somewhere else or maybe there is a problem with the carriers calling that destination).

# 2b. Incoming call is received

In case the client catches a call, you are calling same Verify PIN API as in the above section 2a, with same parameters and values, exception being the value of pin parameter. This one should be populated with the last 4 digits from the number from where the call comes (instead HANGUP as in previous section).

In response to this, you will get if the number is validated or not and the server will make sure the call will be canceled immediately (if you set the use_server_hangup=true parameter).

# Notes

  • This might be the ideal approach for Android because on Android you are able to take information about the number you are called from and send it automatically to us.

  • On iOS you can only detect that you got a call but the user has to put last 4 digits manually for this reason the approach is a bit different.


A. Why use_server_hangup=true and just not close the call from the device when received?

When closing call from device and not from the caller (our server), some carriers will charge us (they play some messages like : user is busy please try later or leave a message after the beep) and we will have to charge you as well.

B. When a missed call validation can fail?

There are multiple reasons but most common are:

  • User put a wrong number and the phone is ringing somewhere else (will trigger point 2a)
  • Carrier doesn't propagate the number we are sending and replace this with something else (it might happen on certain destinations)
  • Bad implementations on clients/clients crashing during validation