3CX Voice Application Designer (VAD) is a tool that allows 3CX users to easily create voice applications. Using the predefined functional blocks, you can easily design the call flow graphically, without requiring any programming skills. This article will illustrate how to create a voice application which reads out a sequence of numbers that have been pressed by the caller.

Introduction

Many times, we are faced with 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 the number that has been inserted by reading the number back to him. We will use this example to illustrate how to create an application using VAD to do this:

  1. VAD: Please, enter your customer code.
  2. The user enters 1234 using the key pad.
  3. VAD: 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. VAD can create custom components that can then be reused in different parts of the application.

Overview

In this article, we'll show how to create a custom component to reproduce digits, and how to use that custom component in another part of the application - in this case in the main call flow. To do this, we need to follow these steps: Step 1: Create a custom component, which loops through the digits and plays them back to the user. Step 2: Add the component to the main call flow. Step 3: Build the new voice application and deploy it to 3CX Phone System. Let’s get started!

Step 1: Creating the Custom Component

The component that we need to create must be able to receive the sequence of digits as input, and play them one by one. Proceed as follows:

      1. From 3CX Voice Application Designer, create a new project.
      2. From Project Explorer, right click on the name of the project, and select New Component.
      3. Change the name of the new component to “PlayDigits”. PlayDigits Component
      4. Double Click on the new custom component “PlayDigits.comp”.
      5. From the Properties window, open the “Variables” Collection by clicking the button on the right of the "Variables" item. PlayDigits properties
      6. 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"
        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. For this, we need a component of type "Loop" to iterate the sequence of numbers. In the "Loop" component, we will add a component of type "Prompt Playback" to play the number in the iteration. Within the same loop, we also need another component of type "Increment Variable" 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

      1. From "Components", drag a "Loop" component to the "Call Flow".
      2. From the "Properties" window, change the name of the Loop component to “digitsLoop”.
      3. Keeping the "digitsLoop" component selected, change the Condition property to:  LESS_THAN(callflow$.Index,LEN(callflow$.Digits)).
      4. This condition property will cause 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. Before you create the PromptPlayback component, you need to copy prompts which will be used to the Audio folder of the project with the corresponding name. Thus for example the prompt "0" should be called 0.wav, “1” should be called 1.wav. this should be done for all numbers between 0 and 9.
      2. Back to the project, from "Components", drag a "Prompt Playback" component to the "Loop".
      3. Change the name property of the "Prompt Playback" component to “playDigit”.
      4. Keeping the "playDigit" component selected, open the "Prompts Collection" from the properties window.
      5. Click on the arrow next to the "Add" button, and select to add a "DynamicAudioFilePrompt".
      6. Change the "AudioFileName" of the new "Dynamic Audio File Prompt" member, to: CONCATENATE(MID(callflow$.Digits,callflow$.Index,1),'.wav').
      7. This will cause the "Prompt Playback" component to retrieve the wav file for the digit that needs to be read out.
      8. Click "OK" when done.

Create the Increment Variable Component

      1. From "Components", drag an "Increment Variable" component underneath the "playDigit" component.
      2. Change the name of the "Increment Variable" to “incrementIndex”.
      3. Change the "VariableName" property to "callflow$.index".

The following screenshot shows the end result: PlayDigits Component - before it is inserted in Main Flow We have the component ready. Now we just need to invoke it from the main flow.

Step 2: Invoking the Component to Reproduce Digits

Now that we have the component that allows us to play a sequence of numbers, we can use it into our application. Proceed as follows:

      1. Open the main call flow by double clicking on the item "Main.flow" in the "Project Explorer".
      2. Add a component of type "User Input" to request some digits from the user.
      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. Keeping the "playEnteredDigits" component selected, change the Digits property to: "requestInput.Buffer".

This indicates that that the digits to be played are to be retrieved from the digits buffer, which are the digits pressed by the user.   You should see something like the following:  Main Flow VAD

Step 3: Build and Deploy to 3CX Phone System

Now that the project is ready, you can build it from the Build menu. There are three different build options:

      • Debug Build: builds only the debug configuration. When you deploy this build, you can debug real calls to the callflow of the application.
      • Release Build: builds only the release configuration. Use this build for production environment, because it is more performant than the debug build.
      • Build All: builds both debug and release configurations.

After building the project with success, you can deploy it to 3CX Phone System. To do this, go to the menu option "Build" > "Deploy" and the deployment dialog will appear. Here you can select the configuration to deploy (debug or release) and perform the deployment by clicking the "Deploy" button. If you're deploying the project to a different machine (remote deployment), i.e. 3CX Phone System is installed in another PC, then you will need to change the 3CX Phone System configuration files to allow remote access to the configuration service. The user manual explains how to do this in detail.

Conclusion

In addition to the specific problem solved by this example, we should also note how certain common behaviors into an application can be encapsulated within a user-defined component. This is a very powerful concept that gives us several benefits:

      • It allows the development of applications faster by having reusable blocks.
      • Simplifies the design of the main callflow, and avoids that the drawing grows to a point where 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.