3CX Integration

3CX

The phone rings. Before you answer, 3CX shows the caller's name and company - and FreeITSM opens their ticket in front of you. When you hang up, the call is already noted on that ticket: in or out, how long, who took it, and the recording if your 3CX keeps one. Nobody typed anything.

Set up under System → Integrations → 3CX. Contributed by Carl Steynvaard of Open Resilience, who built and ran it in production before offering it to the project.

Developers: how it works, the file map and the traps are in the 3CX — Developer Guide.

---

What you get

• You see who is calling. While the phone rings, 3CX asks FreeITSM who the number belongs to and shows the person's name and company.
• Their ticket opens. 3CX opens the caller's open ticket in FreeITSM for the analyst who picks up - or their record on Tickets → Users, if they have no open ticket.
• Every call is noted. When the call ends, an internal note goes on that ticket: Phone call from Jane Smith (07700 900123), the duration, the recording link and 3CX's own summary if your 3CX makes them. The note is written by the analyst who took the call.
• A call can open a ticket. A call in - answered or missed - from someone with no open ticket can open one, assigned to whoever took it.
• Numbers dial out. Phone numbers on tickets, on Tickets → Users and on People get a Call button that dials through your phone.
• You can see what arrived. The bottom of the 3CX page lists the last 25 calls reported and what was done with each.

---

🔑 3CX calls FreeITSM, not the other way round

FreeITSM never logs in to 3CX and holds no 3CX password. 3CX sends each question and each call report to an address on your FreeITSM, with a token - a long secret that proves it came from your 3CX. Anything without it is refused, and until you make a token everything is turned away.

The token travels in a header on each request, never in the address, so it is not written into web server logs or anyone's browser history.

3CX is often hosted in the cloud, so FreeITSM's address on the page has to be one the internet can reach.

---

Setting it up

1. Make the token. On the FreeITSM 3CX page, click Make.
2. Download the template. Click Download. You get freeitsm_3cx_template.xml, with your address and token already in it. Keep it to yourself - it holds the token.
3. Upload it to 3CX. In the 3CX Admin Console, go to Integrations → CRM, add your own template and upload the file. It shows as FreeITSM. Leave Log calls on FreeITSM tickets ticked, turn on call journaling, and save.
4. Choose where calls go on the FreeITSM page (below), and Save.
5. Try it - see below.

After Replace on the token, the old one stops working at once: download and upload the template again.

---

Who is the caller?

The active person whose phone or mobile is the number - however either is written. 07700 900123, +44 7700 900123, 0044 7700 900123 and the last nine digits of it all count as the same number, and anything after the number in the field (ext 21) is ignored.

If two or more people have the number - a switchboard, a shared desk - FreeITSM does not guess. 3CX shows an unknown caller, and the call is only listed.

Short internal numbers (extensions) never match anyone.

---

Your choices

Setting	What it does
Which ticket a call goes on	The caller's most recently updated open ticket (the default); only when they have exactly one - with several, a person decides; or none, so calls are only listed on the 3CX page. The ticket 3CX opens when the phone rings follows the same choice.
Open a new ticket for a call from someone with no open ticket	On by default. Only for calls in, answered or missed - calling someone back is not a new request. Assigned to the analyst who took the call.
Also for numbers nobody in FreeITSM has	Off by default. Raises the ticket for "Caller" and their number, for an analyst to link to the right person.
Write notes as, when the 3CX user is not an analyst	A note is written by the analyst whose email is the same as the 3CX user who took the call. A receptionist or a shared phone that is not an analyst can be covered by choosing someone here - their notes say who took the call. With Nobody, those calls are only listed.
Company for tickets from unknown numbers	(More than one company.) A known caller's ticket always goes in their own company.
Team and Origin	For new tickets. Origin starts as Phone.

---

📞 Click-to-call

Put a Dial address on the 3CX page, with {number} where the number goes:

• 3CX web client: https://your-pbx.3cx.com/webclient/#/call?phone={number} - your own 3CX address.
• 3CX desktop app, or any softphone: tel:{number}.

Every phone number on a person, a supplier contact, Tickets → Users and the ticket's From line then has a Call button. The call is placed by the analyst's own 3CX, on their own computer, where they are already signed in - so it comes from their own extension, and FreeITSM never needs to know it. When it ends, 3CX reports it like any other call.

Leave the dial address empty and there are no Call buttons.

---

Try it

• Try a call on the 3CX page: type a number, choose the kind of call and who took it, and FreeITSM says what would happen - who the caller is, which ticket it would go on, and who the note would be written by. Nothing is written, so you can try a real requester's number safely.
• A real call. Ring the desk from a phone whose number is on someone in FreeITSM. Their name shows in 3CX while it rings; when you hang up, the call appears under Recent calls within seconds. Only this proves 3CX can reach FreeITSM.

---

If something is wrong

What you see	Why
3CX shows no name	Nobody has the number - or two people do, and no name is shown rather than the wrong one. Check with Try a call.
No calls under Recent calls	3CX cannot reach FreeITSM's address, the token is wrong (after Replace, upload the template again), or call journaling is off in 3CX.
A call is listed but not noted	What happened says why: nobody has the number, several do, the caller has several open tickets and the rule is "only one", or the 3CX user is not an analyst and nobody is chosen under Write notes as.
The note is by the wrong analyst	The note goes to the analyst whose email is the 3CX user's. Make them the same.
3CX refuses the file	Upload it exactly as downloaded - saved again in another program, it can change.
No Call buttons	The dial address is empty, or has no {number}.

---

Related: 3CX — Developer Guide · Zabbix · People