Introduction

One of the most common use-case for SMS is about conveying a one-time password to a user’s mobile phone.

Wavecell offers a dedicated API method to make it easier for you to do just that.

In this tutorial, we are going to cover the following two methods: Mobile Verification - Code Generation and Mobile Verification - Code Validation

As their names put it, they are about generating then sending a code to a user and then verifying it.

If you follow the different steps of this tutorial, you will get to generate a code and verify it directly from your command line utility using a simple curl command.

Prerequisites

  • Command line interface compatible with CURL
  • Wavecell account
  • apiKey (Bearer token)
  • Wavecell subaccountid
  • Destination phone number
  • SMS Body
  • Brand name

Account and credentials

You will need to sign-up to use the API. The following steps will guide you through this process and highlight the information to keep aside.

I. Signing-up

  1. Head to https://wavecell.com
  2. Click on SIGN UP.
  3. Enter your email and follow the instructions to define your password and finalize your account.
  4. Confirm your email address by clicking on the validation link you received in the activation email to activate your account.

Sign up


II. Finding your apiKey bearer token (for API authentication)

  1. Head to https://app.wavecell.com .
  2. Click on LOG IN.
  3. Enter your email address and password to get access to your account dashboard.
  4. Head over to the configuration > API keys section
  5. Create an API key if empty and then keep the API Key value, here: OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww

API Key

III. Identifying your Wavecell Subaccountid

  1. Head over to the pricing section and use the subaccountid list to retrieve the subaccountid that you want to use
  2. By default, your account comes with only one subaccountid for your high-quality service. It is designated by your accountid and the suffix _hq.
  3. Note down this value, you will need it later.
  4. In that example, the subaccountid is amazing_hq

subaccountid


Part 1: Generating and sending a code using the Mobile Verification API - Code Generation method

The Wavecell Mobile Verification - Code Generation method expects requests sent by developers to respect a specific format.
In the following parts, we are going to go over the different elements of the request:

  • the URL format
  • the authentication
  • the data payload.

At the end of the section, we will generate a curl command to generate an SMS containing a one-time password directly from the command line.

I. Preparing the request URL

Remarks
  • We are going to send a POST request to the Mobile Verification API - Code Generation endpoint.
  • As detailed in the documentation , the URL is defined by the following pattern: https://api.wavecell.com//otp/v1/{subAccountId}
Tutorial URL
  • In order to create the URL to use, we are going to replace {subaccountid} in the pattern above by amazing_hq, the subaccountid that we are using in this tutorial
  • In that example, the URL that we are going to send the request to is: https://api.wavecell.com/otp/v1/amazing_hq
curl
  • In curl, we will have to indicate that we want to do a POST request to this URL by using the following command:
curl -i -X "POST" https://api.wavecell.com/otp/v1/amazing_hq
  • The -i flag (case-sensitive) will allow to print the request response body and headers
  • The -X flag is used to specify the HTTP method to use for the request (POST, HEAD, PUT, GET, DELETE…) - Here we are using a POST request.

II. Preparing the request authentication

Remarks

  • As explained in the docs, the API authentication uses an apiKey bearer token method.

Tutorial authentication

  • In this tutorial, the apiKey for our account is OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww .

curl

  • In a curl request, bearer tokens must be passed as a header like so: -H "Authorization: Bearer {token}"
  • We just have to replace our {token} placeholder by our apiKey
  • The authorization header will then look like that: -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww"

III. Preparing the request data payload

  • The API expects to receive a structured request containing the SMS data in a specific format.
  • As detailed in the documentation, the data that we have to submit should be a JSON object containing at least a destination field. Let’s keep it simple and add a brand name as well as a country code since our destination phone number is in the national format (as opposed to international format):

Example of JSON object:

{
  "destination": "98765432",
  "country": "SG",
  "productName": "Amazing Product"
}

curl

  • In curl, we will transmit the JSON data inline and indicate that the data payload is in JSON format using the following commands:
-H "Content-Type: application/json" 
-d $'{
  "destination": "98765432",
  "country": "SG",
  "productName": "Amazing Product"
}'

IV. Putting it together and posting the curl request

  • If we wrap up all the elements prepared in the steps above, we should put together the 3 elements of our request: URL + Authentication + Data Payload
  • To send the API request to Wavecell Mobile Verification - Code Generation endpoint we should use the following command in our command line utility:
curl -i -X "POST" https://api.wavecell.com/verify/v1/amazing_hq -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww" -H "Content-Type: application/json" -d $'{ "destination": "98765432", "country": "SG", "productName": "Amazing Product" }'
  • And that’s it! Here is the result on the destination device:

V. API response

  • When sending the curl command above from your command line utility, you notice that the Wavecell API sends back a response that shows up in your terminal, for example in this tutorial:
{
  "uid": "c96a488d-5704-459e-9dee-3dd8138b3a52",
  "resourceUri": "/otp/v1/amazing_hq/c96a488d5704459e9dee3dd8138b3a52",
  "msisdn": 6598765432,
  "status": "WAITING",
  "attempt": 0,
  "expiresAt": "2017-08-29T20:52:09.0790425+00:00",
  "nextSmsAfter": "2017-08-29T20:47:19.0790425+00:00"
}
  • The API response is used to provide a feedback about the expected result of the API request (sending an SMS) and various additional information.
  • If we take some time to analyze the different elements there, we can identify the following:
    • uid: this is the unique identifier set by the API to identify this request. It will be used to check its status and the codes provided.
    • resourceUri: it indicates the uniform resource identifier within Wavecell API
    • msisdn: this is the phone number to which the SMS was sent.
    • status: the status of the Mobile Verification request
    • attempt: this counter shows how many unsuccessful attempts have been made to verify this code
    • expiresAt: this is the timestamp that indicates when the code will expire
    • nextSmsAfter: this timestamp indicates when the system will allow sending another SMS if a new request is sent
  • For more information, check the dedicated section of the API documentation, in the “Response” section

Part 2: Verifying a code received using the Mobile Verification API - Code Validation method

So our user received successfully his SMS containing the code required to verify his mobile phone number (see [Part 1 - IV]).

Here below are the elements from the part 1 that are going to be used in this part 2:

  • apiKey = OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww
  • Subaccountid = amazing_hq
  • uid = c96a488d-5704-459e-9dee-3dd8138b3a52
  • code = 7085

Request URL

According to the documentation, the Wavecell Mobile Verification - Code Validation method is much simpler to use: it simply expects a GET request sent to an URL built using 2 different parameters:

  • the subaccountid: amazing_hq
  • the uid returned by the API during part 1: c96a488d-5704-459e-9dee-3dd8138b3a52

➡ the URL where to send the GET request should follow this structure: https://api.wavecell.com/otp/v1/{subAccountId}/{uid}

In our example, we just have to use the parameters values listed above to compose our URL: https://api.wavecell.com/otp/v1/amazing_hq/c96a488d-5704-459e-9dee-3dd8138b3a52

curl

In curl, we will have to indicate that we want to do a POST request to this URL by using the following command:

curl -i -X "GET" https://api.wavecell.com/otp/v1/amazing_hq/c96a488d-5704-459e-9dee-3dd8138b3a52

II. Preparing the request authentication

Remarks

  • As explained in the docs (https://wavecell.com/docs/#authentication), the API authentication uses an apiKey bearer token method.

Tutorial authentication

  • In this tutorial, the apiKey for our account is OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww .

curl

  • In a curl request, bearer tokens must be passed as a header like so: -H "Authorization: Bearer {token}"
  • We just have to replace our {token} placeholder by our apiKey
  • The authorization header will then look like that: -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww"

III. Preparing the request data payload

Remarks

  • Contrarily to the POST request in the part 1, here the data are passed using a query string: the parameters are appended directly in the URL where we sent the GET request
  • This method can be used to consult a status of a request without actually verifying it: if no code value is appended in the GET request URL, then the API will respond with the status of the request without changing it.
  • To perform the validation action, a code value must be appended in the GET request URL: if the code is the right one and has not expired, the status of the request will be changed to VERIFIED. If the code is not the right one, the attempt counter will be incremented.

Appending the code in the query string for our code validation

  • Our code value is 7085
  • A query string is appended at the end of the URL using ? as separator and then {parameter_name}={parameter_value}

➡ We will have to append the following query string to our URL: ?code=7085

IV. Putting it together and posting the curl request

  • If we wrap up all the elements prepared in the steps above, we should put together the 3 elements of our request: URL + Query string appended + Authentication
  • To send the API request to Wavecell Mobile Verification - Code Validation endpoint we should use the following command in our command line utility:
curl -X GET 'https://api.wavecell.com/otp/v1/amazing_hq/c96a488d-5704-459e-9dee-3dd8138b3a52?code=7085' -H "Authorization: Bearer OiLc1xKaghw3sD1piU6sZHYwSuFK3uWtLQn4WjvOww"
  • And that’s it! Here is the response from our terminal:
{
	"uid": "c96a488d-5704-459e-9dee-3dd8138b3a52",
	"resourceUri": "/otp/v1/amazing_hq/aa0fb28141bd4bedae848f9615b0221e",
	"msisdn": 6598765432,
	"status": "VERIFIED",
	"attempt": 0,
	"expiresAt": "2017-08-29T21:43:26.641256+00:00",
	"nextSmsAfter": "2017-08-29T21:38:36.641256+00:00"
}

You can see that the status of the request is now verified: the code provided was the right one which means that your user provided a legit mobile phone number where he received the code generated by the API, you can let him through!