How the 3CX integration works, where it lives, and the traps. The user page is 3CX.

Contributed by Carl Steynvaard (Open Resilience), October 2026, as part of a package of integrations and modules he built and ran in production on FreeITSM 3.8.1. The idea - 3CX asks who is calling, and reports each call when it ends - is his, as is the care over 3CX's unfilled [Variables]. The code was rebuilt to FreeITSM's conventions; what changed and why is worth reading before contributing an integration of your own.

3CX ──CRM template──▶ api/external/3cx/crm.php ──┬─ lookup → threecxLookup()      who is this number?
     (POST JSON,                                 │            → { contacts: [ … url: tickets/caller.php?user_id=N ] }
      Bearer token)                              └─ report → threecxHandleCall()  a call has ended
                                                              threecxPlanCall() decides, then:
                                                              ├─ noted   → TicketsService::createNote (as the analyst)
                                                              ├─ created → TicketsService::createTicket
                                                              ├─ logged  → nothing on a ticket
                                                              └─ always  → a row in threecx_calls

3CX opens ContactUrl ──▶ tickets/caller.php ──▶ the caller's ticket (same rule as the note) or Tickets → Users

System → Integrations → 3CX (system/integrations/threecx.php) ──▶ api/system/threecx_settings.php   (administrators)

Nothing calls 3CX. It is a telephony-kind provider in the registry (includes/integrations/integrations.php): one endpoint and one token, so the Integrations index shows it as Configured / Not set up, like Zabbix.

Settings are system_settings rows: threecx_token (encrypted - in ENCRYPTED_SETTING_KEYS), threecx_ticket_rule (latest_open / only_one / log_only), threecx_create_ticket, threecx_create_unknown, threecx_fallback_analyst_id, threecx_tenant_id, threecx_team_id, threecx_origin_id (empty = the seeded Phone origin, 0 = none), and phone_dial_url (click-to-call - not prefixed, because it is not 3CX's).

Click-to-call is drawn on people/person.php, people/contact.php (server-side, phoneWithDialHtml()), and on Tickets → Users and the ticket's From line from links the APIs build (get_users.php → phone_dial / mobile_dial; get_email_detail.php → requester_dial). The JavaScript never reads a phone field itself, so the rules live in one place.

3CX links to a CRM through an XML template (Admin Console → Integrations → CRM). threecxTemplateXml() writes it, following 3CX's CRM template reference:

• Parameters Url and Token default to this install's address and token, so the uploaded file is ready; ReportCallEnabled lets an administrator switch call reports off in 3CX.
• <Authentication Type="No" /> plus an Authorization: Bearer [Token] header on each request. 3CX's Basic type base64-encodes its value, and 3CX's own forum reports Bearer under Basic failing; a manual header under No is the pattern that works.
• The lookup scenario has an empty Id. It must return ContactUrl (3CX's identifier for the contact, and the address it opens), one of FirstName / LastName / CompanyName, and a phone output equal to the number searched - so the endpoint hands back phone = the number 3CX sent. EntityId / EntityType are returned too: some 3CX versions only journal a call that matched an entity.
• ReportCall posts call_type ([CallType]: Inbound / Outbound / Missed / Notanswered), number, agent (the extension), agent_email, agent_name, duration (seconds, from [DurationTimespan]), start ([CallStartTimeUTC], ISO), recording_url, summary.
• <Number Prefix="AsIs" MaxLength="[MaxLength]"> gives FreeITSM the number cut to the digits set in 3CX (Phonebook → number of digits to match), which the matcher reads either way.
• The template's Name is plain FreeITSM: a forum report has 3CX refusing an upload over characters in the name.

⚠️ The file carries the token. export is administrators-only and sends Cache-Control: no-store.

threecxNumbersMatch(): the number part of each field (phoneNumberPart() - everything before the first letter, so ext 21 is dropped), digits only, leading zeros dropped, then one must end with the other, the shorter at least 7 digits. So national, international, 00-prefixed and 3CX's cut-down form all agree, and an extension never matches.

⚠️ That is looser than messagingFindUsersByPhone() (WhatsApp, Telegram), which wants the digits equal. A phone system sends whatever its trunk gives it, and equality would miss most real callers. The cost: one national number could in principle match the same digits in another country. That comes out as two matches - and two matches are never chosen between.

threecxFindCallers() searches every company (one phone system answers for all of them), active people only, never the @phone.invalid placeholders.

threecxPlanCall() decides; threecxHandleCall() carries it out. The settings page's Try a call shows the plan and writes nothing, so what an administrator tries is the real decision.

1. The caller - exactly one match, or none.
2. The ticket - threecxTicketFor(), by the rule. tickets/caller.php uses the same function, so the screen that pops is the ticket the call will be noted on.
3. The author - the active analyst whose email is agent_email (case-insensitive, and only if exactly one has it), else the fallback analyst.
4. noted (a ticket and an author) → an internal note through TicketsService::createNote(), with an ActorContext for that analyst and companyScope: null - the call is not limited to the companies the analyst can open.
5. created - no open ticket at all, a call in (Inbound or Missed), the rule not log_only, and new tickets ticked (and unknown numbers too, for a stranger) → TicketsService::createTicket() with user_id (a known caller, in their own company) or a <digits>@phone.invalid requester (an unknown one, in the configured company); assigned to the agent if they are an analyst - never to the fallback, who only signs notes.
6. Otherwise logged, with the reason in detail.

3CX gives a template no call id, so call_key is a hash of number, start, agent, duration and type, unique in threecx_calls. The same report twice (3CX retrying) is recorded once; a GET_LOCK on the key serialises two arriving together.

• TRAP: a call note needs a real analyst. ticket_notes.analyst_id is a foreign key to analysts. The contributed version wrote notes as ActorContext::system() - actor id 0. On an install with the key (every fresh one) the note is refused and the call fails; on an older install that never got the key, it is saved with no author. Proven by mutation: with the system actor swapped back in, tests/threecx-integration.php fails on exactly the two authorship checks. Hence the agent email match and the fallback analyst.
• Never guess between two people, or two tickets. A shared number is nobody; only one with several open tickets is none.
• A lookup says nothing about tickets. The contributed version returned open ticket subjects to anything holding the token. 3CX shows a name - that is all it gets.
• 3CX sends a variable it has no value for as its own name ([RecordingUrl]). The endpoint blanks any value that is exactly [Word] - Carl's catch.
• Everything from 3CX is text. Notes are shown escaped; a recording "link" that is not http(s) is dropped.
• Authorization can be stripped before PHP sees it on Apache + FastCGI. api/external/3cx/.htaccess hands it through, and crm.php reads getallheaders(), then HTTP_AUTHORIZATION, then REDIRECT_HTTP_AUTHORIZATION - as api/v1 does. The body may carry token instead, for a client that cannot set headers.
• The dial address is admin text that becomes a link. phoneDialTemplateValid() allows only https://, tel:, callto: and sip: with {number}; only digits and a leading + reach {number}.
• The endpoint is on CSRF_EXEMPT_PATHS (api/external/): 3CX is cross-origin and carries no login cookie. The token is the credential, compared with hash_equals; no token made means everything is refused.

php tests/threecx-integration.php

60 checks through the real endpoint and settings API, with requests shaped as the template sends them: the token (none made, wrong, absent, in the address), lookups (national vs international vs last-9, a shared number, an extension, no ticket details), reports (a new ticket assigned to the agent, the next call noted by them, a duplicate, a bad recording link, a call out, a non-analyst with and without a fallback, all three rules, a shared number, unknown numbers), the template (well-formed, token only in headers, the outputs 3CX requires, XML characters escaped), click-to-call, the settings API (admins only, the download, a GET rotate refused, save and a refused dial address), and Try a call writes nothing. It makes two throwaway analysts with .invalid addresses so no real analyst is assigned or notified, pauses the ticket.created workflows, and removes everything at the end.

What it cannot prove: there is no 3CX here - it does not run in Docker the way Zabbix does. The template follows 3CX's reference and templates others have posted, and its request shape is exactly what the tests send; the first real upload is the proof that 3CX accepts it.

Related: 3CX · Zabbix — Developer Guide · CSRF protection — Developer Guide · Developer Tests