The 3CX Voice Application Designer is a powerful tool that allows you to easily create voice applications (IVR) by dragging functional blocks to a visual design interface. This makes it possible to create powerful applications without the need for programming or telephone technology skills.
One of the most common questions that we get asked is how to validate a customer within an application built with 3CX Voice Application Designer. In this series of articles we will show you how you can setup this validation using the following different data sources:
- Web Service
- XML File
- CSV Text File
- Microsoft Excel Spreadsheet
- SQL Server Database
- Microsoft Access Database File
- Another Database via ODBC
To start off, we’ll create the application callflow, which is independent of the chosen data source. Then we will create separate user components to access validation data in different ways to validate a customer.
Description of the Application to Develop
The application that we will develop will allow customers with a support contract to access the help desk department, while the rest will be referred to the sales team for assistance.
To begin with we will create an initial menu where customers have two choices:
- Enter the customer ID and PIN.
- Transfer the call to the sales team.
If the customer selects option 1, they will be prompted to enter the customer ID and PIN, then the information entered can be validated against different data sources. If the validation is successful, the call will be transferred to the help desk department. If the validation fails the customer will be offered the option of re-entering the information (in case he made a mistake) for it to be re-evaluated, or the option to be transferred to the sales team to get assistance in recovering their password.
The application that we will create, in addition to implementing a solution to this problem, will also show how to make them easier to understand and maintain through the use of user components.
Creating the Application Callflow
Step 1 – Creating the Project
We will begin by creating a new project. To do this open the 3CX Voice Application Designer, go to File > New > Project, select the folder that you want to save the project in, give the project a name, in this case “PhoneSupportPortal”, and click “Save” to create it. The main callflow Main.flow will be opened automatically.
Step 2 – Defining Variables
We will next define the following variables of the project, which will help us to have a point of parameterization:
- SalesTeamExtension: will be the sales group extension.
- HelpDeskExtension: will be the help desk group extension.
To create the project variables follow the next steps:
- In the Project Explorer, select the “project” node in your case it is the PhoneSupportPortal.
- In the Properties window below the project explorer, click the button to the right of the “Variables” property.
- The Variable Collection editor will be opened. You will now add the two variables mentioned earlier:
- SalesTeamExtension, i.e. assign the value 100.
- HelpDeskExtension, i.e. assign the value 101.
- Click “Add” and a new variable with default data in its properties will appear
- Click the field next to the “Name” variable and type in “SalesTeamExtension”
- Click on the field next to the “InitialValue” and type in “100” .
- Press ok and repeat the process again to add HelpDeskExtension to the variable connection
Step 3 – Creating the Main Menu
After you have defined the necessary variables it’s time to create the main menu. We mentioned earlier that the plan is for the customer to have two options:
- To enter the customer ID and PIN and to be connected with the support team.
- To be transferred to the sales team.
To create the main menu,
- Drag a “Menu” component from the toolbox to the left side of the design surface and drop it between the green circle (which denotes start) and the red square (denoting stop).
- Click the menu component to go to the Properties window which appears to the right side of the screen, to set some of its values. Click the field next to the “(Name)” of the component
(which should be “menuComponent1”) – and type in “MainMenu”. Ensure that options IsValidOption_1 and IsValidOption_2 are enabled (set to “True”).
- Configure the timeout and retries (MaxRetryCount) according to your needs. In this example we’ll leave the default values, i.e. wait for DTMF input for 5 seconds and allow up to 3 retries (i.e. 4 total attempts).
Now it is time to configure the menu prompts. First, we want to play a welcome message that will be heard only the first time the customer accesses the menu, but not in the retries, (for example after entering an invalid digit). To do this, we need to record the following audio messages and copy the files into the Audio folder within the project:
- welcome.wav: “Welcome to 3CXPhone Support.”
- main_menu_options.wav: “If you have a Customer Support ID and PIN number, please press 1. Otherwise, please press 2 to leave a voicemail, for the Sales Team to assist with password recovery.”
- timeout.wav: “We didn’t receive any digit, please try again.”
- invalid_digit.wav: “The selected option is not valid, please try again.”
Once audio files are in the Audio folder of the project, we have to configure the InitialPrompts, SubsequentPrompts, InvalidDigitPrompts and TimeoutPrompts properties for the menu components. The message defined in the InitialPrompts property will be played the first time a customer enters the menu, while during retries the messages played will be the ones defined by the SubsequentPrompts property. In the case of the SubsequentPrompts property having nothing defined, the callflow will always play the messages defined in the InitialPrompts property.
To set the prompts, click on the MainMenu in the design surface, go to the Properties window that will appear in the right side of the screen, scroll down to the Prompts section and click on InitialPrompts. Click the little icon that will appear at the end of the row.
This will open the Prompt Collection editor. In this case we need to define two pre-recorded audio messages. To do this add 2 messages of type AudioFilePrompt, as shown in the following screenshot.
For the first message rename it to “welcome” and choose the file welcome.wav from the dropdown list. For the second message rename it to “mainMenuOptions” and choose the file main_menu_options.wav from the dropdown list. Click OK to save the changes.
To define the messages that are played during retries, where the welcome message must not be reproduced, go to the properties window and click on the button to the right of the property SubsequentPrompts. In this case a different editor will be opened, which allows you to define at what retry number a set of messages is activated. That is, you can define a set of messages for the first retry, and a totally different one to the next. In this case we will define a single set of messages for all retries. To do this press the Add button in the editor. We will see the following:
The property MinTryCount allows us to define at what retry number this set of messages is activated. For example, if this value is 1, these messages are played in the first retry. But if the value is 2, the messages played during the first retry are defined in the property InitialPrompts, and these messages will only be played in the second and further retries. This allows to change the messages as the user makes a mistake in the selection, for example to provide additional information about the option to select, when we see that the user fails to enter a valid option with the instructions received in the previous iteration.
To fulfill the messages to play in the retries, let’s leave the value of MinTryCount to 1 and then click on the button to the right of the property Prompts. Add a single message of type AudioFilePrompt, rename it to “mainMenuOptions” and select the audio file main_menu_options.wav from the dropdown list.
We just need to configure InvalidDigitPrompts and TimeoutPrompts properties. The procedure is identical as for SubsequentPrompts, i.e. it is possible to define different sets of messages for different retries. Thus, the error message may be different the first time the user enters an invalid option (eg “the entered option is invalid”) and the second (eg “Please pay attention to the options, you entered an invalid option again”).
Now configure the file timeout.wav for the property TimeoutPrompts and the file invalid_digit.wav for the property InvalidDigitPrompts, just as we did for SubsequentPrompts.
Step 4 – Transferring the Call to the Sales Team
Now that we have the menu component ready, we need to define what needs to be done in each of the possible output branches. We defined that when the user presses the Option 2, should be transferred to the sales team.
To do this, add an element of type “Transfer” within the branch of option 2. In the properties window change the name to TransferToSales.
Press the button to the right of the “Destination” property to define the expression for the destination number of the transfer. In the expression editor options select Variable, and then locate the variable that we defined for the project and we named SalesTeamExtension.
If the customer does not enter any options in the menu, or enters an invalid option, and exceeds the maximum number of retries, we will also transfer the call to the sales team so that the customer can be assisted. To do this, repeat the steps above but placing the new “Transfer” component in the branch “Timeout or Invalid Option”.
Step 5 – Creating the Login Component
When the user presses the menu option 1, we must ask him/her to enter his/her credentials. We will do this in a user component. This way we simplify the main flow diagram and make it easier to read and maintain.
To create the new component, go to the Project Explorer and right click on the project name. Select the “New Component” option to create an empty component, and change the name to “Login”. Double-click the component to open it.
Within the Login component we need to do the following:
- Ask the user to enter his/her customer ID.
- Ask the user to enter his/her PIN.
- Validate the information using an external data source.
- If validation is successful, transfer the call to the help desk team, and otherwise offer to re-enter the customer ID and PIN. We could allow for example retry up to 3 times.
To ask the customer ID to the user, we will use a User Input component. Drag the component from the toolbox to the design area and rename it requestCustomerID.
Assuming the customer code should be between 5 and 10 digits, modify the properties MaxDigits and MinDigits properly. Then configure the messages in the same way we did for the main menu.
If the user enters invalid data or no information at all, we’ll transfer the call to the sales team. To do this we will use a Transfer component and will configure it as we saw in previous steps. Prior to the transfer, we can play a message to the user to inform that we are transferring the call to the sales team. The User Input component will look like this:
Next we’ll do something very similar to ask for the PIN. Add another User Input component just below the previous, and rename it to requestCustomerPIN. Then properly configure the prompt messages and valid digits. We will have something like the following:
Now that the user has entered the customer ID and PIN, we need to validate this information using an external data source. We will do this validation in a new component, which will be empty for the moment. In the next article in this series we will implement this component for different data sources.
To create the new component, go to the Project Explorer, right-click the project name and select “New Component”. Rename the component to “ValidateData”. Open the component to define the properties that will become its interface:
- An input variable on which we will specify the CustomerID entered.
- An input variable on which we will specify the CustomerPIN entered.
- An output variable which will return the validation result: successful or failed.
After opening the new component named ValidateData, go to the properties window and click the button to the right of the Variables property. Define the three variables mentioned: CustomerID, CustomerPIN and ValidationResult. The three properties will have ReadWrite access and Public Scope. We can leave the initial value empty, as it will be completed at runtime.
Now that we have the skeleton of the validation component, we can use it inside the Login component. To do this, open again the Login component and drag the ValidateData component from the toolbox and drop it below the second User Input component. Change the component name to validateData and set the properties CustomerID and CustomerPIN from the properties window, specifying the variables requestCustomerID.Buffer in the first case and requestCustomerPIN.Buffer in the second.
We just need to verify the result of the validation. To do this we need to use a Conditional component that allows us to take different paths based on the conditions that we define. Add a Conditional component below the validation component and change the name to checkValidationResult. In the first branch we’ll check if the validation result is successful, so that we will change the name of the branch to isSuccess, and configure the Condition property to the following expression, which can be easily created with the Expression Editor:
Finally, within the first branch, we’ll transfer the call to the help desk, after playing a message telling the user about this transfer.
When the validation is not successful, execution will continue in the second branch of the Conditional component. Let’s rename this branch to isError. Now we just need to implement the logic to retry the login procedure if validation fails. For that we need to iterate through the components we just created, and to achieve this we will use a Loop component. To prevent the user from looping indefinitely, we’ll restrict the number of iterations to 3. This is achieved by defining a private component variable with an initial value of 0, which will be increased into the isError branch, i.e. every time there is a validation error.
To create the variable, go to the Project Explorer, select the Login component and then in the properties window click the button to the right of the Variables property. Add a variable named loopCount and set the initial value to 0, the Scope to Private and the Type to ReadWrite. Then within the isError branch of the Conditional component at the end of the diagram, add a new Increment Variable component, and specify that the variable to increment is “callflow$.LoopCount”. Rename the component to incrementLoopCount.
The last step is adding the Loop component. Drag it from the toolbox and drop it at the beginning of the diagram. Rename the component to loginLoop and enter the following expression for the Condition property:
Now select all the other components within the Login component and drag them into the Loop component. Remember that you can select multiple components using the Ctrl key.
Validating the Customer Information Using External Data Sources
Now that we have the callflow of the application ready, we need to perform the validation using external data sources. To do this, we must implement the ValidateData component that we have left empty for now. In the next articles, in this series, we will show how to do this validation with the following data sources:
- Web Service
- XML File
- CSV Text File
- Microsoft Excel Spreadsheet
- SQL Server Database
- Microsoft Access Database File
- Another database through ODBC
The Second part of the series Creating a phone support portal with 3CX VAD – Part 2 shows how to perform the validation using a Web Service.