Connect 3CX
3CX is a phone system that a customer runs on their own server, in their own cloud, or as an instance hosted by 3CX. Every customer has their own PBX with its own address, so one StackJack connection…
Written By Christopher Scaminaci
Last updated About 3 hours ago
3CX is a phone system that a customer runs on their own server, in their own cloud, or as an instance hosted by 3CX. Every customer has their own PBX with its own address, so one StackJack connection reaches one PBX. StackJack talks to the two APIs 3CX publishes for it, the Configuration API (everything you can do in the Admin Console) and the Call Control API (live calls), through one connection.
Connecting a 3CX PBX to StackJack gives your AI assistant a family of tcx_ MCP tools. MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:
- Check the health of the PBX - system status, services and which one is down, the licence and when it expires, update status, the firewall checker, event logs, the activity log and the network settings
- Answer questions about calls - the call log for any period, call quality for one call, inbound and outbound volume, the audit log, and the queue, SLA, abandoned-call, agent-login and extension reports
- Look up who and what is on the PBX - users and extensions, departments, contacts, phones and the firmware they run, and who has which number
- Read the call path - inbound and outbound rules, DID numbers, digital receptionists, ring groups, queues, office hours, holidays, parking and call flow apps
- Read trunks and gateways - SIP trunks and their registration, SBCs, FXS gateways and trunk templates
- Read security and access - the IP and caller block lists, the anti-hacking settings, API clients and tokens
- Download files - call-history and report exports, recordings, greetings and playlists, and the generated dial-plan and script files, each as a short-lived download link
- Onboard and change people (on Pro plans) - create and update users, send the welcome email, regenerate passwords, and reboot or reprovision a phone
- Change the call path (on Pro plans) - edit rules, receptionists, queues, ring groups, office hours and holidays, and add or change trunks, SBCs and gateways
- Run the PBX (on Pro plans) - start a backup, restart a service, install updates, manage departments on a multi-company PBX, and change general, mail, logging and integration settings
- Work with live calls (on Pro plans) - see the calls in progress, drop one, place a call from an extension, and answer, divert, route or transfer a call on a monitored extension
What you need before you start
The 3CX AI edition (8SC or higher). The Configuration API is not part of the lower editions. A PBX on Free Basic, Basic or Pro does not offer it, and StackJack cannot connect to it.
A PBX that StackJack can reach from the internet. StackJack calls your PBX over HTTPS from outside your network. That works when the PBX is published at a public address with a certificate from a publicly trusted authority, which is how an instance hosted by 3CX and most PBXs that serve the remote apps already run. It does not work for a PBX reachable only on your own network, and it does not work with a self-signed certificate. The PBX's HTTPS port is usually 443 or 5001; enter whichever one you use.
Access from StackJack's addresses, if you restrict the console. If you limit the Admin Console to an address list, StackJack's calls have to be allowed through it. We give those addresses by support ticket rather than publishing them.
How StackJack authenticates to 3CX
3CX has no vendor portal and no partner-level credential. Every PBX issues its own API client, so you do this once per PBX you want StackJack to reach.
- Sign in to the 3CX Admin Console as a System Owner or System Admin.
- Go to Integrations > API and add a client for StackJack.
- Tick 3CX Configuration API Access. To use the live call control tools, also tick 3CX Call Control API Access.
- Choose a department and a role. System Owner or System Admin gives StackJack the whole PBX. Any other role limits StackJack to what that role may do.
- Copy the Client ID and the API key before you close the dialog. 3CX shows the key only once; if you lose it, generate a new one.
- In StackJack, enter the PBX address, the Client ID and the API key.
StackJack exchanges the pair for an access token that lasts one hour, keeps it cached, and renews it by itself, so there is no renewal step. The pair keeps working until someone changes or deletes the client on the PBX.
Give StackJack its own API client
The PBX keeps only one access token active at a time. If another tool uses the same API client, each one's sign-in invalidates the other's token and both start failing at busy moments. Create a separate client for StackJack and do not share it.
Two things to get right before you save
Use an HTTPS address. The API key travels in the sign-in request and the access token travels in every call. A plain http:// address would expose both, so StackJack refuses it.
Check the pair before you save it. A PBX can ban an address that fails to sign in repeatedly. StackJack disables a failing connection after three failed checks and, after a refusal, waits a short while before it tries the PBX again, which keeps a typo from getting StackJack's address banned. If you fix something on the PBX after a refusal, allow a few minutes before testing again.
Live call control
The live call control tools use the Call Control API, which needs a second permission and a second setting. Tick 3CX Call Control API Access on the API client, and make sure the extensions you want to control are ones that client monitors. Without both, those tools answer that the action is not allowed, while every Configuration API tool keeps working.
Permissions
3CX has no permission scopes on this API. What the client can do is decided by its role and department on the PBX, and a client with the System Owner or System Admin role reaches everything.
That makes StackJack a second place where least privilege happens, so it is worth being deliberate:
- Reads are Free. Everything that only answers a question is available on the Free plan.
- Every change is Pro. Creating, editing, deleting and anything that touches a live call or the running PBX.
- The tools you allow are the boundary. An assistant that only needs to answer questions about calls should be granted read tools and nothing else.
Tools that change live phone service
Some of these tools do things a customer will notice immediately. StackJack marks each of them as a change tool, and it is worth knowing which they are before you grant them. Whether your AI application stops to ask you first depends on that application's own settings - see Destructive tools and confirmation. Review those settings, and restrict the tools you grant, before you allow changes:
- Live calls - dropping a call in progress, and answering, diverting, routing or transferring one
- Calls that ring a phone - placing a call from an extension, testing a trunk with an inbound or outbound call, and playing or recording a prompt or greeting over the phone
- Messages to people - the welcome email and the test and notification emails reach real mailboxes, and a help request reaches 3CX support
- Desk phones - rebooting, reprovisioning, moving or pushing firmware to phones people are using
- Running services - stopping, restarting or disabling a service, restarting the operating system, installing updates, and starting database maintenance
- Restore and licence - restoring a backup over the running PBX, replacing a licence key and linking or unlinking a reseller
- Who can call in and out - trunks, outbound rules, emergency settings, the block lists and the anti-hacking settings. A wrong value silently drops legitimate calls or lets unwanted ones through
- Locking yourself out - the console access restrictions and the network settings. A wrong value can make the PBX unreachable
- Credentials - regenerating user passwords, creating a user or changing a user's roles and passwords, generating a phone provisioning link (it lets a phone or app configure itself without a password), revoking tokens and API keys, and creating or changing an API client
- Jobs that run on their own later - saving settings that can arm automatic deletion or archiving of recordings, voicemail, chats, faxes and logs, a scheduled restore or update, scheduled firmware updates for the desk phones, the data offload, the user sync with Microsoft 365 or Google, and reports that 3CX emails to people on a schedule
- Stored passwords and keys - saving the mail, backup, syslog, Teams, Amazon, AI, CRM, directory search and conference settings stores a password, key or PIN that the PBX keeps and uses. So does creating or changing a trunk, an SBC, an FXS gateway or a fax extension, and creating a trunk from a provider's phone numbers, because their records carry the SIP or gateway password
- Deletions and purges - every delete, and every purge of calls, chats, logs, recordings or backups, which the PBX cannot undo
Reads that can return passwords
3CX stores SIP passwords and other secrets in several records, and the matching reads return them as part of the record. These are the user, extension, trunk, phone, SBC and FXS reads, the extension and trunk exports, and the settings reads for backups, archiving, mail, logging, voicemail transcription, directory search, and the Google, Microsoft Teams, Amazon, data connector and AI integrations. Two more reads return a credential outright: the PBX's API token and the Microsoft access token the PBX holds.
StackJack does not strip those fields, so an agent that reads a user sees what 3CX returns. StackJack never records such a result for evaluation, never stores an oversized one as a file, and the extension and trunk exports always answer inline rather than as a download link. Anything an agent reads can still appear in its conversation, so grant these tools only to agents that need them, and ask for only the fields you need.
Downloads and exports
Call-history and report exports, recordings, greetings, playlists and the generated script files are files rather than data. StackJack saves the file and returns a short-lived, read-only download link with its type, size and exact expiry, so it never has to carry a recording through the conversation. If the link cannot be created, the tool says so rather than handing back a dead one.
Where the numbers come from
Every page-size limit here is StackJack's, not 3CX's. 3CX documents no maximum, and a call log or event log on a busy PBX can be very large, so StackJack always asks for a page: 50 records by default and at most 100. Ask for the next page with a skip, and ask for the total with a count. Report tools take their period and filters as required values, so name a date range rather than asking for everything. A file export is the exception: it is the whole result unless you give it a row limit.
3CX documents no request limit. StackJack keeps its own courtesy cap on how fast one connection calls a PBX, because the target is often a small server and an agent loop must not load it.
Several customers, and multi-company PBXs
Every customer has their own PBX. Add one connection per customer from the connector's card, name it after the customer, and your AI names it on each call. Omit the name and the call runs against your default connection. Pin an endpoint to one connection when an AI should never reach past a single customer. See Several connections of one connector.
A multi-company PBX hosts several small customers on one instance as departments. One connection with the System Owner or System Admin role reaches every department, and the department tools take a department id or a filter to narrow a request to one customer. The API needs the AI edition even where multi-company mode itself does not, so a multi-company PBX can be connected only when it runs the AI edition.
If something goes wrong
The connection test is refused. Check the edition first: a PBX below the AI edition does not offer the API. Then check the address is the one you reach the 3CX web client at, that its certificate is publicly trusted, and that the Admin Console's access restrictions allow StackJack through. Then check the Client ID and API key match the client on the PBX.
Calls work, then fail for a while, then work. Another tool is probably using the same API client, so the PBX keeps swapping which one holds the token. Create a separate client for StackJack.
A tool says the action is not allowed. The client's role or department does not cover it, or the API access box is not ticked. Open the client under Integrations > API and check both. For live call control, check the second box and the monitored extensions.
A tool says the route or record was not found. Either the record does not exist, or the PBX build is older than the route. StackJack follows the newest 3CX version 20 build, and a route added in a later update answers not found on an earlier one. Update the PBX under Updates in the Admin Console. If every tool answers not found, the address is wrong.
Something answered, but it was not 3CX. A sign-in page, a firewall or a reverse proxy replied instead of the PBX. Enter the exact address you reach the 3CX web client at, including the port when it is not 443.
Full tool reference
Every tcx_ tool, with its plan and whether it reads or changes something: 3CX tools.
3CX tools
tcx_ · 610 tools · Free 334 · Pro 276
System status
Services
Updates
License
System definitions
Firewall checker
Network
Logs
Reference data
Backups
IP block list
Caller block list
Access restrictions
Security tokens
API clients
Users
My user
Extension properties
Peers and directories
Departments
My department
Tenant properties
Contacts
Phonebook settings
Inbound rules
Outbound rules
DID numbers
Digital receptionists
Ring groups
Queues
Office hours and holidays
Parking
Call flow apps
Dialing settings
Live calls
Prompts
Playlists and music on hold
Trunks
Trunk templates
SBCs
FXS gateways
SIP settings
Phones
Firmware
Phone templates and settings
Recordings
Archiving and retention
Voicemail
Fax
Call Control API
History views
Scheduled reports
CDR and call cost settings
Call log reports
Call volume and audit reports
Queue reports
Extension reports
Chat reports
General settings
Mail and notifications
Logging
Conferencing
Website links
Hotel
Microsoft 365
Microsoft Teams
CRM
Amazon AWS
Data connector
MCP servers
AI
Was this helpful?
More in Connector guides
Connect Acronis Cyber Protect CloudConnect Action1Connect AddigyConnect AlertOpsStill need help? Ask the team