How to play a sequence of digits from a 3CX Call Flow Designer voice app
On this topic
In this article we’ll explain how to create a voice application that reads a sequence of numbers that have been pressed by the caller. Many times we face the need to read out a sequence of numbers. For example, we need to request a number using DTMF and ask the user to confirm whether the number that has been entered is valid, by reading the number back to them. We will use this example to illustrate how to create an application using the 3CX Call Flow Designer (formerly VAD) to do this:
- 3CX CFD: Please, enter your customer code.
- The user enters 1234 using the keypad.
- 3CX CFD: The customer code entered is 1234. To confirm press 1, to re-enter press 2.
Since the reproduction of digits may be something that is required in different parts of the application, that functionality should be encapsulated in a custom component. The CFD can create custom components that can then be reused in different parts of the application.
The project for this application is installed along with the 3CX Call Flow Designer, in folder “Documents\3CX Call Flow Designer Demos”. Let’s start.
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. In this case we’ll name it “PlayDigitsDemo”.
Step 2: Create the custom component
The component that we are creating will receive the sequence of digits as input, and play them one by one. Proceed as follows:
- From the Project Explorer window, right click on the name of the project, and select New Component.
- Change the name of the new component to “PlayDigits”.
- Click on the new custom component “PlayDigits.comp”, and from the Properties window open the “Variables” collection by clicking the button on the right of the “Variables” item.
- Add two variables called “Digits” and “Index”. The Digits variable will be accepting the digits form the user, so this component knows what digits need to be reproduced. The Index variable is internal and allows the component to iterate through the digits. Proceed as follows:
- Click the “Add” button to add a new variable.
- Change the Name property of the new variable to “Digits”.
- The Digits variable should have the following properties:
- Accessibility: ReadWrite
- Initial Value: <blank>
- Scope: Public
- Click the “Add” button to add another variable.
- Change the Name property of the new variable to “Index”.
- The Index variable should have the following properties:
- Accessibility: ReadWrite
- Initial Value: 0
- Scope: Private
- When done, press “OK” to save the changes.
Now that we have created the custom component, we need to design the component internally. To do this, we need a “Loop” component to iterate the sequence of numbers. In the “Loop” component, we will add a “Prompt Playback” component to play the number in that iteration. Within the same loop, we also need another “Increment Variable” component to increase the Index variable we created earlier. This will allow the loop to iterate through all the numbers inputted by the user. Let’s see how this is done in more detail:
Create the Loop
- From the “Components” toolbox, drag a “Loop” component to the designer.
- From the “Properties” window, change the name of the Loop component to “digitsLoop”.
- Select the “digitsLoop” component, and change the Condition property to: “LESS_THAN(callflow$.Index,LEN(callflow$.Digits))”
- This condition will cause that the loop continues iterating as long as Index (callflow$.Index) is less than the length of the sequence of numbers LEN(callflow$.Digits).
Create the Prompt Playback
- In first place, we need to audio files to play each digit. Copy the files “0.wav”, “1.wav”, and so forth to the project Audio folder. We need all the digits, from 0 to 9.
- From the “Components” toolbox, drag a “Prompt Playback” component and drop it into the “Loop”.
- Change the name property of the “Prompt Playback” component to “playDigit”.
- Select the “playDigit” component, and from the properties window, open the Prompt Collection Editor by clicking on the button on the right of the property “Prompts”.
- Click the “Add” button, and change the prompt type to “Dynamic Audio File Prompt”.
- Set the “Audio File Expression” to:
- This expression will take the digit for this specific iteration, and concatenate it to the extension “.wav”. This way, the “Prompt Playback” component will play the desired digit.
- Click “OK” when done.
Create the Increment Variable Component
- From the “Components” toolbox, drag an “Increment Variable” component and drop it into the “Loop”, underneath the “playDigit” component.
- Change the name of the “Increment Variable” component to “incrementIndex”.
- Change the “VariableName” property to the following expression:
The loop will look like in the following screenshot.
The component is ready. Now we need to invoke it from the main flow.
Step 3: Invoking the component to play digits
We have the component to play a sequence of digits ready. Now we can use it in our application. Proceed as follows:
- Open the Main call flow by double clicking on the item “Main.flow” in the “Project Explorer” window.
- Add a “User Input” component to ask some digits from the user. Rename the component to requestInput. Add the prompts as needed.
- In the “Valid Input” branch, add a “PlayDigits” component from the User Defined Components – this is an instance of the component that we have just created.
- Change the name of the “PlayDigits” component to “playEnteredDigits”.
- Select the “playEnteredDigits” component, and change the Digits property to the following expression:
This way, the digits to be played are retrieved from the digits buffer entered by the user. The callflow will look like this:
Step 4: Build and Deploy to 3CX Phone System
The project is ready. We just need to build and upload it to our 3CX Phone System server. To do this:
- Go to “Build > Build All”. The CFD will create the file “PlayDigitsDemo.tcxvoiceapp”.
- Go to the “3CX Management Console > Call Queues”, create a new queue, configure it with name and extension, check the “Voice apps” option, and upload the file created by the CFD in the previous step.
- Save the changes to the queue. The voice app is ready to use. Make a call to the configured extension, enter a number and the app will play it back to you.
In addition to the specific problem solved in this example, it’s important to note how it’s possible to encapsulate common behavior in a user-defined component. This is a very powerful concept that provides several benefits:
- Accelerates app development by having reusable components.
- Simplifies the design of the main callflow, avoiding that the designer grows to a point that it becomes unmanageable.
- Makes the application easier to understand and maintain.
By extending this concept we can create reusable components that allow, for example, playing dates, playing hours, perform the validation of user input in a generic way, and so on.