In this scenario, we'll explore the process of verifying a user's identity and authorization before allowing that user to gain access to their account, send communications, or request data from a secured network, system, or application through the WhatsApp delivery channel. That is, the goal of this use case is to explore the process of how to
to implement the two-factor authentication via WhatsApp.

Before beginning, it is essential to take into account the following prerequisites.

• Get API Key: From the Digital Engagement Platform, copy the API Key located in Preferences section > API tab.

• For WhatsApp, you need to:

  Get a Facebook Business Manager ID.

  Create a WhatsApp Business Account ID (WABA).

  Create a Sender.

• Have created a WhatsApp Authentication Template. If you haven't done so already, we'll guide you through creating a new one in this example.

The steps to set up Two Factor Authentication through WhatsApp are the following:

• Create WhatsApp Authentication Template.
• Create a Code Generator
• Send Verification Code to the end user (recipient)
• Validate Verification Code

Create WhatsApp Authentication Template.

In this step we are going to learn how to create an authentication template with an OTP button.

The authentication template consists of the following content:

• Fixed preset text:

  The Body message is defined by META. That is, the body is fixed -> “<VERIFICATION_CODE> is your verification code”.

  Next to the Body message, it is defined a security recommendation message (Security disclaimer message) as a boolean (optional) by META: “For your security, do not share this code”.

  From the Footer, you are able to add an Expiration warning message (optional): “This code expires in <NUM_MINUTES> minutes”.

• OTP button: It is mandatory to add an OTP button. Either a copy code button. A copy code button copies the one-time password or code to the user's clipboard.

Let’s replicate the next example:

📘

NOTE

The “982012” code displayed in the example will differ from the one sent to the end user because the next step is to generate that code. Additionally, the codes are generated randomly.

HTTP Request: POST /whatsapp/templates

Before beginning, in this API call you need to provide the WhatsApp Business Account ID (WABA) or the unique identifier of the Sender.

🚧

WARNING

Enter only one of the required parameters (“wabaId” or “senderId”), not both.

In this example we are going to enter the WABA Id.

The following request body includes a body, footer and OTP Button.

curl --request POST \
     --url 'https://elastic.messangi.me/balerion/v2/whatsapp/templates/?wabaId=<WABA_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <YOUR_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "elipackage_authentication",
  "category": "AUTHENTICATION",
  "templateLanguages": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "securityRecomendation": true
        },
        {
          "type": "FOOTER",
          "expirationMinutes": 15
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "OTP",
              "otp_type": "COPY_CODE",
              "text": "Copy Code"
            }
          ]
        }
      ]
    }
  ]
}'

Request Body Parameters

{
  "meta": {
    "timestamp": 1707177081141,
    "transactionId": "395b2ac9-1046"
  },
  "errors": {
    "reason": "error Meta template",
    "details": {}
  },
  "data": {
    "wabaId": 11234567232528,
    "name": "elipackage_authentication",
    "category": "AUTHENTICATION",
    "templateLanguages": [
      {
        "id": "37587656784131",
        "language": "en",
        "components": [
          {
            "type": "BODY",
            "securityRecomendation": true
          },
          {
            "type": "FOOTER",
            "expirationMinutes": 15
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "OTP",
                "otp_type": "COPY_CODE",
                "text": "Copy Code"
              }
            ]
          }
        ]
      }
    ]
  }
}

1. Copy the request body and paste it in your terminal command.
2. Press Enter key
3. From the response body, copy the unique identifier of the WhatsApp authentication template (“data.templateLanguages.id”) parameter.

📘

NOTE

Upon the creation of the authentication template, META approval is required.

Create a Code Generator

Once the WhatsApp Authentication Template has been created and approved by META, the next step is to create the code generator.

Code Generator is a security feature for your Application used with two-factor authentication. You can add an authentication factor linked to a channel (WhatsApp). When a user signs up or logs into your application a numeric code is sent to their mobile device either via WhatsApp. For this reason, the second step is to create the code generator and configure the code that will be sent to the end user.

When you create a Code Generator for WhatsApp, the request body contains the following data:

HTTP Request: POST /v1/2fa

curl -X 'POST' \
  'https://elastic.messangi.me/eyriesgate/v1/2fa' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "codeLength": 6,
  "expirationMinutes": 15,
  "channels": [
    {
      "type": "WHATSAPP",
      "address": "584111111111",
      "templateId": "3752812345987345",
      "placeholder": "code"
    }
  ]
}'

Request Body Parameters

{
  "meta": {
    "timestamp": 1707180413315,
    "transactionId": "a6a16b0a-b830"
  },
  "data": {
    "id": 250,
    "codeLength": 6,
    "expirationMinutes": 15,
    "channels": [
      {
        "placeholder": "code",
        "address": "584111111111",
        "templateId": "3752812345987345",
        "type": "WHATSAPP"
      }
    ]
  }
}

1. Copy the request body and paste it in your terminal command.
2. Press Enter key
3. From the response body, copy the unique identifier of the code generator (“data.id”) parameter.

Send Verification Code

Once the code generator has been created, the next step is to send the verification code to the end user.

HTTP Request: POST /v1/2fa/{id}/codes

In this API call you need to provide the unique identifier (“data.id”) of the code generator previously created.

curl -X 'POST' \
  'https://elastic.messangi.me/eyriesgate/v1/2fa/<CODE_GENERATOR_ID>/codes' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "channel": "WHATSAPP",
  "receiver": "+525500000000"
}'

Request Body Parameters

{
  "meta": {
    "timestamp": 1707183277726,
    "transactionId": "7942859d-45d2"
  },
  "data": {
    "requestId": "c12345616-fee2-f345hgf-fgh123"
  }
}

1. Copy the request body and paste it in your terminal command.
2. Press Enter key.
3. From the response body, copy the unique identifier of the two factor authentication request (“data.requestId”) parameter.

Validate Verification Code

Once the code has been generated and sent to the user via WhatsApp, you proceed to validate the user.

When the user enters the security code to your application, you can carry out the following actions :

• Verify the security code to validate the user.
• Cancel the security code.
• Check the Status of the security code.

In this example, we'll solely verify the security code.

HTTP Request: PATCH /v1/2fa/{id}/codes

In this API call you need to provide the unique identifier (“data.id”) of the code generator and the unique identifier (“data.requestId”) of the request previously created.

Prior to validating the user, it's necessary to initially verify the status of the verification code.

curl -X 'PATCH' \
  'https://elastic.messangi.me/eyriesgate/v1/2fa/<CODE_GENERATOR_ID>/codes' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "status",
  "requestId": "<REQUEST_ID>"
}'

Request Body Parameters

{
  "meta": {
    "timestamp": 1707243156412,
    "transactionId": "6ae15fa5-1e97"
  },
  "data": {
    "id": 534,
    "userID": "+525500000000",
    "token": "151820",
    "requestID": "c12345616-fee2-f345hgf-fgh123",
    "expirationDate": "2024-02-06T01:44:37.020949",
    "validationDate": null,
    "validationChannel": "WHATSAPP",
    "status": "PENDING"
  }
}

Response Body Parameters

1. Copy the request body and paste it in your terminal command.
2. Press Enter key.
3. From the response body, copy the verification code (“data.token”) parameter.

Because the verification code is in “PENDING” status, we proceed to validate the code.

📘

NOTE

In this API Call, the user needs to enter their verification code to valid the code.

We acquired that code from the previous request to provide you with a clearer understanding of its status and validation.

curl -X 'PATCH' \
  'https://elastic.messangi.me/eyriesgate/v1/2fa/<CODE_GENERATOR_ID>/codes' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "verify",
  "requestId": "c12345616-fee2-f345hgf-fgh123",
  "code": "151820"
}'

Request Body Parameters

{
  "meta": {
    "timestamp": 1707252519688,
    "transactionId": "424cd21f-a190",
    "explain": "valid code"
  }
}

Response Body Parameters