The VoIPTools Relay software enables remote applications to communicate with the 3CX Call Control API. Applications can send requests to 3CX using our REST API, or subscribe to real-time 3CX events using our “events” API.
The Relay is the only VoIPTools application that is installed directly on the 3CX server. All other VoIPTools applications must be installed on a separate server.
Before proceeding with the installation process, ensure that you have the following prerequisites,
|Linux Console Access:||You must possess root access to your Linux console to initiate the setup program. Make sure you have the necessary credentials at hand, including your 3CX server’s IP address, an administrative user (root), and the corresponding password.|
|Remote Access Tool (e.g., Putty):||Prepare a remote access tool like Putty, which enables you to execute Linux commands from a remote location. This tool will be essential for carrying out necessary operations during the installation process.|
|Firewall Configuration||To establish seamless communication with the Relay from remote locations, it’s imperative to open (port forward) TCP 8801 on your firewall. This port should be directed to your 3CX server. If you rely on the built-in Linux firewall (iptables/nftables), the setup program will endeavor to automatically configure port 8801 for you.|
In scenarios where an alternative firewall solution is employed or a different port is chosen, manual configuration will be needed to ensure remote access to the Relay is appropriately established.
Installing the 3CX Relay for Linux (Debian) #
The only application you install directly on the 3CX server is the Relay. The Relay allows our tools to communicate with the 3CX Call Control API. The remainder of our tools are always installed on a separate Windows server.
You can establish the “voiptools_relay” service with the following series of commands. It involves installing “unzip,” creating directories, downloading and extracting files, configuring permissions, and enabling the service with systemd. This process enables streamlined execution of the “voiptools_relay” service on the Linux system.
- Open your Remote Access Tool, enter your password and press Enter.
- Enter the following to prompt to install the “unzip” file using elevated privileges.
sudo apt install unzip
- Enter the following prompt to change the current directory to the filesystem’s root directory.
- Enter the following prompt to navigate into the “/opt” directory. The “/opt” directory is typically used for installing software packages that are not part of the core operating system.
- Enter the following prompt to create a new directory named “voiptools” within the “/opt” directory using elevated privileges.
sudo mkdir voiptools
- Enter the following prompt to change the current directory to the newly created “voiptools” directory.
- Enter the following prompt to create a new directory named “relay” within the “voiptools” directory.
sudo mkdir relay
- Enter the following prompt to change the current directory to the “relay” directory.
- Enter the following prompt to download a ZIP file named “LinuxRelay-18.4.36.zip” from the specified URL.
sudo wget https://installers.voiptools.com/Downloads/Temp/LinuxRelay-18.4.36.zip
- Enter the following prompt to extract the contents of the downloaded ZIP file using the “unzip” utility.
sudo unzip LinuxRelay-18.4.36.zip
- Enter the following prompt to give executable permissions to the “RelayServicesHost” file, allowing it to run as a program.
sudo chmod +x RelayServicesHost
- Enter the following prompt to navigate to the “/etc/systemd/system” directory, which is where systemd service unit files are typically located.
- Enter the following command to download a service unit file named “voiptools_relay.service” from the specified URL.
sudo wget https://installers.voiptools.com/tmp/voiptools_relay.service
- Enter the following command to let the “voiptools_relay.service” start automatically on system boot.
sudo systemctl enable voiptools_relay.service
- Enter the following prompt to start the “voiptools_relay.service” immediately.
sudo systemctl start voiptools_relay.service
Relay Login: #
To gain access to the Relay, you have the option to log in using either your 3CX Administrator credentials or any 3CX extension possessing 3CX System Admin privileges. If opting for the extension login method, employ your designated 3CX extension number along with your assigned WEB password.
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.
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_r
License Registration Process #
If you have previously registered your Relay, rest assured that your existing licensing information will remain intact. For new installations, please proceed by selecting the appropriate licensing option displayed on the left-side panel.
License Registration #
Follow the procedure to initiate the registration process,
- In the left side panel, click the Register tab.
- Enter your license number in the License Key field and enter other mandatory information. Click the Register button to complete your registration.
Registration Contact Information: #
During the license key registration process, it’s crucial to provide the contact information of the end-user (customer). In scenarios where the purchase was facilitated through a 3CX Reseller, kindly include the Reseller company name as well.
License Key Absence: #
If you do not possess a license key, please be informed that our range of free tools remains accessible for your use. However, it’s important to note that registration with a valid license key is mandatory to access the full functionality of the Relay API.
Settings Tab #
The Services screen is used to configure how the Relay functions. This includes setting the protocol (HTTPS), the IP address the webserver will bind to, and the TCP port number. The IP whitelist is maintained on this screen, and you can turn on/off monitored events and the Swagger (Open API) documentation.
Warning Popup: #
The Warning popup displays immediately when you open the Services menu. You must enter at least one entry in the IP address whitelist. Typically, the only entry needed is the IP address of your VoIPTools server. It is essential, to ensure the security of your Relay, that you limit the devices allowed to communicate with it. This is done by specifying a list of permitted (whitelisted) IP addresses. Requests received from an IP address, not in the whitelist will be rejected.
Click here to learn how to add an IP address to the Whitelist.
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 0.0.0.0, or “localhost” to represent 127.0.0.1. You can also specify IPV6 addresses. You cannot use an FQDN like “pbx.mydomain.com”. Each URL should be separated by a comma.
Typically, it is not necessary to change the default setting. If you make changes to the server bindings, a restart of the Relay may be required.
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.
Access to the Relay is always permitted from localhost. We do not support configuring IP ranges. You must enter at least one IP address in the whitelist.
Below is the recommended setting:
IP Whitelist #
Follow the steps to add an IP to the IP Whitelist,
- In the IP Restriction section, click the New option.
- Enter the IP address in the IP Address field and click the Update option.
You must enter the IP address of your VoIPTools server in the IP Address field.
In most cases, the only device that needs to communicate with the Relay is the Windows server where your VoIPTools applications are installed. We recommend configuring your parameter firewall to reject requests from any other IP address. However, if your firewall does not support this feature, you can easily block access to the Relay using the IP Whitelist.
The Relay IP Whitelist setting is used to identify the computers that are permitted to communicate with the Relay. Requests from any other computer (IP address) will be rejected.
Authorization (JWT) #
To implement JWT authorization, two keys are required:
- The Private Secret Key that is only needed by the Relay,
- The Public Key is used by client applications when requesting a new token.
The secret keys are autogenerated the first time you install the JWT version of the Relay. Typically, it is not necessary to generate new keys. However, if you choose to generate a new public key, the client applications must be updated.
You can copy the keys by clicking the Copy icon.
Automatic software updates #
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
Enable Features #
As a best practice, we recommend turning off the API (Swagger) documentation. Because you can execute APIs right from within the documentation, disabling the documentation when not in use reduces the surface area for hackers looking for vulnerabilities.
The Relay can “publish” 3CX events to client applications using SignalR (WebSockets under the covers). For example, the Relay can publish phone call events, presence status changes, 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 your installed tools. Disabling unused events will reduce the resources required by the Relay.
The Relay logs information about how the application is functioning. Each day a new log file is created automatically. The 7 most recent log files are kept. Older log files are deleted automatically..
To view events for a specific day, select the desired file from the Logs drop down.
API Documentation #
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, expand “API Doc” from the left-hand side panel by clicking on the arrow (>).
We provide support for our APIs to the extent that we can offer suggestions on what methods are available, and how to use them. However, we will not write the application for you. If you would like our help building a custom solution, contact our Support team at Support@VoIPTools.com
REST API #
Our REST API has an extensive list of methods to choose from and includes actions to make phone calls, get a list of active phone calls, create extensions, change a user’s presence status, and much more. The documentation is auto-generated using Open API (Swagger) and is derived directly from our code thus ensuring the documentation is always up-to-date.
SQL API #
In truth, this is not an API, rather, this is a testing tool you can use to determine whether your 3CX server can communicate with your SQL Server. This is important if you are using a 3CX Call Flow Designer (CFD) application that needs database access. To test your SQL connectivity, simple paste your SQL connection string in the field provided and press the Test Connection button.
Common problems connecting to a remote SQL Server are:
- Firewalls are blocking the required ports
- SQL is not configured to permit remote access
- The SQL Browser service is not started
Instructions for configuring SQL Server to permit remote connections can be found
Events API #
The Relay offers a variety of events that your applications can subscribe to in order to be notified of changes or actions. For example, you can set up subscriptions to detect when new calls are made, when presence settings are altered, when calls are placed in a queue, or when recordings are generated.
To help C# .Net developers utilize our events API, we have provided two downloads:
Data and Shared DLLs #
To reduce the complexities of using a REST API, we provide two DLLs that contain class object definitions and methods that you can use to work with our API.
Visual Studio sample project #
To see how to use our DLLs in your project and how to subscribe to events, we provide a sample Visual Studio project that provides a basic example you can use as a starting point for your project.
SSL / TLS Certificate #
The Relay shares the same certificates used by 3CX. It is not necessary to provide separate certificate files for the Relay.
Need Support? #
You get quick answers to most of your inquiries in our online manual. If you prefer direct contact, we offer various support channels, including phone, email, live chat, and our helpful VoIPTools forums.
24/7 Support Availability #
Rest assured, our dedicated team is here to assist you around the clock, every day of the year. Whether you’re based in the USA or India, we’re ready to provide prompt responses to your technical queries.
Windows Event Log for VoIPTools Applications and Services #
For troubleshooting any application errors, our Windows Event Log contains a comprehensive list of error messages, warnings, and informative notes related to all our VoIPTools applications and services. It’s a valuable resource to help you pinpoint and resolve any issues you may encounter.
Real-Time Live Chat Assistance #
Got questions that need immediate answers? Our chat support team is available to assist you in real-time. Just click on the Live Chat button located at the lower right corner of our website, and we’ll acknowledge your queries right away.
Efficient Email Support #
To ensure a thorough understanding of your concerns, feel free to email us at firstname.lastname@example.org. Describe your issue in detail, and we’ll get back to you within one business day with the support you need.
Reach Us by Phone #
If you prefer to speak with a representative directly, you can reach us at +1 801-642-4655. Our attentive team is available to take your calls from 8:00 AM to 6:00 PM (Central Standard Time).
Free Support #
If you’ve purchased our products through a VoIPTools Partner, rest assured that they provide first-level support at no additional cost. Partners have access to 100% free technical assistance and actively participate in the troubleshooting process.
VoIPTools customers enjoy access to our online manuals and receive support through emails (with responses within one business day) and live chat. However, please note that we do not provide remote server login assistance.
Paid Support #
For a more hands-on experience, consider our “Installation Support” package. Our expert support team can log in to your servers, and install and configure all our tools for you. This comprehensive service includes setting up SQL Server Express and Internet Information Server if necessary. We’ll work closely with you to tailor our applications to best meet your specific requirements.
We’re committed to providing top-notch support to ensure your VoIPTools experience is smooth and hassle-free. Contact us today, and let us assist you in making the most of our powerful tools!