Skip to content

ATTENTION EXISTING USERS!

We recently moved our website to a new hosting platform, and because we do not save credit card information on our servers, all users must re-enter their credit card information as soon as possible to avoid any service disruption. Users can update their payment information here.

Support@VoIPTools.com

+1 801 642 4655

24/7 Support

  • Home
  • Tools
    • Features
    • Downloads
    • Manuals
  • Hosting
  • Partners
  • Webinars
  • Contact Us
  • Blog
  • My Account
Menu
  • Home
  • Tools
    • Features
    • Downloads
    • Manuals
  • Hosting
  • Partners
  • Webinars
  • Contact Us
  • Blog
  • My Account
Subscribe
×

Tools

  • 3CX Queue Notifier (Client) V18
  • Auto Voicemail V18
  • 3CX Barge Messages
  • Caller ID V18
  • Call Router V18
  • Competitive Wallboard V18
  • Custom Presence V18
  • Enhanced Billing Codes V18
  • Exporter V18
  • Hosted Billing V18
  • Monitor V18
  • On Call Manager V18
  • Emergency Notifier V18
  • Power Dialer V18
  • Profile Manager V18
  • Queue Notifier (Server) V18
  • Queues Wallboard V18
  • Reception Console V18
  • Recording Beep V18
  • Do Not Call V18
  • Recording Manager V18
  • Auto Call Back V18
  • Auto Self ID V18
  • Auto Logout V18
  • Auto Call Back V18
  • Surveyor V18
  • Audio Scheduler V18
  • Agent Greeting V18
  • Active Directory Sync V18
  • Survey Creator V18
  • Voicemail Manager V18
  • Wrapup Codes V18 (Server)
  • Click-to-Call V18
  • Holiday Importer V18
  • Wrapup Codes V18 (client)

3CX Relay

  • Relay V18 (Windows) JWT
  • Relay V18 (Windows) SP5
  • Relay V18 (Linux) JWT
  • Relay V18 (Linux) SP5

Prerequisites

  • Microsoft SQL Management Studio
  • Microsoft SQL Server Express
  • Home
  • Docs
  • 3CX Relay
  • Relay V18 (Windows) JWT

Relay V18 (Windows) JWT

Table of Contents
  • Introduction
  • What's new? JWT!
  • Prerequisites
  • Installing the 3CX Relay for Windows
  • Relay Login
  • License Registration
  • Services Settings
    • Web Server Bindings
    • IP Whitelist
  • Authorization (JWT)
    • Automatic software updates
    • Enable Features
    • Logs
  • Upgrading the Relay
  • API Documentation
    • REST API
    • SQL API
    • Events API
      • Data and Shared DLLs
      • Visual Studio sample project
    • SSL / TLS Certificate
  • Need Support?
    • Contact Us
    • Support Hours
    • Event Logs
    • Email
    • Live Chat
    • Phone Support
    • Submit a bug

Introduction #

The VoIPTools Relay is a software application that 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.

Figure 1: VoIPTools Architecture

Note: 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.

What’s new? JWT! #

The VoIPTools Relay is a software application that 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.

Want more information about how we use JWT? Take a look at our prerecorded JWT webinar here

Prerequisites #

Firewall

To enable our tools to remotely communicate with the Relay, you will need to open (port forward) TCP 8801 on your firewall, pointing to the 3CX server. If you use the built-in Windows firewall, the setup program will attempt to open port 8801 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.

Installing the 3CX Relay for Windows #

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.

1. Download the Windows Relay installer from the VoIPTools website here

2. Double-click on the downloaded installer to start the install process.

Figure 3: SmartScreen

3. Click on “More info” link

Figure 4: SmartScreen – Run anyway

4. Press “Run anyway” button to continue the installation.

Figure 5: Windows Installer – Welcome

5. Press “Next” to continue the installation process

Figure 6: Windows Installer — Ready

6. Press “Install” to begin the install process.

Figure 7: Windows Installer — Installation path

7. Press “Next” to continue

Figure 8: Windows Installer — Installation Progress

8. If you are upgrading a previous version of the Relay, you may see the following screen:

Figure 9: Windows Installer — Files in use

9. Select to automatically close the applications and press “OK”

Figure 10: Windows Installer — Finish

10. Press the “Finish” button to complete the installation of the Relay.

Relay Login #

The Windows installer will create an icon on your desktop. Double-click on the icon to open your browser and display the Relay login screen. This icon links to the following URL

http://<3cx-server-ip>:8801

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

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 11: VoIPTools Relay login

Note: 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.

Figure 12: VoIPTools Relay failed login
Figure 13: VoIPTools Relay failed login

Note: 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:

License Registration #

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 14: Register license key

Note: You should have received an email containing your license key shortly after placing your order

Services Settings #

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 as well as the Swagger (Open API) documentation.

Web Server Bindings #

Figure 15: 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 a FQDN like “pbx.mydomain.com”. Each URL should be separated by a comma.

Note: 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.

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.

Note: 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:

https://0.0.0.0:8801

IP Whitelist #

Figure 16: White list

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) #

Figure 17: JWT Public and Privae keys

To implement JWT authorization, two keys are required: (1) a private secret key that is only needed by the Relay, and (2) a public key that 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 will need to be updated.

Automatic software updates #

Figure 18: Software auto-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.

Note: 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 #

Figure 19: Update event state

Note: 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 the tools you have installed. Disabling unused events will reduce the resources required by the Relay.

Logs #

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 our kept. Older log files are deleted automatically..

Note: To view events for a specific day, select the desired file from the Logs drop down.

Figure 20: Relay logs

Upgrading the Relay #

There are three ways you can upgrade the Relay:

  • Enable automatic updates
  • Click on the Relay version number in the upper right-hand corner of the home screen
  • Manually run the setup program again.

Running the setup program again deletes the existing Relay (while preserving any settings) and downloads and installs the latest Relay.

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

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 (>).

Note: 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

Note: 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? #

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

Contact Us #

Email:Support@VoIPTools.com
Live Chat:VoIPTools.com
Phone:+1 801-642-4655

Support Hours #

We are now available 24/7 365 days a year



Event Logs #

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.

Note: For Windows events look in the Windows event viewer under: “Applications and Settings / VoIPTools”

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. Be sure to include the following information:

  • 3CX Server:
    • Operating system (Windows / Linux)
    • 3CX version number
    • 3CX Edition (Startup / Pro / Enterprise)
    • License size (simultaneous calls)
  • The VoIPTools applications you have installed (including version numbers)
  • The version number of your Relay
  • Description of your issue

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.

Phone Support #

Our USA phone support is available Monday – Friday 8:00 a.m. to 5:00 p.m. CST. All other times, phone support is provided by our team in Deli and Hyderabad India.

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/

Note: be sure to include the same information required for email support (see above)

What are your Feelings
Still stuck? How can we help?

How can we help?

Updated on January 18, 2023
Relay V18 (Windows) SP5

Powered by BetterDocs

Table of Contents
  • Introduction
  • What's new? JWT!
  • Prerequisites
  • Installing the 3CX Relay for Windows
  • Relay Login
  • License Registration
  • Services Settings
    • Web Server Bindings
    • IP Whitelist
  • Authorization (JWT)
    • Automatic software updates
    • Enable Features
    • Logs
  • Upgrading the Relay
  • API Documentation
    • REST API
    • SQL API
    • Events API
      • Data and Shared DLLs
      • Visual Studio sample project
    • SSL / TLS Certificate
  • Need Support?
    • Contact Us
    • Support Hours
    • Event Logs
    • Email
    • Live Chat
    • Phone Support
    • Submit a bug
Logo - 3CX Platinum Partner
Logo - 3CX Advanced Certified

Navigation

  • About
  • Tools
  • Subscribe
  • Contact
  • Support
  • Product Downloads
  • Product Manuals
  • My Account
  • Partner Sign Up
  • Custom Development

Contact Us

  • Support@VoIPTools.com
  • Billing@VoIPTools.com
  • Live Chat
  • +1 801 642 4655
  • 4464 Glenwillow Dr. Batavia, OH 45103

COPYRIGHT © 2022 VOIPTOOLS. ALL RIGHTS RESERVED | PRIVACY | TERMS OF USE 

Cleantalk Pixel
×
×

Cart