Last updated: 23 May 2026.

To integrate 3CX with a CRM, you need 3CX v18 build 11 or later (v20 preferred) on a paid annual licence with call recording enabled, plus a dedicated 3CX API user holding the Recording Manager and Reports User roles per the 3CX user roles documentation. The Call Control API, documented in the 3CX API reference, is the surface a bridge talks to. Transcription is v20-only, on the higher tier.

Why version and roles matter more than the licence tier name

3CX licence tier names change over the years. The two settings that actually decide whether a CRM bridge works are the API surface and the user roles, not the marketing tier name. A v18 build 11 or later PBX with the right roles will work with any 3CX-aware bridge. A higher-tier licence with the wrong roles will not.

The reference below organises by what the integration needs, not by what 3CX calls the tier this quarter.

Version: v18 or v20

3CX v18 is the minimum supported version for a stable Call Control API integration. v20 is the current generation and is recommended for new builds. Both expose the Call Control API; v20 adds transcription support and a broader reporting surface, per the 3CX v20 release notes.

Direct answer: if you are integrating today, target v18 build 11 or later as a floor and plan to be on v20 within the next twelve months. The Call Control API surface is stable across both.

Roles: Recording Manager and Reports User

The single most common DIY failure mode is creating a 3CX API user with the Reports User role only. That user can read call history but cannot fetch the recording file, and the bridge returns calls without audio.

The working configuration is one dedicated 3CX API user with both roles assigned: Recording Manager (for the recording fetch endpoints) and Reports User (for the call history endpoints). These are listed as separate permission sets in the 3CX documentation because they cover different scopes.

Three role configurations and what they do

• Recommended: Recording Manager and Reports User on one dedicated API user. Reads call history, fetches recordings, low blast radius if the credentials leak (the user has no other privileges).
• Works but risky: System Administrator. Has everything the bridge needs and far more. If the credentials leak, the attacker has the keys to the PBX. Avoid on production builds; acceptable for a quick test only.
• Will fail: Reports User on its own. Reads call history, returns 401 or 403 on the recording fetch. Calls appear without recordings. Common DIY mistake.

The role configuration is the first thing to check when a bridge returns calls without recordings. We cover the practical setup in the five-minute setup guide.

Hosted versus self-managed versus PBX Express

3CX runs in three hosting modes. All three support the Call Control API, with one note on PBX Express.

• Self-managed (your own server or VPS). Full API access, full role control, no hosting-mode restrictions on the bridge. Most flexibility.
• Hosted (3CX provides the cloud instance). Full API access. The PBX behaves identically to self-managed from the bridge's perspective.
• PBX Express (3CX's free hosted starter). Call Control API available with a bearer-token constraint on certain endpoints, documented in 3CX support notes. A productised bridge handles the token rotation; a DIY build needs to read the documentation carefully.

For agencies whose sub-accounts vary across all three modes, the bridge should abstract the differences so a single CRM workspace can pull calls from a mix of hosted and self-managed PBXs.

Licence tier: annual or higher with recording enabled

3CX licences come in several tiers. The detail varies by year; the categorical statement that holds is: any paid annual tier with call recording included will support a CRM bridge. Free PBX Express and trial licences may have restrictions on simultaneous calls or feature flags; check the current 3CX pricing page for live numbers.

Self-contained answer per tier:

• PBX Express (free): API access works with the bearer-token note above. Recording may be limited; check the current PBX Express feature list. Acceptable for testing the bridge, not for production sales floors.
• Small Business annual: Call Control API and recording included. The Recording Manager and Reports User roles can be assigned. Bridge works.
• Professional and Enterprise annual: Full API surface, full recording features, full role control. Bridge works with no constraints.
• v20 highest tier: Adds transcription on top of the above. Transcription is fetched alongside the recording by a bridge that supports it.

What 3CX does not require for a CRM bridge

A short list of things people sometimes worry about that do not apply.

• No on-premise installer on the CRM side. The bridge runs as a marketplace app or hosted service; it does not need software installed on a server inside the customer's network.
• No VPN to the PBX. The 3CX Call Control API is HTTPS-reachable on the public internet at the PBX's hostname. No tunnel is needed.
• No SBC change. The bridge does not sit in the call path. It listens to events after the call ends; the SBC and the PBX continue to handle audio and signalling unchanged.
• No firewall changes for outbound calls. Inbound from the bridge to the 3CX API is the only network direction that matters, and it is an HTTPS GET from a known IP range. The bridge documentation lists the IPs to allowlist if your firewall enforces strict outbound rules.

Evidence sandwich: what 3CX itself documents

3CX maintains its API documentation publicly. The relevant references for the statements above:

• The Call Control API exposes call events (started, ended, missed) and recording fetch endpoints; see the 3CX API reference.
• The Recording Manager and Reports User roles are listed as separate permission sets in the 3CX user roles documentation, which is why both are required for full bridge functionality.
• v20 introduces native call transcription on the higher tier; v18 does not have native transcription, per the v20 release notes.

Read together, these three documents support the practical rule of thumb: v18 build 11 or v20, both roles, paid annual tier, and the bridge works.

What changes when 3CX itself updates

3CX issues build updates regularly. Two patterns to watch for that affect a CRM bridge.

• Field renames on the call event payload. v18 and v20 differ in a handful of field names on the call event payload. A DIY bridge needs to handle both shapes; a productised bridge handles the normalisation for you.
• Recording URL shape changes. Across 3CX builds, the recording URL format has changed twice in the last three years. A bridge that hard-codes the URL pattern breaks on update; a bridge that follows the API-provided URL handles it.

For agencies running multiple 3CX builds across sub-accounts, the abstraction in a productised bridge is the practical reason not to maintain a custom build.

How Connect Zero handles the licence and version variation

Connect Zero supports v18 build 11 onwards and v20 across hosted, PBX Express and self-managed. The bridge handles the field-name and URL-shape differences in code; the agency does not configure for version. The role configuration is the only manual step on the 3CX side: create the API user, tick the two roles, paste the key into the marketplace install. We document the step-by-step setup and the full licence requirements reference.

If a sub-account is on a 3CX build older than v18 build 11, the path is to upgrade 3CX first. Plan for an hour of downtime and the standard 3CX upgrade procedure; an Auswide VAR engineer can walk a sub-account through it on a shared screen.

Frequently asked questions