VoIPTools Relay
Connect your own software
to 3CX.
The VoIPTools Relay lets your applications send requests to 3CX through a REST API and subscribe to real-time 3CX events. It is also how VoIPTools add-ons connect to your phone system.
- REST API documented in Swagger
- Real-time events over SignalR
- Windows and Linux versions
What your software can do
Send commands to 3CX and get live events back.
The Relay gives your applications two ways to work with 3CX: a REST API for requests, and real-time events as they happen.
REST API
Send requests
Your software gets a token with the Relay's public key, then sends REST requests over HTTPS. Some of what it can do:
Uses a registered license key. Every method is listed in the Relay's Swagger documentation.
Real-time events
Receive events
Connect over SignalR, and your software hears about 3CX activity as it happens:
Most events are on by default, and you can turn off the ones you do not need. Real-time events need a paid license key.
The REST API screen in the Relay. Each method is documented, and you can run it from here for testing.
Security and upkeep
Control who connects, and keep it up to date.
The Relay's settings live in its web console, which only 3CX system owners and administrators can sign in to.
- IP whitelistLimit the Relay's API and web console to the addresses you list. Changes apply right away.
- Your 3CX certificateThe Relay uses the TLS certificate 3CX manages, and can restart itself at a set time after the certificate is renewed.
- Automatic updatesChecks for updates every day and installs them at the time you choose.
- LogsA new log file each day, with the seven most recent kept.
For developers
Built to make integrations easier to write.
Swagger documentation
Generated from the code, so it stays current. Run methods from it for testing.
JWT over HTTPS
Request a token with the public key, then send it with each API request.
.NET SDK
Handles the token and the web request for you, so one line of code can fetch an extension's details.
Code samples
C# samples for real-time events and for REST calls without the SDK.
Everything in VoIPTools Relay
- REST API into the 3CX Call Control API
- Real-time 3CX events over SignalR
- Swagger (OpenAPI) documentation, which you can turn off
- JWT authorization over HTTPS
- Uses the TLS certificate 3CX already manages
- IP whitelist for the API and web console
- .NET SDK and C# code samples
- SQL test screen for checking a connection to an external SQL server
- Daily automatic updates at the time you choose
- A log file for each day, seven days kept
- Sign-in limited to 3CX system owners and administrators
- Windows and Linux (Debian) versions
Install the Relay, then add a license key for the API.
You can install the Relay and use its documentation and code samples without buying a subscription. The REST API needs a registered license key, and real-time events need a paid one. Ask us which key fits your setup.
- 3CX version 20. Relay 20.9.34 is for 3CX V20 Update 9, and 20.7.34 is for Updates 7 and 8. Upgrade the Relay when you upgrade 3CX to Update 9
- Installed directly on your 3CX server (the only VoIPTools software installed there). Windows and Linux (Debian) versions are available
- For Linux: root access to the 3CX server's console and a remote access program such as PuTTY
- TCP 8801 (the default) open or forwarded on your firewall to the 3CX server
- Access to keymanagerV3.voiptools.com on port 83 for license registration and notifications
- HTTPS: the Relay uses JWT and does not accept unencrypted HTTP connections
- A registered license key to use the REST API and real-time events
Check the documentation for the current release and full setup details for your environment.
20.9.34July 17, 2026+
- New: a Relay update indicator on the login screen, to check for and install Relay updates before signing in.
- New: presence events for temporary status changes, including when a temporary status expires and reverts to the default profile.
- Fixed: the AI Voice Service no longer starts a new call while already on an active call.
June 24, 2026+
- New: updated the TransferCall2 API integration for compatibility with 3CX Update 9 (GET: /api/TransferCall2/{json}).
- Fixed: the Relay was not sending new voicemail notifications for certain voicemails.
- Fixed: VoIPTools AI Voice was not playing prompts correctly in 3CX Update 9 environments.
May 26, 2026+
- New: a popup with brief new-feature information on the first login after an update.
- New: support for running in 3CX Update 9 RC environments.
- New: the transcription API checks the installed 3CX version before processing requests, and blocks or warns if it is unsupported.
- New: a CreateExtensionByTemplateExtension option to choose whether a created extension inherits the template's department.
- Fixed: default role and department assignment in the Create Extension API (POST: /api/Extensions/{json}).
- Fixed: duplicate new-voicemail notifications after upgrading 3CX.
- Fixed: cleanup and notification when 3CX moves voicemail files to external storage.
- Fixed: calls from the VoIPTools AI Service are registered in 3CX ActiveConnections again, restoring barge-in.
May 19, 2026+
- New: transcription API version validation.
- New: department inheritance control for template extensions.
- Fixed: role and department assignment during extension creation.
- Fixed: duplicate voicemail notifications after 3CX upgrades.
- Fixed: voicemail delete event handling and synchronization.
- Fixed: ActiveConnections synchronization for incoming calls.
April 10, 2026+
- New: Personal Contacts API for managing and accessing personal contacts.
- New: Event Control API to turn events on or off as needed.
- New: CFD Version API to retrieve Call Flow Designer version details.
- New: compatibility with 3CX v20 Update 8A.
- Fixed: calls did not drop when redialing external numbers with special characters (for example +!).
- Fixed: call handling in a paging ring group with multiple users.
- Fixed: On Call Manager "heard" events were not received, affecting voicemail processing.
- Fixed: PJSIP configuration issues after restarting the Relay service.
January 16, 2026+
- Fixed: improved calendar and holiday APIs for better data consistency and scheduling support.
- Fixed: token refresh timing now uses UTC to prevent time-based sync issues.
- Fixed: duplicate GUIDs when creating extensions from templates.
- Fixed: the GetExtensionByNumber API for extensions not assigned to any group.
- Fixed: call control API issues, for reliable transfer and listen operations.
November 7, 2025+
- New: VoIPTools AI Voice Service integration for audio services.
- Fixed: deleting holidays with special characters in the department name.
June 25, 2025+
- New: APIs for the new 3CX V20 Update 6 tables.
- New: an API to get an extension's default department.
- Fixed: Exporter date and time data now uses UTC instead of the server's local time.
- Fixed: turning subscriptions to 3CX general and registration events off and on.
May 2, 2025+
- Fixed: the new Observer role and access permissions.
- Fixed: folder permissions when creating folders through the API.
- Changed the field length for History ID in preparation for V20 Update 6.
March 25, 2025+
- Added a new MoveFiles API.
February 25, 2025+
- Various minor bug fixes and improvements.
January 27, 2025+
- Various minor bug fixes and improvements.
December 11, 2024+
- Fixed an issue that prevented the latest certificate information from being retrieved, causing the Relay to fail.
- API code changes.
- Fixed a problem caused by a change in a 3CX method signature that was breaking APIs for creating and updating extensions and for login.
- Fixed a login issue where security measures caused failures with the Web Client password, by adding encryption.
November 20, 2024+
- Only system owners and users with admin rights can now log in to the Relay.
- Fixed an issue that prevented the latest certificate information from being retrieved, causing the Relay to fail.
- Fixed a problem caused by a change in a 3CX method signature that was breaking APIs for creating and updating extensions and for login.
- Fixed a login issue where security measures caused failures with the Web Client password, by adding encryption.
- Other minor API changes.
September 25, 2024+
- Fixed an issue that prevented some users from registering their Relay.
- Minor code changes.
September 12, 2024+
- Fixed a certificate issue.
- Fixed "Free Mode" appearing when the licensing database was reset.
- Fixed multiple events coming through when voicemails were re-recorded.
- Added an API for retrieving all voicemail files.
- Fixed the watcher not sending events correctly. Users need to turn this on.
- Fixed null events when extensions were marked as favorites.
July 19, 2024+
- Fixed an issue that prevented On Call Manager from authenticating its license key through the Relay.
- Added a new API for extension updates and for checking the connection between 3CX and the VoIPTools server.
April 23, 2024+
- The Relay now uses the TLS certificate managed by 3CX, so no separate certificate is needed for Relay communications.
- On startup, the Relay scans the standard 3CX locations for .pem certificate and key files and uses them to encrypt communications with client applications.
- Because it uses JSON Web Tokens (JWT), the Relay requires HTTPS to authorize access to the REST APIs and does not support unencrypted HTTP.
- Certificate files can be updated manually with the Update buttons. If 3CX keeps certificate files in non-standard locations, enter their full path in the Certificates section.
- The Relay requires both crt and key files and does not support other certificate file types. Restart the Relay to use an updated certificate.
January 24, 2024+
- Contacts now support extended characters.
- Fixed an issue that prevented some users from validating their passwords.
- Verified the APIs for creating extensions: Post(extensions) and CreateExtensionByTemplateExtension.
- Updated validation messages on the login screen.
January 17, 2024+
- Initial v20 release.
Questions
VoIPTools Relay questions, answered.
Anything else? Our team answers 24/7 from the USA, India and the Philippines.
Who is the Relay's API for?+
Developers and 3CX partners who want their own software to work with 3CX: placing calls, reading active calls, creating extensions, changing presence or reacting to live events. No developer on your team? VoIPTools also offers custom development.
Where is it installed?+
Directly on your 3CX server. It is the only VoIPTools software installed there; VoIPTools add-ons run on a separate server and connect through it. There are Windows and Linux (Debian) versions.
Do I need a license key?+
You can install the Relay and use its documentation and code samples without buying a subscription. To use the REST API, you register a valid license key, and real-time events need a paid license key. Ask us which key fits your setup.
How is it secured?+
The REST API uses JWT tokens and requires HTTPS, with the TLS certificate 3CX already manages. An IP whitelist limits which devices can reach it, only 3CX system owners and administrators can sign in, and three failed sign-ins lock the console for 15 minutes.
We do not use .NET. Can we still use it?+
The C# sample walks through each step without the SDK: requesting a JWT token, making the REST request and handling the JSON that comes back, as a guide for other languages.
Which Relay version do I need?+
Relay 20.9.34 for 3CX V20 Update 9, and 20.7.34 for Updates 7 and 8. When you upgrade 3CX to Update 9, upgrade the Relay too.
Got a question?
Talk to the team that builds VoIPTools Relay.
Whether it is VoIPTools Relay, another add-on, or a custom solution built around your needs, we can help you get the most out of 3CX.
- Sales@VoIPTools.com
- +1 801 642 4655
- Live chat and 24/7 support
Already a customer? For help with an install or an issue, email Support@VoIPTools.com.
Keep exploring
More add-ons for admin and integration.
REST API / Relay and every add-on below come in the same VoIPTools Subscription.
Browse all 35 add-onsAdmin and integrationExporterAutomatically copy 3CX call records and data into SQL Server, MySQL or PostgreSQL for your own reporting.See the add-on Admin and integrationMonitorTrace any call step by step through menus, queues, transfers and voicemail to see exactly what happened.See the add-on Admin and integrationHosted BillingPull extension counts and storage use from every hosted 3CX system for monthly billing, without logging into each one.See the add-on
Put 3CX to work inside your own software.
Download the Relay and explore its documentation and code samples, or see it on a live demo. The REST API and real-time events need a registered license key.