Phone verification flow with OTP using WhatsApp API

WhatsApp API allows you to send messages to any user that has a WhatsApp number. This opens up endless possibilities to send different types of notifications or verify phone numbers.

In this tutorial, we will show you how to build an OTP flow that verifies phone numbers using WhatsApp as sender provider.

Prerequisites

• An active Facebook Business Manager account. You can create one here.
• A valid phone number with WhatsApp Business account. You can buy a virtual number for this with Twilio.
• An active Arengu account. You can sign up here.
• The user who receives the WhatsApp message needs to accept the new Terms of Service and Privacy Policy, otherwise it won’t be delivered. You can find more info here.

An overview of the flow we’re building

The structure of the flow will be:

• We will require the phone number in the first step.
• After the user provides the phone number, we will generate an OTP and send it using the WhatsApp API.
• The user will be required to provide the verification code.
• After the user provides the verification code, we will check if it's valid or not. If it's valid, we will display a thank you message, if it's not valid, we will display an error message.

1. Create and configure the app in your Business Manager

If you don’t have one, you need to create an app in your Facebook Business Manager choosing the “Business” type:

‍

Once it’s created, go under WhatsApp > Getting started:

Here you will have your temporary access token that we will use in the next sections and your testing phone number. You can add your own phone number if you go under WhatsApp > Configuration > Manage phone numbers.

1.1 Create a message template

You can send free text messages using the WhatsApp API but, in this case, we’re going to create a template:

Once you click “Create Message Template”, pick the “One-Time Password” option, name it “otp” and fill out the template:

• Header: Verification code
• Body: Hey! 👋  I'm testing an OTP flow with the WhatsApp API. {{1}} is your verification code.
• Footer: place your brand name, we’re using “Arengu Testing”.

Notice we use “{{1}}” as a variable, this is the syntax that WhatsApp API uses to dynamically replace those variables with the values we pass to the API.

Note you will use the name of this template to call the WhatsApp API in the next sections.

1.2 Generating a permanent access token

Before moving to a production environment, remember to generate a permanent access token, otherwise, the temporary one will expire in 24 hours.

To generate the permanent token go under Users > System users in your Business Manager settings, click “Add”, name it as you want, and choose “Admin” user role.

Now, click “Generate new token” and make sure you enable the “whatsapp_business_management”, “whatsapp_business_messaging” and “business_management” permission:

‍

Then, copy the generated access token, as we will use it to configure the WhatsApp API:

2. Build the form requiring the phone number and the verification code

Let’s start adding a first form step with a “Phone” field:

• Rename the field ID to “phone” to ease referencing its value.
• Mark it as required.
• Enable “Country picker” to allow users to pick their country code. By default, we automatically pick the country based on the users’ IP location.

In the second step, let’s add a “Number” field:

• Rename the field ID to “verification_code” to ease referencing its value.
• Mark it as required.

You can also add a “Rich text” block to add some descriptions and guide the user. Note you can click the plus icon to use field values from previous steps like in the above example:

“Please enter the 4-digit verification code that was sent to {{fields.phone}}. The code is valid for 30 minutes.”

And last, place some text as a thank you message in the ending screen settings:

3. Generate the OTP and send it using the WhatsApp API

Go to the flows tab, and let’s create the first flow that we will execute between the step 1 and step 2:

Let’s start adding the “Generate one-time password” action:

• Rename the action ID to “generateOtp” to ease referencing the generated value.
• Add “{{input.body.phone.number}}” to the “Reference value” input. 
• Set 4 digits as “Code length” value.

As second action, add an “HTTP Request” that we will use to call the WhatsApp API:

• Rename the action ID to “sendMessage” to ease referencing the generated value.
• Click on the plus icon under the “Connection” field and provide the temporary or permanent access token generated in the previous section.
• Set “https://graph.facebook.com/v13.0/YOUR_PHONE_NUMBER_ID/messages” as URL. You will find your phone number ID in your app settings. 
• Change the “Method” to “POST” and “Content type” to “application/json”
• Use the following payload as body:

{
  "messaging_product": "whatsapp",
  "to": "{{input.body.phone.countryCodeNumber}}{{input.body.phone.nationalNumber}}",
  "type": "template",
  "template": {
    "name": "otp",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{{generateOtp.code}}"
          }
        ]
      }
    ]
  }
}

Note the following about the payload:

• We’re using “otp” as template name because it’s the same one we’ve created in the previous section.
• Use the same language code as the one you've used creating this template.
• The “to” property uses two variables because it expects the international phone number without the “+” icon.
• Inside the “components” property, we pass the generated OTP that will replace the {{1}} of our WhatsApp template.

Add an “If/then condition”:

• Add {{sendMessage.success}} in the first input.
• Set “is true” in the second input.

And last, close this flow adding two more actions:

• Show error message with {{sendMessage.body.error.message}} value. This will return the output message of the WhatsApp API in case there is any error.
• Jump to a form step selecting the second step of the created form.

4. Verify the WhatsApp number OTP

For this last flow, we will start adding a “Verify one-time-password” action:

• Rename the action ID to “verifyOtp” to ease referencing the generated value.
• Add {{input.body.phone.number}} to the “Reference value” input.
• Add {{input.body.verification_code}} to the “Code value” input.

Then, add an “If/then condition” action that will evaluate the output of the OTP verification:

• Add {{verifyOtp.valid}} as first input value.
• Set “is true” in the second input.

Close this flow with two more actions:

• Show error message with “Your verification code is not valid. Please, review it and try it again.” value.
• Submit the form that will display the thank you message you’ve configured in the previous section.

That’s all! Now you have a verification flow that sends an OTP via WhatsApp and verifies the phone number. Remember you can download this scenario to easily test this use case.