Using the Authentication Component to Validate Customers

Introduction

Many times we need to authenticate callers, asking for an ID and PIN, and then validating them against different data sources. Usually we also need to iterate this procedure, and ask for the ID and PIN again in case of validation failure, until the validation succeeds or we reach a number of retry attempts. We have simplified this procedure to perform all these tasks in a single component. The 3CX Call Flow Designer includes the Authentication component for this!

This guide describes how to use the “Authentication” component to ask for an ID and PIN, and perform the validation using a web service. It also includes info on how to use the “Web Service REST” component for the validation.

💡 Tip: The project for this example application is available via the CFD Demos GitHub page, and is installed along with the 3CX Call Flow Designer in your Windows user documents folder, i.e. “C:\Users\YourUsername\Documents\3CX Call Flow Designer Demos”.

Step 1: Create the Project

First, we need to create a new project. Open the CFD and go to “File” > “New” > “Project”, select the folder where you want to save it, and enter a name for the project, e.g. “Authentication”.

Step 2: Add the “Authentication” Component

We now add the “Authentication” component:

  1. Drag an “Authentication” component from the toolbox, and drop it into the design view of the “Main” callflow. Then select the component added, go to the “Properties” and rename it to “authenticateCaller”.

Authentication component configuration in 3CX CFD

  1. To open the configuration dialog for this component, double-click or right-click on it and select the “Configure” menu option.
  2. Here we have basically 4 settings:
  • Max Retry Count for ID and PIN: the number of times the user may retry entering the ID and PIN after a validation failure.
  • User Input for ID: configure how we collect the digits for the ID.
  • Request PIN: enable this check-box if the component request also a PIN.
  • User Input for PIN: configure how we collect the digits for the PIN.
  1. In this demo application, we ask for ID and PIN. We need to define the prompts to ask for ID and PIN, the prompts to inform that the input is invalid or that no digits were detected. We also need to set the minimum and maximum number of digits to collect for ID and PIN, the stop digit and the valid digits.

Step 3: Validate ID and PIN Using a REST Web Service

The Authentication component has two branches:

  • “Valid Input”: executed when both the ID and PIN are successfully entered. This means that the user entered at least the minimum number of digits expected, but the validation has not been performed yet, so even if we execute the “Valid Input” branch, that doesn’t mean that the ID and PIN are valid.
  • “Invalid Input”: executed when the ID or the PIN were not entered by the user. In this case we may want to play a message for example to explain in more detail what the user needs to enter. In this case we leave the “Invalid Input” branch empty, so when the user enters an invalid ID and PIN pair, the component automatically retries asking for ID and PIN, until the Max Retry Count is met.

In the “Valid Input” branch we need to perform the validation using the “Web Service REST” component, which supports different authentication methods out of the box:

Authenticate Caller flow in 3CX CFD

  1. Drag a “Web Service REST” component from the toolbox and drop it into the “Valid Input” branch. Then select the added component, go to the “Properties” and rename it to “validateCustomer”.
  2. To open the configuration dialog for this component, double-click or right-click on it and select the “Configure” menu option.

Web Service REST component configuration in 3CX CFD

  1. Here we need to configure our Web Service REST component, as follows:
  • URI: this is an expression that returns the web service endpoint, e.g.: "https://webservice.example.com/validation"
  • Request Type: the HTTP method used for the validation, in this case we use POST.
  • Content Type: this field describes what we have in the Content field. It could be JSON, XML, or any other content type we need. We can also specify a value which is not in the list, to do that we just type the value we want. For this demo we use “application/json”.
  • Content: this is an expression to build the actual content. In this demo we create a JSON string using the CONCATENATE function to create the authentication content, e.g.:

{"id":"12345","pin":"67890"}

Our CONCATENATE expression is:

CONCATENATE("{\"id\":\"",authenticateCaller.ID,"\",\"pin\":\"",authenticateCaller.PIN,"\"}")

Note that we use the variables “authenticateCaller.ID” and “authenticateCaller.PIN”, which hold the values entered by the user in the Authentication component.

  • Finally, we configure Basic Authentication and we set the username and password from callflow variables.

Step 4: Check Validation Result and Pass to Authentication Component

The Authentication component has a “Validated” property. We need to set this to true if the validation succeeds, to stop the the Authentication component asking for ID and PIN again when the “Valid Input” branch ends.

To do this, we can use a “Create a Condition” component:

  1. Drag it from the toolbox and drop it below the “Web Service REST” component we added in the previous step.
  2. Rename it to “checkValidationResult”, configure the component with 2 branches and name them “validated” and “not_validated”.
  3. Set the “Condition” for the “validated” branch to the following expression to check if the web service returned the number “1” as validation result:

EQUAL(validateCustomer.ResponseContent,"1")

  1. In the “validated” branch set the variable “authenticateCaller.Validated” to true and transfer the call to the Support department extension, as the customer is validated.
  2. In the “not_validated” branch we just play an error message, so the Authentication component can retry asking ID and PIN.

Valid Input flow in 3CX CFD

In this example, consider the above “Valid Input” branch of the callflow.

Authenticate Caller flow in 3CX CFD

Finally, after the Authentication component, add another “Transfer” component, but in this case, transfer the call to sales. This Transfer component is executed when the Authentication component has consumed all the retry attempts and the validation did not succeed.

Step 5: Build and Deploy to 3CX Phone System

The project is ready to build and upload to our 3CX Phone System server, with these steps:

  1. Select “Build” > “Build All” and the CFD generates the file “Authentication.zip”.
  2. Go to the “3CX Management Console” > “Advanced” > “Call Flow Apps” > “Add/Update”, and upload the file created by the CFD in the previous step.
  3. The Call Flow app is ready to use. Make a call to it to test this app.

See Also

Last Updated
This document was last updated on 29th August 2021
https://www.3cx.com/docs/cfd-validate-customers/