3CX Relay Agent for Windows User Guide

1.Introduction #

The new 3CX Relay Agent for Windows is used by VoIPTools products to communicate with 3CX either locally or in the cloud. 3CX permits one 3rd party application to communicate with the 3CX server at a time. To overcome this limitation, VoIPTools created the 3CX Relay Service. The Relay is a lightweight application that is installed directly on the 3CX server. The Relay exposes the 3CX Call Control API via a REST-based API, as well as phone system events using SignalR. The Relay manages requests and events between VoIPTools products and 3CX. The Relay also makes it possible to install our VoIPTools products on a remote server (including over the internet).

1.1. What are the Benefits?

1. Offers a streamlined approach to calling the 3CX Call Control APIs.

2. Creates an abstraction layer to insulate VoIPTools products from changes made by 3CX.

3. Allows VoIPTools products to run on a remote server separate from the 3CX server.

4. Enforces a consistent approach to integrating with 3CX.

5. Reduces the time required to develop custom 3CX integrations through code reuse.

6. Encrypts authentication between VoIPTools and 3CX.

7. Provides an easy-to-use REST API for developing custom integrations with 3CX

1.2. What’s New?

* Supports cross-platform support for both Windows and Linux

* Provides an easy-to-use REST API for developing custom integrations with 3CX

1.3. How does it work?

3CX Relay Agent is used in combination with other VoIPTools products. The agent accepts multiple connections from VoIPToys products while making a single connection to 3CX.

1.4. How often should you install it?
When you upgrade 3CX to a new FULL version, you must upgrade the Relay too. If you have already installed the Relay for your version of 3CX, you need not install it again unless a newer version of the Relay is required by a newer VoIPTools add-on.

2.Prerequisites #

Before installing the 3CX Relay Agent for Windows, you need to ensure that your computer meets the minimum requirements mentioned below:

1. .Net 4.7.2 or above

2. 3CX Version 16 (Windows)

3. Windows 10 or above / Windows Server 2012 or above

4. Latest version of VoIPTools product

3.Installation #

Download software

You can download the Relay from our website at http://www.voiptools.com.


Install Prerequisites

There are a number of prerequisites that must be installed prior to installing the 3CX Relay Agent For Windows.


Install 3CX Relay Agent

This User Guide contains step-by-step instructions to successfully install the 3CX Relay Agent for Windows.  Begin by extracting the installer from the downloaded zip file (Step 1 above), then run the setup program named RelaySerivcesInstaller.exe

3.1.Step by step Installation Procedure #

The following section guides you through a detailed walk-through of the installation process.

Step 1: Download the 3CX Relay Agent for Windows

You can visit online at http://www.voiptools.com and download the free utility.

Step 2: Login to 3CX Server

VoIPTools applications interact with 3CX through the VoIPTools 3CX Relay Service. The Relay MUST be installed directly on the server where 3CX is installed.

Step 3: Extract the installer from the downloaded .zip file

The file you downloaded in the above step is a compressed .zip file.

1. Position the mouse on the zip file and right-click.

2. From the popup menu, select Extract All to extract the software.

Step 4: Start the installation process

1. From the extracted folder, find the file RelayServicesInstaller.exe

2. Double-click the file to start the VoIPTools Installer.

3. Click Next to continue.

Figure 1: Installation in progress

4. When the software installation is complete, click Close.

Figure 2: Installation Complete

3.1.1. Register Your License
When the installation is complete, the setup program will display a message with the URL needed to access the web-based Relay administration console. Your URL should be something similar to the following:


Replace <3cx-server-ip> with the IP address of your 3CX server, or FQDN.

If you previously registered your Relay, the existing licensing information will be preserved. For new installs, select the licensing option from the left-side panel. Enter your license information and press the “Register” button. If you do not have a license key, you can still use our free tools. To access the Relay API, you must register with a valid license key.

When registering your license key, the contact information should be the end-user (customer). Be sure to include the Reseller company name if purchased through a 3CX Reseller. When complete, press the “Register” button to activate your license key. Note: It is not necessary to restart the Relay after registering your key.

Figure 3: Register License

3.1.2. Services
The Relay can be configured to respond to an IP address or FQDN (or both), and you can change the default port used (not recommended). Typically the default settings are sufficient, but you can use the “Server Bindings” field to define the URLs accepted by the Relay/REST API.  You can enter multiple URLs separated by a space.  For example: http://mydomain.com:8800

To change these settings, select “Services” from the left-hand side panel. After making changes to either the server bindings or port, it is necessary to restart the Relay. You can restart the relay by pressing the “Restart” button. Note: Restarting the Relay during production hours will temporarily stop the sending of events to client applications. Use wisdom when choosing a time to restart the Relay.

Figure 4: Services

4.Support #

Visit our website to access our on-line manuals and receive quick answers to most of your questions. Otherwise, you can contact us by phone, email, live chat and on the VoIPTools forums.

• Support Hours (USA and India)

Our team is ready to assist you with answers to your technical questions, during normal business hours, which is Monday through Friday, 8:00 AM to 6:00 PM (Central Standard Time), and 8:00 AM to 12:00 AM (Indian Standard Time).

• Windows Event Log (Applications and Services ? VoIPTools)

The Windows Event Log lists various errors, information messages and warnings related to all our VoIPTools applications and services. The data here can be used for troubleshooting various application errors.

• Forums

Our forum is intended for VoIPTools customers to collaborate on real-life challenges, solutions and best practices. You can participate on our forum at: https://www.voiptools.com/community/

• Submit a Bug

If you suspect a bug in any of our VoIPTools products, you can bring it to our notice by reporting your issue at: https://www.voiptools.com/report-a-bug/

• Live Chat

Our chat support team is ready to acknowledge your queries in real-time. You can start a live chat with us by simply clicking on the Live Chat button at the lower right corner of our web page.

• Email

You can email us at: support@voiptools.com. Be sure to describe your issue in detail. We’ll get back to you within one business day of receiving your request.

• Phone

You can call us at +1 801-642-4655 to reach a representative. VoIPTools will accept calls at this number from 8:00 AM to 6:00 PM (Central Standard Time).

• Support Services

Free Support:

If you purchased our products through a VoIPTools Partner, your Partner will provide first level support. Partners have access to 100% free technical support, provided they participate actively in the troubleshooting process.

VoIPTools customers have access to our on-line manuals and we will respond to emails (next business day) and live chat, but we will not login to your servers remotely.

Paid Support:

If you purchase “Installation Support’ our support team can login to your servers and install and configure all our tools for you. This includes installing SQL Server Express and Internet Information Server if required. Our team will work with you to configure our applications to best meet your needs.

Help Guide Powered by Documentor
Suggest Edit

Get the Best Solution for your Business

Whether through one of our commercial products, or a custom solution built to meet your specific needs, we can help you get the most out of your 3CX investment. Call us today!

Contact Us