whatsapp-otp-login dialog

Introduction

The whatsapp-otp-login dialog is a global dialog to make the user login in the WhatApp channel.

Currently, it only supports SMS-OTP authentication.

Access to the Kernel WhatsApp API.

📃 Check the dialog’s code in the aura-bot-libraries Github repository.

Flows

The dialog flow is divided in several steps, which are described in the following sections.

Additionally, a sequence flow is included in Operational flowcharts: WhatsApp OTP (LoA2) authentication.

Check if the user is already authenticated

When the dialog flow starts, it checks if the current user is already authenticated, verifying if the type of user is anonymous.

If so, the dialog flow ends with the text resource login.otp.already.signin. If not, it starts a sub-dialog to verify the phone number to send the SMS code.

Check if current number is corporate

In this step, if configured so, the system checks if the current phone number is corporate, to allow using it in next steps.

• If check is not enabled or user is not corporate, go to the following step for prompting a new phone number.
• Otherwise, ask the user if she wants to use current number.

Prompt a phone number

This step prompts the user to enter the phone number he wants to log in with in Aura, thus the dialog will send the SMS-OTP code to that phone number.

• If the phone number format is correct:
  1. If configured to check the prompted number and the number is not corporate, ask for a new phone number (until max number of retries is reached).
  2. Otherwise, it starts a sub-dialog to verify the SMS authcode.
• If the format is wrong, the dialog will prompt again to enter with correct format until the maximum number of attempts is reached (See settings section). When the user reaches this maximum, the dialog ends with the text resource login.otp.too.many.phone.kos.

To send this code to the user phone, the send code endpoint from Kernel is called. This endpoint returns an authentication_id that will be used in the next step to validate the OTP code.

Insert SMS OTP code

This step prompts the user to enter the SMS authcode sent to phone number provided on the previous step.

• When the user enters the correct code, the dialog starts the following step in order to register the user.
• If the authcode is wrong, the dialog will prompt again to enter the correct authcode until the maximum number of attempts is reached (See settings section).

When the user reaches the maximum authcode attempts the dialog ends with the text resource login.otp.too.many.sms.kos. A new code can be sent by sending the text resource login.otp.newCode.command which makes the bot to send a new auth code to the phone number provided.

To validate the code, the Kernel validate code endpoint is called with the code received by the user and the authentication_id returned in the previous api call. This call returns all the necessary data to register the user in Aura.

Register user

This step registers the user in Aura ecosystem and redirects to onboarding T&C with the intent intent.onboarding.terms-and-conditions or the requested intent before authentication if T&C are already accepted.

To do this registry, the method GET /users/aura-id/{auraId} from aura-authentication-api is called and the user is registered with the data obtained from Kernel in the previous step.

The redirect to onboarding (or the intent set) is done if the field actions.afterLogin is present in the channel configuration. An example of this configuration is shown below:

 {
  "name": "whatsapp",
  "prefix": "wa",
  "type": "whatsapp",
  "responseOptions": {
      "versions": {
          "v1": {
            "singleMessage": true,
          }
      }
  }
  .
  .
  .
  "actions": 
    "afterLogin": {
        "type": "redirect",
        "action": "REDIRECT.COMMAND",
        "data": {
            "auraCommand": {
            "type": "suggestion",
            "value": {
                "intent": "intent.onboarding.terms-and-conditions"
            }
            }
        }
    }
  }
  .
  .
  .

This configuration is used to generate the redirect command that will be sent to launch the intent. If there is an intent requested before authentication and the T&C are already accepted, the intent set in configuration will be overwritten with the requested intent.

NOTE The user can cancel login flow at any moment by sending the text resource login.otp.cancel.command.

Sequence diagram

sequenceDiagram
    autonumber
    participant user
    participant auraBridge
    participant auraBot
    participant 4p
    participant auraAuth
    participant T&C API
    rect rgb(255, 255, 230)
    Note left of user: USER REQUESTS AN AUTHENTICATED UC
    user->>auraBridge: I want to see my billing data
    auraBridge->>auraBot: 
    auraBot->>auraBot: Dialog needs auth and user is anonymous. Redirect to whatsapp login
    auraBot->>auraBridge:  
    auraBridge->>user: login.otp.phone.number: Please enter your phone number
    user->>auraBridge: +34665762892
    auraBridge->>auraBot: 
    auraBot->>4p: Aura requests a new OTP sms
    4p->>user: (SMS) login.otp.sms.code.message: Your verification code is 6789
    4p->>auraBot: authorization_id
    auraBot->>auraBridge: 
    auraBridge->>user: login.otp.sms.sent.message: Please insert the code
    user->>auraBridge: 6789
    auraBridge->>auraBot: 
    auraBot->>4p: Aura validates the code
    4p->>auraBot: Returns user data
    auraBot->>auraAuth: Register user
    auraAuth->>auraBot: 200 OK
    alt
        Note left of T&C API: User already accepted authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 200 OK
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    else
        Note left of T&C API: User needs to accept authenticated T&C
        auraBot->>T&C API: Checks terms and conditions
        T&C API->>auraBot: 404 Not found
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.onboarding.terms-and-conditions from redirect intent
        auraBot->>auraBot: authenticates the user and executes T&C dialog
        auraBot->>auraBridge: 
        auraBridge->>user: onboarding:onboarding.auth.welcome
        auraBridge->>user: onboarding:onboarding.auth.privacy
        auraBridge->>user: onboarding:onboarding.auth.terms-and-conditions
    else
        Note left of T&C API: Channel doesn't have terms and conditions config
        auraBot->>auraBridge: Response + Redirect intent
        auraBridge->>user: login.otp.success: Great! you are now signed in
        auraBridge->>auraBot: intent.billing from redirect intent
        auraBot->>auraBot: authenticates the user and executes the billing dialog
        auraBot->>auraBridge: 
        auraBridge->>user: "Here is your billing data"
    end
end

BotResponse settings

Currently, the dialog has a main intent intent.authentication.login and three auxiliary intents: otp-confirm-user-phone-number-dialog, intent.authentication.otp.phone.number and intent.authentication.otp.auth.code. These auxiliary intents are necessary to enable the flow between sub-dialogs.

        {
            "id": "whatsapp-otp-login-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.login"
                }
            ]
        },
        {
            "id": "otp-confirm-user-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.otp.confirm.user.phone.number.dialog"
                }
            ]
        },
        {
            "id": "otp-phone-number-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.phone.number"
                }
            ]
        },
        {
            "id": "otp-sms-auth-code-dialog",
            "triggerConditions": [
                {
                    "intent": "intent.authentication.otp.auth.code"
                }
            ]
        }

Settings

This section lists and describes all the variables the whatsapp-otp-login dialog uses and that can be configured to adapt the environment: