3CX to Custom CRM: Integration Without the Template

3CX natively supports Salesforce, HubSpot, Zoho, Freshdesk, and a handful of others. If the CRM is not on that list, or if it is a custom-built system, the integration does not exist out of the box.

But 3CX is built to be connected. Its CRM Template Wizard covers any CRM with a REST API, and the Call Control API enables real-time call event handling for teams that need more than template-based logging. A 3CX custom CRM integration is a documented, achievable build for any CRM with an API layer.

Running 3CX but your custom CRM is not on the supported list? Schedule a 30-minute call and we will scope the CRM Template or Call Control API path for your setup. talk to us

Key Takeaways

• 3CX integrates with any CRM that has a REST API, not just the platforms on its supported list. The CRM Template Wizard generates the integration template from API documentation.
• Two integration paths exist: the CRM Template for contact lookup, call logging, and contact creation; and the Call Control API for real-time call events, screen pop, and bidirectional call control.
• The CRM Template handles four events: inbound contact lookup, contact creation for unknown callers, call logging at call end, and outbound click-to-call.
• The Call Control API uses REST and WebSocket: REST for initiating actions, WebSocket for receiving real-time call events per state change.
• Call logging requires a POST endpoint in the CRM that accepts call data (caller number, agent extension, duration, date/time, call direction) and creates an activity record.
• A 3CX Enterprise licence with 8SC+ is required for the Call Control API. The CRM Template works on lower licence tiers.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don't just solve problems—they transform how people experience your product.

Let's talk

What does a 3CX CRM integration actually do and what does it not do?

A 3CX CRM integration handles four events: inbound contact lookup (caller name displayed before answer), contact creation for unknown callers, call logging at call end (duration, outcome, agent, datetime written to the CRM), and click-to-call from inside the CRM. It does not sync contact data from 3CX to the CRM, store recordings in the CRM directly, or replace a full contact centre CTI solution.

Understanding the scope boundary prevents the most common expectation mismatch in 3CX CRM builds.

• Inbound contact lookup: when a call arrives, 3CX queries the CRM by phone number and pulls the contact name to display in the 3CX Web Client before the agent picks up.
• Contact creation: if the caller number is not found in the CRM lookup, 3CX can create a new contact record automatically so the call log has somewhere to attach.
• Call logging at call end: when the call ends, 3CX sends call data (duration, outcome, date/time, agent extension) to the CRM and creates an activity record linked to the contact.
• Click-to-call: reps dial contacts from inside the CRM with a single click, initiating the call through 3CX without opening a separate dialing interface.

The integration is a telephony-to-CRM data bridge. The CRM remains the system of record for contact and activity data. 3CX is the source of call events.

What are the two integration paths and which one should you use?

The CRM Template handles standard contact lookup, call logging, and click-to-call for any CRM with a REST API. The Call Control API handles real-time screen pop, custom routing driven by CRM data, and complex IVR workflows. The Template covers 80 percent of use cases. The Call Control API covers the rest.

The right path depends on whether real-time events and screen pop are required or whether end-of-call logging is sufficient.

• Path 1 — CRM Template: a JSON configuration file mapping 3CX events to CRM REST API endpoints. Created using the 3CX CRM Integration Wizard. Requires REST API knowledge and CRM API documentation. Works on most 3CX licence tiers. Best for standard contact lookup and call logging to any custom CRM.
• Path 2 — Call Control API: a REST and WebSocket API exposed by 3CX that allows external applications to monitor and control calls in real time. Requires 3CX Enterprise licence with 8SC+. Best for real-time screen pop from the CRM, complex routing driven by CRM data, or custom IVR workflows that query the CRM mid-call.

How to build a 3CX CRM Template for a custom CRM

The 3CX CRM Template is a JSON configuration file built using the CRM Integration Wizard. It maps four 3CX events (inbound lookup, contact creation, call logging, click-to-call) to the custom CRM's REST API endpoints in six steps. The process takes two to three days for a developer with REST API experience.

Step 1: Download and set up the CRM Integration Wizard

• Download the 3CX CRM Template Generator from the 3CX Customer Portal and install it on a Windows machine.
• Launch the wizard and select "New CRM Template" to begin the configuration. The wizard generates a JSON file the 3CX admin console uploads when complete.

Step 2: Configure authentication

• Select the authentication method your CRM uses: Basic auth, API key header, OAuth 2.0, or Bearer token.
• Enter the credentials or token values stored in the template and used for every API call 3CX makes to the CRM. API key header is the simplest choice for server-to-server calls.

Step 3: Configure inbound contact lookup

• Enter the CRM's contact lookup endpoint URL using the [Number] variable: for example, https://yourcrm.com/api/v1/contacts?phone=[Number].
• Map the JSON response fields to 3CX's required contact fields: Contact ID (mandatory), First Name, Last Name, Company, and the URL for the CRM contact record to open on call connect.

Step 4: Configure contact creation (optional)

• Enable contact creation if unknown callers should auto-create a new CRM contact record. This prevents call logs from landing on a null contact reference.
• Enter the CRM's contact creation endpoint (POST) and map the fields 3CX will populate: phone number, first name (defaulted to "Unknown" if not captured), and any other required fields the CRM enforces.

Step 5: Configure call logging

• Enter the CRM's activity creation endpoint (POST) where 3CX sends call data at call end. Available 3CX variables for the POST body: [CallType], [Duration], [DateTime], [AgentExt], [AgentName], [Number], [ContactID].
• Map these variables to the CRM's activity fields: call direction, duration in seconds, call date, agent name, contact linked, and any custom fields the CRM requires for call records.

Step 6: Upload and test

• Export the completed template as a JSON file from the wizard and upload it to 3CX via Admin Console > Integrations > CRM.
• Use 3CX's built-in test functionality to send a test call and verify the contact lookup and call log arrive in the CRM correctly before enabling for all users.

How to use the 3CX Call Control API for advanced CRM integration

The Call Control API connects a WebSocket stream to 3CX that emits an event for every call state change: ringing, connected, on hold, transferred, ended. Each event includes the caller number, the agent's extension, and the call ID. REST endpoints allow the CRM to initiate calls, transfer calls, and query active call state.

This path requires a backend developer with WebSocket experience and a 3CX Enterprise licence with 8SC+.

• API setup: create a client application in the 3CX Admin Console under Integrations > API. The wizard generates a Client ID and API key. The API key is shown only once. Store it immediately.
• Authentication: the external application authenticates using the Client ID and API key to receive a Bearer token. All REST calls and the WebSocket connection use this token.
• WebSocket event stream: connect to wss://[3cx-fqdn]/callcontrol/ws with the Bearer token. The stream emits events per call state change. Each event includes caller number, agent extension, and call ID.
• REST call control: use the REST API to initiate a call from the CRM (click-to-call), transfer a call, or query the current state of an active call. Full endpoint specification is in the 3CX API documentation.
• Common real-time use case: when a call connects (WebSocket event fires), the CRM backend looks up the caller number, opens the contact record in the agent's browser, and starts a call timer on the deal record before the agent says hello.

What CRM API endpoints must be built to receive 3CX data?

The custom CRM must expose three endpoints to support 3CX integration: GET /contacts for phone number lookup (must respond in under 500ms), POST /contacts for unknown caller creation (must return the new Contact ID), and POST /activities for call log receipt at call end. All three must accept the authentication method configured in the 3CX template.

These endpoints are built on the CRM side, not configured in 3CX. If the CRM does not expose them, neither integration path will work.

• GET /contacts?phone=[number] accepts a phone number query parameter, searches the CRM contact database, and returns Contact ID, name, company, and a URL to the contact record. Must respond within 500ms or 3CX may not display the contact name before the agent picks up.
• POST /contacts creates a new contact from the fields 3CX sends for unknown callers and must return the new Contact ID in the response so 3CX can link the call log to the correct record.
• POST /activities (or POST /calls) receives the call log POST from 3CX at call end. Accepts call type, duration, datetime, agent extension, agent name, caller number, and Contact ID. Creates an activity record linked to the contact and, if configured, the relevant open deal.

Build the GET /contacts endpoint first and test it with Postman using a sample phone number in the exact format 3CX will send. If the lookup works in Postman, the template will work in production.

What are the most common 3CX CRM integration problems and how to fix them?

The five most common 3CX CRM integration problems are: phone number format mismatch between 3CX and the CRM, duplicate call logs on transferred calls, contact creation firing on every inbound call, missed calls not logged for queue environments, and call recording URLs not written to the CRM. Each has a specific fix that must be implemented at the CRM API layer.

These problems surface in production and are not visible during initial template testing with a controlled test call.

• Contact lookup returns no result for a known number: 3CX sends the number as dialled (typically +1XXXXXXXXXX or without country code). The CRM must normalise the incoming format to E.164 before querying. Strip non-numeric characters and apply the country code before the database lookup.
• Call log creates duplicate activity records on transferred calls: the call end event fires more than once when a call is transferred between agents. Use the 3CX Call ID as a unique key in the activity creation endpoint and check for an existing record with that ID before creating a new one.
• Contact creation fires on every inbound call including known contacts: the lookup is returning an empty response even for known contacts because the phone number format does not match. Test the lookup endpoint directly with Postman using the exact format 3CX sends before enabling contact creation.
• Missed calls not logged for queue environments: 3CX only logs missed calls when a single extension rings and does not answer. Calls to a queue with multiple agents ringing simultaneously are not reported as missed via the template. Use the Call Control API WebSocket to capture queue-level missed call events if this reporting is required.
• Call recording URL not written to CRM: 3CX does not send recording URLs in the template POST by default. Retrieve the recording URL from 3CX's reporting API after the call ends and write it to the CRM activity record as a second API call triggered by the call log receipt.

Conclusion

Connecting 3CX to a custom CRM is a documented, achievable integration. The CRM Template handles 80 percent of use cases with two to three days of development work. The Call Control API covers the remaining 20 percent where real-time events, screen pops, or custom routing are required.

Before starting the integration, test the CRM's contact lookup endpoint directly using Postman with a sample phone number in the exact format 3CX will send. If the lookup works in Postman, the template will work in production. If it does not, the format mismatch will surface before any 3CX configuration is done.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don't just solve problems—they transform how people experience your product.

Let's talk

Need 3CX integrated with a custom CRM that isn't on the supported list?

The 3CX supported CRM list covers a handful of named platforms. If the CRM is custom-built, the integration does not exist out of the box. But the tools to build it do.

As AI development experts, we at LOW/CODE Agency build custom CRM systems with 3CX integrations: CRM Templates for standard call logging and contact lookup, and Call Control API implementations for real-time screen pop and advanced call workflows. We build and test the CRM-side API endpoints, configure the 3CX template, and handle the phone number normalisation and deduplication issues that surface in every production environment.

With 450+ projects delivered for clients including Zapier, Medtronic, American Express, and Coca-Cola, we know how to build telephony integrations that work correctly the first time.

If you need 3CX connected to a custom CRM that is not on the supported list, schedule a call with LOW/CODE Agency and we will scope the right integration path for your licence tier and use case.