3CX Integration

The connect_3cx module connects Odoo to an existing 3CX V20 PBX through 3CX's server-side CRM integration. 3CX keeps full ownership of numbering, routing and phones; Odoo receives contact lookups and call journals and offers click-to-call through the 3CX Web Client.

How it works

You download a CRM template (an XML file generated by Odoo with your instance URL and a shared API key baked in) and upload it to the 3CX Admin Console. From then on the 3CX server calls Odoo on every external call:

• at call arrival — a contact lookup: the caller's name from Odoo appears in 3CX clients, with a link to the partner form (screen pop);
• at call end — a call journal: the call lands in the Connect ledger (Connect → Calls) with direction, answered/missed status, duration, agent and queue. If your 3CX license produces recordings, transcriptions or summaries, their references are stored on the call;
• on request — agents can create an Odoo contact for an unknown caller directly from the 3CX client.

Click-to-call from Odoo opens the 3CX Web Client dial URL in a new tab — the call is placed by the user's own 3CX client and appears in the ledger when it ends.

1. Install the module

Install connect_3cx like any Odoo addon. On install a random webhook API key is generated automatically.

2. Configure Connect → 3CX → Configuration → Settings

Odoo must be reachable from the 3CX server over HTTPS (the generated template uses the connect.api_url system parameter).

3. Download and upload the CRM template

1. Click DOWNLOAD CRM TEMPLATE in the settings form — you get odoo_connect_3cx.xml with the URL and key pre-filled.
2. In the 3CX Admin Console open Integrations → CRM, add/upload the template and select Odoo Connect.
3. Check the parameters (Odoo URL, API Key, journaling and contact creation toggles) and use the 3CX Test button to verify the lookup — the Last Contact Lookup stamp in Odoo should update.

3CX loads templates at service start and caches them; after replacing an already-uploaded template a 3CX service restart may be required.

4. Map the agents

For every Odoo user handling calls, set the 3CX Extension on the Connect user (Connect → Users). The journal webhook uses it to attribute calls to the right user. If several telephony providers are installed, also select 3CX as the user's Click-to-call Provider.

5. Verify

• Call your 3CX DID from outside: the 3CX client should show the Odoo contact name; after hangup the call appears under Connect → Calls.
• Click a phone number in Odoo: a new tab opens the 3CX Web Client with the number pre-filled.

Deep tier: the 3CX agent (AI edition, 8SC+)

If your PBX runs the 3CX AI edition (8 simultaneous calls or larger), you can additionally deploy the oduist/3cx-agent sidecar to get live call events (calls appear in Odoo while ringing, with durations measured from the actual answer), server-side click-to-call (rings all your 3CX devices instead of opening a browser tab) and recording audio download into Odoo (so OpenAI transcription applies).

1. In the 3CX Admin Console open Integrations → API and create a dedicated client application for the agent: check both 3CX Call Control API Access and 3CX Configuration API Access, assign the System Owner role (needed for recordings), and list the extensions to monitor. Copy the Client ID and the API key (shown once). Nothing else may use this client — 3CX keeps one active token per client application.
2. In Connect → 3CX → Configuration → Settings, section Agent: enable the agent, set the agent URL, and paste the 3CX Client ID and Client Secret.
3. Run the agent next to Odoo (or anywhere with HTTPS reach to both Odoo and the PBX):

docker run -d --name connect-3cx-agent \
  -e ODOO_URL=https://odoo.example.com \
  -e AGENT_TOKEN=<API key from Connect Settings → 3CX> \
  -p 8083:8083 \
  -v connect-3cx-agent:/var/lib/connect-3cx \
  oduist/3cx-agent:latest

The agent pulls the PBX URL and the 3CX credentials from Odoo automatically. 4. Press PING AGENT in the settings form — the status should show Call Control WS connected.

With the agent enabled, the CRM template keeps working: caller-name lookup and screen pop stay server-side, and the end-of-call journal now merges its 3CX AI transcript/summary into the live call record instead of creating a duplicate.

Security notes

• All webhook routes live under /3cx/webhook/* and require the API key (constant-time comparison); they are additionally disabled while 3CX Enabled is off.
• The key is embedded in the downloaded template file — treat the file as a secret and rotate the key if it leaks.