The 3CX Voice Application Designer allows simple access of web services. It is only necessary to enter the URI, the name of the web service to invoke and eventually the list of parameters to send.
Creating the Application with the VAD
First, you must create a new project. Open the VAD and go to “File -> New -> Project”, select the folder where you want to save it, and choose a name for the project. In this case we’ll name it “WebServiceTest”.
Our application will request a customer code, which will be validated against a web service. To do this add an element of type “User Input” by dragging it from the toolbox and dropping it into the Callflow, then rename it to “requestPIN”. Set the message that will be played by the component to request the PIN using the properties window. Assuming that the customer code has 10 digits, set the properties MaxDigits and MinDigits to the value 10.
When the user enters a valid 10 digit value, the execution will continue in the “Valid Input” branch of the component requestPIN. There we will make the validation of the customer code.
To do that, add a component of type “Web Services Interaction” by dragging it from the toolbox and dropping it into the “Valid Input” branch mentioned above. Rename the component to “validatePIN” and double click on it to open the component configuration dialog. Complete the fields as follows:
- In the “URI” field, enter the URI to the web service as a constant string expression (adding single quotes). For example: ‘http://localhost:8080/ValidationWebService.asmx’. This URI will be invoked from the PC where you have installed 3CX Phone System, so note that when using localhost it will try to access that computer. The value must be entered with quote marks if this is a constant string, because the field is an expression.
- In the “Web Service Name” field, enter the name of the web service to invoke, adding single quotes if you need to use a constant string expression. For example, ‘ValidatePIN’. The value must be entered with quote marks if this is a constant string, because the field is an expression.
- The 30 seconds value for the Timeout can be left or changed if you consider it convenient.
- Finally, we need to add a parameter to the parameters list: the PIN code entered by the user. This parameter will be sent to the web service. Enter “CustomerPIN” for the name, and the expression “requestPIN.Buffer” for the value, i.e. the digits entered by the user.
Now that the web services interaction component is properly configured, we must verify the value returned and decide whether to accept the customer code or not. This requires using a “Conditional” component with 2 branches, one for the case of successful validation and one for the case of validation error.
Add the Conditional component by dragging it from the toolbox, and change its name to “validateWebServiceResult”. Then rename the two branches as “success” and “error” in the case of successful and failed validation respectively. The main flow should look as pictured below:
In order to execute the “success” branch, the web service should return a value of 1 indicating that there is a record with the code entered by the customer, i.e. the following condition must be fulfilled, which should be set for that branch using the Expression Editor:
Once this condition is configured, the only thing left to do is to add the messages to play in each case (success or error), and transfer the call to an operator in the case of successful validation.
Implementing the Web Service
In this case we’ll implement the web service using C# on Visual Studio 2008, but other tools can also be used. To do this, open Visual Studio 2008 and go to “File -> New -> Project”, select “Visual C# -> Web -> ASP .NET Web Service Application”. Enter the name of the web service “ValidationWebService”. Rename the web service added by default from “Service1” to “ValidationWebService”. Change the method “HelloWorld” renaming it to “ValidatePIN”, returning an integer value and receiving a string with the PIN entered by the user. The code should look like this:
[WebService(Namespace = “http://tempuri.org/”)]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
public class ValidationWebService : System.Web.Services.WebService
public int ValidatePIN(string customerPIN)
return customerPIN == “1234567890” ? 1 : 0;
With that sample implementation, the web service will validate the PIN “1234567890”, and reject any other PIN value.
Note that to invoke the web service, the VAD sends a web request using the POST HTTP method. If the web service is created with the .NET framework, as in this example, and if it is necessary to access it remotely (for example, if 3CX Phone System is installed on computer A and the web service is installed on computer B), then you will need to explicitly enable the HTTP POST protocol in the web service configuration file “web.config”. To do this, add the following configuration settings:
This occurs by default. The HTTP POST protocol is only enabled when accessing the web service from the same machine.
Downloads & Documentation
- Download 3CX Voice Application Designer 12: http://downloads.3cx.com/downloads/3CXCallFlowDesigner.exe
- Check out the 3CX VAD User Manual: https://www.3cx.com/manual/3CXVADManual.pdf
- Give us your feedback and comments in the 3CX VAD Forum and on our Facebook Page.