3.5.1 Phone number registration
- Piotr Mrozek
Sign up with the phone number allows to associate user’s GSM phone number with his RCS account. This feature is crucial as it is the base of the active address book functionality where existing phone numbers are matched with the RCS service users. Thanks to this a new client can immediately communicate with his phone contacts which are marked as the RCS.
Before a phone number is added to the RCS account the system has to verify the authenticity of the request, i.e. if the phone number really belongs to the person initiating the sign up procedure. The verification is based on sending an SMS with code (one time password) to the given phone number.
Sign up with the phone number is supported in the RCS mobile softphones. In the latter case the code will be sent to the phone number and then the user has to manually type the code from the SMS in the softphone.
In the first step a client has to enter his phone number into the appropriate field in the application’s signup screen. On android devices the number is obtained from the SIM card, however on some SIMs this function is forbidden. If the number can be read from the SIM it will be presented in the application.
After submitting the application sends a request to the EMCD register.ashx method. Besides the phone number the request carries information on the phone’s operating system and the device UDID.
The UDID and phone number pair will be then used to detect if future sign up or log in requests originate from the same device as in the initial registration.
UDID is a Unique Device Identifier and is generated based on device’s hardware parameters.
On receiving the request the EMCD checks if the phone number already exists in the api.clients table. If not a four digits code is generated and sent to the provided phone number via SMS.
The phone, UDID and other information that are sent with the registration request are stored in the dialer_requests table. The field sms_left is used for limiting the number of SMS sent to the same number, from the same device. By default the maximum number is set to 5. With each new SMS sent by the RCS API the number is decreased. When reaches zero the client request is declined with “Too many SMSes” error response which is shown in the application. To allow user for more SMS requests you will need to remove the records for his phone number from the dialer_requests table. Another option is to increase the number in the sms_left field.
Note: if a user already has an account and reinstalled the application the EMCD detects that the registration request comes from the same device-phone number pair and sends the SIP login and password back in the response, skipping the verification procedure.
Sending SMS with code
The EMCD uses an SMS provider for sending verification codes. The API communicates with the provider’s API directly, it does not use voipswitch and its SMS routes which are used for SMS communication from and to clients.
Therefore the relevant settings have to be added to the AppSettings.config file in the SMS API section.
|
By default EMCD is configured to use NEXMO as the SMS provider for verification process.
The first key allows to define the SMS text, the [CODE] is replaced by the actual code when SMS is being prepared. Change the string to reflect your service or app name.
Next three keys contain information obtained from your NEXMO account.
US DID (phone number) is required for SMS delivery in the USA. The number will be shown to the user as the sender number.
And the last key allows to define the sender name which will be shown to the user. Usually it will be your service name. This feature works only in the networks where alphanumeric sender names are allowed. In the USA it is not and hence we needed to get a US DID.
Delivery status
If you use NEXMO it provides delivery state for sent SMS. The softphone sends request to the ds.ashx method to check the current state. The EMCD response can contain a definite state, either success or error/failed or unknown/in progress state. In the latter case the application repeats the request up to several times until it gets a response with a definite state or the process timeouts.
Successful verification
On Android devices the softphone is capable of obtaining the code from the SMS. The moment it arrives the code is put in the code input field. On other operating systems the user has to type the code manually.
Once the code is submitted the application sends a request again to the register.ashx method, this time with the code as a parameter.
The EMCD then creates a new account in voipswitch.clientsshared using the template from the AppSettings.config. The sip login is the phone number in the e164 format. A random password is generated.
Next, an entry in the api.clients is added with the login being phone number, in addition the phone number is put in the phone field.
The EMCD completes the operation by sending the sip login and sip password back to the client. The softphone stores these credentials locally and uses them in subsequent requests to the API and in SIP communication.
Failure
The failure is when a user enters wrong code. The system allows for up to three attempts and then rejects further requests from the same device.
Also it may happen that the SMS has not been received by the user due to the route problem or some other reasons. After requesting the code the softphone’s screen shows a timer counting down 60 seconds, the send button is grayed out. When elapsed, the send button is enabled again. An exception can happen when the delivery state method will return an error, in such case the timer is hidden.
The number of SMS that can be requested by a user is limited, if the limit is reached the system will return an error Too many SMS. You can increase the number of attempts by changing the sms_left value in the api.dialer_requests table.
After the first request, if an error occurs or the time elapses, the user is presented with an option for the system to call him. There is a Call me button shown on the screen. After pressing the button a request is sent to the EMCD.
Callback
To trigger the callback the RCS client calls the EMCD register method again, this time with a parameter which tells EMCD to initiate the phone call instead.
The EMCD sends then a request to VSServices/callback.ashx. The full URL and other parameters are defined in the EMCD/AppSettings.config file:
|
The callback_user and callback_pass are username and password of a retail client type of account created on voipswitch for this purpose only, i.e. for making verification calls. You have to make sure that there is appropriate routing and tariff in place.
Besides the login and password the request contains two more parameters which are the source and destination numbers.
The source number is the number defined in the Routing Plan which points to the IVR (VoipBox) scenario responsible for playing the code. The code itself is the last four digits from the source number. It is being added by EMCD in each request.
In the Destination number field there is a rule set which strips the first eight digits so the number that is passed to the Say verification code scenario comprises the code only.
The destination number parameter is the client’s phone number. The voipswitch will call it through a PSTN carrier (gateway) defined in Destinations menu. When a user answers the call he will hear the IVR saying the code, it is being repeated twice before the call is disconnected.
Flow diagram
