The VoIPTools Relay makes it possible for applications to communicate with the 3CX Call Control API (running on the 3CX server) from anywhere on the internal network or over the public internet.


Linux Console Access

You will need root access to your Linux console to run the setup program. You will need your 3CX server IP address, an administrative user (root), and a password.


You will need a remote access program such as Putty to issue Linux commands.


To enable our tools to remotely communicate with the relay, you will need to open (port forward) TCP 8800 on your firewall, pointing to the 3CX server. If you use the built-in Linux firewall (iptables), the setup program will attempt to open port 8800 for you. If you use a different firewall or select a different port, you will need to configure your firewall to provide remote access to the Relay.

3.Installing the 3CX Relay for Linux (Debian)

The only application you install directly on the 3CX server is the Relay.  The Relay makes it possible for our tools to communicate with the 3CX Call Control API.   The remainder of our tools are always installed on a separate Windows server.

i). Download and run the setup program

Once you have installed 3CX and have access to the Linux console, you can download the Relay setup program directly to your Linux server. There are essentially 3 steps to install the Relay:

If you are upgrading, be sure to look at the steps in Upgrade Relay section before continuing.

1. Download the setup program with the following command

sudo wget https://installers.voiptools.com/Downloads/18.4/3CXRELAY/LINUX/setup-18.0.4

Figure 1: Download Setup Program

— Wait until the setup program downloads successfully.

Figure 2: Setup Program Downloaded Successfully

2. Give execute permissions to the setup program by entering this command

sudo chmod +x setup-18.0.4

Figure 3: Give Execute Permissions to Setup Program

3. Execute the setup program with the following command

sudo ./setup-18.0.4

Figure 4: Execute Setup Program

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.

Figure 5: URL for Accessing Web-Based Relay Administration Console

ii). Relay Login

To access the Relay, you can login with either your 3CX Administrator credentials, or with any 3CX extension that has 3CX System Admin rights.  To login with an extension, use your 3CX extension number and WEB password.


Figure 6: Voiptools Relay login

  You can obtain your web password by editing your extension in the 3CX web console.

You are permitted 3 attempts to login to the Relay console successfully.  After 3 unsuccessful attempts, the Relay console will be locked FOR ALL USERS for the next 15 minutes.

Login Failed

  The only way to clear a failed login before the 15 minute lock out period, is to reboot the Relay service.  You can restart the Relay from a secure shell session with the following commands:

systemctl stop voiptools_relay.service
systemctl start voiptools_relay.service

iii). Register your license key

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 7: Register License

iv). 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: https://mydomain.com:8801

Figure 8: Services

• Web Server Bindings

The Relay’s built-in web server (Kestrel) only binds to IP addresses, not to domain names (with a few exceptions). You can use “*” to represent, or “localhost” to represent You can also specify IPV6 addresses. You cannot use a FQDN like “pbx.mydomain.com”. Each URL should be separated by a comma.

If you wish to secure the Relay using SSL/TLS, all you have to do is ensure one of the URLs specified uses “https”. Remember if you want both http and https support, you will need at least two entries each with their own port number (see example below).

Default value: http://*:8800,https://*:8801

• Instructions to Create SSL (Secure Socket Layer) Connection

1. In the 3CX Console Management, navigate to Dashboard and then in the Information section, click the IP link.

Figure 9: 3CX Console Management: Dashboard

2. In the Network Settings page, click Public IP tab.

3. In the Select Network Card Interface dropdown list, copy the default internet facing IP Address

Figure 10: 3CX Console Management: Dashboard: Public IP

4. In the 3CX Relay Agent, navigate to Services and then in the Server Bindings field, beside existing value, type comma(,) and then type the value in following format:

https://< internet facing IP Address>:<8801> , where ‘8801’ is the relay port number.

Figure 11: 3CX Relay Agent: Services

5. Click Restart.

6. In the 3CX Console Management, navigate to Dashboard and then in the Information section, click the FQDN link.

Figure 12: 3CX Console Management: Dashboard

7. In the Network Settings page, click FQDN tab and in the Fully Qualified Domain Name field, copy the FQDN name.

Figure 13: 3CX Console Management: Dashboard: FQDN

8. Open browser and in the address bar, type the url in following format and hit enter to open ‘3CX Relay Agent’ through SSL connection:

https://<FQDN Name>:<Relay Port>

Figure 14: SSL URL

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.

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.

v). Update Time

The Relay Auto-Update service checks for software updates daily. If an update is found, the service will download the latest available Relay and install the update.

You can enter the hour and minute that the service checks for updates. Pressing the “Start” button saves your settings and starts the service. To disable the service, simply press the button to stop the service.

The “Hour” field assumes a 24-hour clock. For example, to configure the service to perform updates at 5:00 P.M., enter 17 in the hour field.Default Value: Disabled, 23:59

Figure 15: Update Time

vi). IP Restrictions

As a security measure, it is prudent (where feasible) to limit what devices can access your Relay. Normally you would restrict what IP addresses are permitted to communicate with your relay at your firewall. However, if your firewall does not support this feature, or you do not know how to implement this feature in your firewall, you can easily implement this restriction at the Relay.

By restricting what IP addresses can communicate with the Relay, you block hackers access even if they obtain passwords and authorization tokens. If you enable this feature, only the authorized IP addresses will be able to access the Relay. At this time we do not support entering ranges of IP addresses.

Figure 16: Enable IT Restriction

To authorize an IP address (device) to access the Relay, press the “New” button. You can also edit or delete existing entries using the “Edit” and “Delete” buttons.

Regardless of configured IP address restrictions, we do allow access to the Relay from localhost.

vii). IP Enable 3CX Events

The Relay can “publish” 3CX events to client applications using SignalR (websockets under the covers). The Relay can publish phone call events, as well as file events (new recordings, voicemails, and CDR files). These events are enabled by default, but can be disabled at the recommendation of VoIPTools support if not needed by any of the tools you have installed. Disabling unused events will reduce the resources required by the Relay.

Figure 17: Update Events

4.Upgrade Relay

Upgrading the relay is as simple as running the setup program again (see the section above). The setup program deletes the existing Relay (while preserving any settings) and downloads and installs the latest Relay. However, there are a few details to consider.

If you have downloaded the setup program previously, you will want to delete the old setup program. To see if a previous version is already downloaded, login to your Linux console and run the following command:

ls setup8

Figure 18: Check if previous version already exists

This command displays a list of existing files at your current location on disk.

To delete a previous version of the setup program, run this command

rm setup8

Figure 19: Delete previous version of setup program

When updating the relay, the setup program will display a warning message explaining that the previous version of the Relay and logs will be deleted. Press “y” to confirm:

Continue? [y/n] : y

Figure 20: Press ‘y’ to delete previous Relay and logs

After pressing ‘y’ the setup program will immediately begin the setup process. It will capture your existing Relay settings, remove the existing Relay, download and install the latest available relay, and restore your previous settings.

You can configure the Relay to check for updates daily. Enter the desired hour (24 hours) and minute to check for updates. To start the service press the “Start” button. If the service is running, press the “Stop” button to disable the service.

5.REST / RPC / SignalR / WebSockets

The Relay includes an extensive API you can use to build your own custom 3CX integrations. In fact, all our tools use this same API to communicate with 3CX. For API documentation, select API from the left-hand side panel.

6.Secure Socket Layer (SSL) Certificate

Coming soon!

We plan to add support for an SSL Certificate in the future so you can add additional security when communicating with the 3CX server through the Relay.


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 and we now offer 24/7, 365 days a year.

• 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.

Our team is ready to assist you with answers to your technical questions and we now offer 24/7, 365 days a year.

• 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.

Suggest Edit