How to Play a Digit Sequence from a Call Flow

Introduction

This guide describes how to create a call flow app 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 use this example to illustrate how to create an application using the 3CX Call Flow Designer (formerly VAD) to do this:

1. 3CX CFD: “Please, enter your customer code”.
2. The user enters 1234 using the keypad.
3. 3CX CFD: “The customer code entered is 1234”.

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.

💡 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. “PlayDigitsDemo”.

Step 2: Create the Custom Component

To create the component to receive the digit sequence as input and play back the sequence, use these steps:

1. From the “Project Explorer” panel, right-click on the name of the project, and select “New Component”.
2. Change the name of the new component to “PlayDigits”.

3. Click on the new custom component “PlayDigits.comp”, and from the “Properties” open the “Variables” collection by clicking the button on the right of the “Variables” item.

4. In the “Variable Collection Editor” add two variables called “Digits” and “Index”. The “Digits” variable accepts the digits from 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:

1. Click the “Add” button to add a new variable.
2. Change the Name property of the new variable to “Digits”.
3. The Digits variable should have the following properties:

• Accessibility: ReadWrite
• Initial Value: <blank>
• Scope: Public

4. Click the “Add” button to add another variable.
5. Change the Name property of the new variable to “Index”.
6. The Index variable should have the following properties:

• Accessibility: ReadWrite
• Initial Value: 0
• Scope: Private

7. 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 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 allows the loop to iterate through all the numbers provided by the user. To see how this is done in more detail:

Create the Loop

1. From the “Components” toolbox, drag a “Loop” component to the designer.
2. From the “Properties”, change the name of the “Loop” component to “digitsLoop”.
3. Select the “digitsLoop” component, and change the Condition property to:

4. This condition causes the loop to continue iterating as long as Index (
   callflow$.Index
   ) is less than the length of the sequence of numbers
   LEN(callflow$.Digits)
   .

Create the Prompt Playback

1. First, we need the audio files to play each digit. Copy the files “0.wav”, “1.wav”, and so forth from your 3CX installation, to the project Audio folder. We need the WAV files for all the digits, from 0 to 9.
2. From the “Components” toolbox, drag a “Prompt Playback” component and drop it into the “Loop”.
3. Change the name property of the “Prompt Playback” component to “playDigit”.
4. Select the “playDigit” component, and from the “Properties”, open the “Prompt Collection Editor” by clicking on the button on the right of the property “Prompts”.

5. Click the “Add” button, and change the prompt type to “Dynamic Audio File Prompt”.
6. Set the “Audio File Expression” to:

7. This expression takes the digit for this specific iteration, and concatenate it to the extension “.wav”. This way, the “Prompt Playback” component plays the desired digit.
8. Click “OK” when done.

Create the Increment Variable Component

1. From the “Components” toolbox, drag an “Increment Variable” component and drop it into the “Loop”, underneath the “playDigit” component.
2. Change the name of the “Increment Variable” component to “incrementIndex”.
3. Change the “VariableName” property to this expression:

Consider the loop as in the example call flow above. The component is now ready and 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 and now we can use it in our application:

1. Open the Main call flow by double clicking on the item “Main.flow” in the “Project Explorer” panel.
2. Add a “User Input” component to ask some digits from the user. Rename the component to requestInput. Add the prompts as needed.
3. 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.
4. Change the name of the “PlayDigits” component to “playEnteredDigits”.
5. 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. Consider the example callflow above.

Step 4: 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 “PlayDigitsDemo.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, enter a number and the app plays it back to you.

Conclusion

In addition to the specific problem solved in this example, it is important to note the ability 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.

Extending this concept, we can create various reusable components, e.g. play dates or hours, perform generic validation of user input, etc.

See Also

• Learn more about CFD components.
• Automated Telephone Ordering Voice app with CRM integration via the 3CX API.
• Sending emails from a CFD voice app.
• Routing Calls Based on the Time of Day.
• Using the Authentication Component to Validate Customers.
• Using the Credit Card Component.
• Text to Speech with the 3CX Call Flow Designer.
• Using the Loop component to navigate upwards
• Registering and making callbacks
• Using the survey component
• Using the CRM Lookup component
• See how to integrate your PBX with a CRM via the 3CX API.

Last Updated
This document was last updated on 29th April 2021
https://www.3cx.com/docs/cfd-digit-sequence/