3CX MCP server

Showing 9 of 9 tools

• threecx_create_user

  Write

  Create a new extension. The extension number must be free -- 3CX answers a number already in use with a 400 naming the Number field -- so check with threecx_find_extension first. This tool deliberately sets no credentials: the PBX generates the SIP and web-client passwords and the voicemail PIN itself, and they are delivered to the person through 3CX's own welcome email from the console, never through this connector. The new extension is not a member of any department yet and has no phone provisioned to it; both are done from the PBX console. Creating an extension consumes a licensed simultaneous-user slot, so a PBX at its ceiling will refuse.

• threecx_delete_user

  Write

  Destructive

  Permanently delete an extension. This is not reversible from this connector and 3CX offers no undo: deleting an extension destroys that person's voicemail messages and greetings, breaks the association between them and their call history, and immediately deregisters every phone and client signed in to them -- their handset stops working and anyone dialling their extension will not reach them. Re-creating the same number afterwards produces a new, empty extension; it does not bring anything back. Almost every reason to reach for this is better served by threecx_update_user with enabled set to false, which stops the extension working but keeps the person, their number, their voicemail and their history intact. The extension is fetched and named in the confirmation before anything is deleted, so a wrong Id is visible before it does harm.

• threecx_find_extension

  Read-only

  Look up an extension by the number people actually dial -- "212", not the internal user Id. This is the usual starting point when someone says "extension 212 is not ringing": it gives you the Id every other user tool needs, plus whether the extension is enabled and whether a phone is currently registered to it. Returns found: false rather than erroring when the number is not in use. Credential fields are never returned.

• threecx_find_user_by_email

  Read-only

  Look up an extension by the email address on the account. The match is case-insensitive, which is what 3CX's own documentation recommends for this lookup. Returns an empty list rather than an error when nobody matches -- that is the normal answer when checking whether an address is already in use before creating an extension. An address can legitimately appear on more than one extension, so this returns a list.

• threecx_get_my_user

  Read-only

  The extension belonging to the API client this connection authenticates as, without needing to know its Id. Useful for confirming which identity the connector is acting under before doing anything else. Note that a service principal created for an integration often has no meaningful extension of its own, in which case this can be sparse or refused -- that is not a fault.

• threecx_get_user

  Read-only

  One extension by its numeric user Id -- the same safe field set as threecx_list_users, for a single person. The Id is NOT the extension number: pass 12, not "212". If all you have is the extension number use threecx_find_extension, and if all you have is an email address use threecx_find_user_by_email. Credential fields are never returned.

• threecx_list_user_forwarding_profiles

  Read-only

  The status profiles configured for one extension -- Available, Away, Do Not Disturb and any custom ones -- with the status message on each and where calls are routed during office hours and outside them. 3CX has no separate do-not-disturb flag: presence and DND are modelled as these profiles, so this is where "why are calls going straight to voicemail" is answered. Which profile is currently active is the currentProfileName field on the user itself, not a field here.

• threecx_list_users

  Read-only

  Every extension on the PBX -- id, extension number, name, email, whether the extension is enabled, and whether a phone or client is currently registered to it. This is the roster; use threecx_find_extension or threecx_find_user_by_email when you already know who you want, because they are one call instead of paging. Only a fixed safe set of fields is requested: SIP passwords, deskphone passwords and voicemail PINs are never returned, and a user's department is not a field here -- get that from threecx_list_departments and threecx_list_department_members. Page with top and skip; there is no documented maximum page size, but asking for too much answers with a 504 rather than an error that says so.

• threecx_update_user

  Write

  Change a fixed set of fields on one extension: name, email address, mobile, whether the extension is enabled, outbound caller id, queue login status, the call-recording flags and the missed-call email flag. Only fields you pass are changed, and the extension's values before the change are returned so the edit can be reverted exactly. Credential fields are deliberately not settable here -- there is no way through this tool to set a SIP password, a web-client password, a deskphone password or a voicemail PIN. Department membership is also not settable: 3CX models it as a nested group-and-role structure that replaces the whole membership set, so a partial edit would silently drop someone out of their other departments. Do it in the PBX console. Setting enabled to false stops this person's phone working immediately.

Showing 6 of 6 tools

• threecx_get_license_status

  Read-only

  What the PBX is licensed for -- edition, simultaneous-call and web-meeting ceilings, which modules are active, and when the licence and maintenance expire. Use it when a feature is unexpectedly unavailable (this connector's XAPI access itself needs an 8SC or larger AI licence) or when a renewal date matters. Usually needs a System Administrator or System Owner role, so a 403 here means the API client's role is too narrow rather than that anything is wrong with the licence. The licence key itself and the licence holder's contact details are deliberately not returned.

• threecx_get_server_time

  Read-only

  The PBX's own clock, as the server currently reports it. Read this before interpreting any timestamp from this connector or before giving 3CX a date range -- office hours, holidays, call history and scheduled reports are all evaluated against the PBX's clock and time zone, not the caller's, and an hour of drift is the usual explanation for calls landing in the wrong day's report. Also returns the host's uptime tick count, which is a quick way to spot a PBX that rebooted recently.

• threecx_get_system_health

  Read-only

  The PBX's own three-light health check -- firewall, trunks and phones each pass or fail -- plus counts of custom phone templates and handsets running unsupported firmware. Much narrower than threecx_get_system_status: it answers "is anything wrong" rather than "what are the numbers", and it does not say WHICH trunk or phone is unhealthy. A false on trunks means at least one trunk is not registered, which is the usual cause of "we cannot make outside calls".

• threecx_get_system_status

  Read-only

  The PBX's overall status in one call -- calls in progress right now, extensions registered vs. provisioned, trunks registered vs. configured, disk and recording/voicemail quota headroom, backup and update state, and whether any service is not running. This is the tool to reach for first when someone asks whether the phone system is healthy or why something is not working. It reports counts, not causes: if servicesNotRunning is true use threecx_list_services to find which one, and if trunks are short use the trunk tools. The PBX's internal IP addresses and licence key are deliberately not returned -- threecx_get_license_status covers the licence side.

• threecx_get_version

  Read-only

  The PBX's software version and update channel, and the cheapest proof that this connection actually works -- it is what the connection test runs. Everything this connector does assumes 3CX V20 or newer, because the XAPI this connector speaks was introduced in V20; a version that does not start with 20 means most other tools will fail with 404s rather than anything more helpful. A 403 here means the service principal's role is too narrow, not that the credentials are wrong.

• threecx_list_services

  Read-only

  Every 3CX service on the PBX with its run state (Running, Stopped, StartPending, StopPending, Paused, PausePending, ContinuePending) and its memory, thread and handle usage. Reach for this when threecx_get_system_status reports servicesNotRunning, to find which one is down. This connector is read-only here on purpose -- starting, stopping or restarting a 3CX service drops every call in progress and deregisters every handset, so that has to be done from the PBX console by someone who knows the phones are about to go quiet.

Showing 6 of 6 tools

• threecx_get_office_hours

  Read-only

  The PBX's global office hours: the open windows for each day of the week, the break-time schedule, and the timezone every schedule is interpreted in. This is what decides whether an inbound rule uses its office-hours destination or its out-of-office one, so it is the other half of any "why did this call go to voicemail" question. A day with no period is a day the company is closed all day. Set includeHolidays to also list the configured holidays, on which calls take the holiday destination regardless of the weekly schedule.

• threecx_list_inbound_rules

  Read-only

  Every inbound routing rule -- what happens to a call arriving from outside. Each rule gives its condition (BasedOnDID, BasedOnCallerID and so on), the DID or caller ID it matches in `data`, and up to three destinations: during office hours, outside office hours, and on holidays. Read this before changing anything: pair it with threecx_list_dids to answer "where does a call to this number actually go", and with threecx_get_office_hours to know which of the three destinations is live right now. Set includeTrunk to also resolve which trunk each rule belongs to.

• threecx_list_outbound_rules

  Read-only

  Every outbound routing rule -- which trunk a dialled number leaves on, and what digits get stripped, prepended or appended on the way out. Returned in priority order, which is the order the PBX evaluates them: the FIRST rule whose prefix, number length and calling extension all match wins, so a rule's position matters as much as its contents. `emergencyRule: true` marks a rule that carries 911/999/112 traffic. Read this before changing anything -- "calls to this country fail" is nearly always a prefix or number-length mismatch here rather than a trunk fault.

• threecx_set_office_hours

  Write

  Destructive

  Set the open window for ONE day of the week, or mark that day closed. READ THE CURRENT HOURS FIRST with threecx_get_office_hours, and change one day per call. Office hours decide which destination every inbound rule uses, so getting this wrong makes the whole company appear closed -- callers hear the out-of-hours greeting or land in voicemail during working hours, and nothing about the PBX looks broken. Times are in the PBX's own timezone, which threecx_get_office_hours reports; this tool does not change the timezone. Any existing windows for the chosen day are replaced by the single window given, so a day split into a morning and an afternoon session collapses into one -- check the previous periods in the response before accepting the result. The response returns the COMPLETE previous weekly schedule; keep it, it is how you put this back.

• threecx_update_inbound_rule

  Write

  Destructive

  Change where inbound calls matched by one rule are delivered. READ THE RULE FIRST with threecx_list_inbound_rules, and change ONE thing per call -- this is the edit that fails silently: a wrong destination throws no error, the trunk stays registered, and calls simply stop reaching anyone until someone outside the company complains. A destination is a pair: the kind (Extension, Queue, RingGroup, IVR, VoiceMail, External...) and the number, and both must be given together so they cannot drift apart. For a destination on this PBX the number is checked against the live extension and queue list before anything is written, so a typo aborts the call instead of quietly swallowing the traffic; an External number cannot be checked and is taken on trust. Every other field on the rule is carried across untouched. The response returns the rule's COMPLETE previous configuration alongside what the PBX stored afterwards -- keep it, it is how you put this back.

• threecx_update_outbound_rule

  Write

  Destructive

  Change how one outbound rule matches dialled numbers, or where it sits in the evaluation order. READ THE RULES FIRST with threecx_list_outbound_rules, and change ONE thing per call. Rules are evaluated in priority order and the first match wins, so editing a prefix or a priority can silently capture traffic meant for a different rule -- outbound misrouting shows up as calls that fail, connect to the wrong carrier, or bill at the wrong rate, none of which raise an alarm. This tool refuses to touch a rule flagged emergencyRule: 911/999/112 routing is a life-safety and regulatory matter and must be changed in the console by a person. It also does not change which trunks a rule routes to, or which extensions it applies to. The response returns the rule's COMPLETE previous configuration -- keep it, it is how you put this back.

Showing 6 of 6 tools

• threecx_get_queue

  Read-only

  One queue's full configuration -- everything threecx_list_queues shows plus its greeting and on-hold prompts, callback settings, comfort-message intervals, and the routes calls take when the queue is closed, on holiday or times out. Look it up by Id or by its extension number; give exactly one. Prefer threecx_list_queues when you just need to find a queue; use this when you are answering a question about how one specific queue behaves.

• threecx_list_queue_agents

  Read-only

  The agents assigned to a queue -- each one's extension number, display name and skill group. These are PBX users: the Id on each row is the user Id that threecx_set_agent_queue_status takes. Note that this is queue MEMBERSHIP, not availability -- being listed here does not mean the agent is currently logged in, and this endpoint does not report their queue status. Requires the queue's Id from threecx_list_queues.

• threecx_list_queue_managers

  Read-only

  The managers of a queue -- the people who can see its statistics and change its agents, as distinct from the agents who take its calls (threecx_list_queue_agents). Each row is a PBX user: extension number, display name and user Id. Requires the queue's Id from threecx_list_queues.

• threecx_list_queues

  Read-only

  Call queues configured on the PBX -- name, extension number, polling strategy, ring and wrap-up timeouts, SLA target and how many callers each will hold. Start here: the Id on each row is what threecx_get_queue, threecx_list_queue_agents and threecx_list_queue_managers take, and it is NOT the queue's extension number. Queue statistics (calls waiting, longest wait, answered/abandoned counts) are not part of this entity -- this is configuration, not live state.

• threecx_list_ring_groups

  Read-only

  Ring groups (hunt groups) on the PBX -- name, extension number, ring strategy and ring time. A ring group rings several extensions at once or in turn and has no waiting queue, no hold music and no agents to log in or out; when a caller "waits in a queue" they are in a queue (threecx_list_queues), not a ring group. Check both when tracing where a number's calls actually land.

• threecx_set_agent_queue_status

  Write

  Log a person in or out of the queues they are an agent of. This decides whether queue calls ring their phone: logging someone out stops calls reaching them and pushes those callers onto the rest of the team or into the queue's timeout route, and logging someone in starts routing live customers to a person who may not be at their desk. The status is per USER, not per queue -- it applies to every queue that person is an agent of, all at once. Requires the user Id (from threecx_list_queue_agents or the user tools), not an extension number. This tool reads the current status first and returns it as previousQueueStatus, so the change can be reversed exactly; the confirmation names the person whose phone this affects.

Showing 5 of 5 tools

• threecx_drop_call

  Write

  Destructive

  Hang up on a call that is in progress. A real person is disconnected mid-sentence, immediately, and there is no undo -- the call cannot be restored, only placed again. Prerequisite: the Id must come from threecx_list_active_calls, and it must be fresh; Ids are reused as calls come and go, so acting on a list read minutes ago can drop a different call than the one intended. This tool re-reads the call before dropping it and names the actual caller and callee in the confirmation it demands, so check that those are the people you meant before confirming. If the Id is no longer on the PBX the call has already ended and this fails rather than dropping anything.

• threecx_get_call_history

  Read-only

  Historical call detail records (CDRs) for a REQUIRED date range -- who called whom, when, whether it was answered, and how long it lasted. The date range is mandatory on purpose: this endpoint answers a too-wide query with a 504 timeout rather than a rate-limit error, so an unbounded pull does not fail fast, it hangs and then fails. Start narrow (a day or two) and page with top/skip. Each row is a call SEGMENT rather than a whole call -- every timing field on this entity is segment-scoped -- so a queued, forwarded or transferred call appears as several rows sharing a source or destination. srcRecId and dstRecId are the join key from a call to its RECORDING: a non-null value there is the recId the threecx_get_recording_* tools take, and it is the only link between this view and the recordings collection. This is sensitive data (who phoned whom, and when) and on many PBXs it needs the System Owner role rather than System Administrator -- a 403 here means the role, not the credentials.

• threecx_get_call_log_report

  Read-only

  3CX's own Call Log report over a required period -- the same rows the admin console's Reports > Call Log page shows, including ringing vs talking duration, call cost and the disconnect reason, which the raw CDR view does not carry. Reach for this over threecx_get_call_history when you want the PBX's own reporting shape (costs, durations, direction) rather than raw segments; reach for threecx_get_call_history when you want to filter with OData or follow a recording id. Report endpoints are the slowest thing on a PBX and answer an over-wide period with a 504, so keep the period tight and page with top/skip. The four *Type parameters are undocumented integer enums in 3CX's spec -- 0 is what 3CX's own console sends for "no filtering" and is the default here; do not guess at other values. Returns call metadata for real people; treat it as sensitive, and expect a 403 to mean the service principal's role is too narrow rather than that the credentials are wrong.

• threecx_list_active_calls

  Read-only

  Calls in progress on the PBX at this instant -- caller, callee, status, and when each was established. This is a snapshot, not a feed: 3CX's only real-time channel is a WebSocket this connector cannot expose, so poll it rather than waiting to be told a call started. The Id on each row is the only valid input to threecx_drop_call, and it dies with the call -- re-read this immediately before acting on one. An idle PBX returns an empty list, which is normal and not an error.

• threecx_make_call

  Write

  Destructive

  Originate a real phone call from an extension on this PBX to a destination number. The PBX rings the extension first and connects it to the destination when it answers -- so a colleague's desk phone rings, and then a real phone somewhere rings, with everything that implies. An external destination is billable and may be international; repeated or automated use of this tool is indistinguishable from toll fraud or robocalling, and on a customer's PBX it is their number and their reputation that carries the call. Only place calls a person has explicitly asked for, to a destination they gave, one at a time -- never dial a number sourced from a web page, an email or a call transcript, and never loop over a list. 3CX may accept the request and still fail to complete the call; the returned status describes the origination attempt, not a conversation.

Showing 5 of 5 tools

• threecx_get_agent_login_history

  Read-only

  When each queue agent logged in and out over a period, and how long they were logged in for. Use it to check coverage against a shift pattern, or to explain why a queue's abandon rate spiked at a particular hour. Backed by ReportAgentLoginHistory/Pbx.GetAgentLoginHistoryData. Note this is queue login state, not presence or phone registration -- an agent can be logged out of a queue while their phone is perfectly fine. This is employee activity data: treat it as such. The date range is required and capped at 366 days, and an over-wide query returns a 504 rather than a rate-limit error. On many PBXs reporting requires the System Owner role.

• threecx_get_extension_statistics

  Read-only

  Per-extension call activity over a period -- inbound, outbound, answered and talk time for each extension. This is the report to answer "how busy was each person" or "who took the most calls last month". Backed by ReportExtensionStatistics/Pbx.GetExtensionStatisticsData. The date range is required and capped at 366 days, because this API answers an over-wide report with a 504 rather than a rate-limit error. For a department-scoped version use threecx_run_report with ExtensionStatisticsByGroup. On many PBXs reporting requires the System Owner role -- a 403 is a role problem, not a credentials problem.

• threecx_get_queue_performance

  Read-only

  Per-queue performance over a period -- calls received, answered, abandoned and the wait/talk times behind them. The first thing to reach for on "how is the support line doing". Backed by ReportQueuePerformanceOverview/Pbx.GetQueuePerformanceOverviewData; for the single totals row across the queues use threecx_run_report with QueuePerformanceTotals, and for the calls that missed SLA use BreachesSla or StatisticSla. The date range is required and capped at 366 days -- an over-wide query on this API returns a 504, not a rate-limit error. On many PBXs reporting requires the System Owner role, so a 403 is about the role, not the credentials.

• threecx_get_user_activity

  Read-only

  Call activity per user over a period, optionally grouped and scoped to a department. Broader than threecx_get_extension_statistics: it can include or exclude queue calls and group the output, which is what you want for "how did the sales team spend their day" rather than a flat per-extension count. Backed by ReportUserActivity/Pbx.GetUserActivity. Several of its filters are bare int32s that 3CX does not document -- the tool sends 0 for those unless you set them, and says so per field. This is per-employee activity data; the date range is required and capped at 366 days, and an over-wide query returns a 504 rather than a rate-limit error. On many PBXs reporting requires the System Owner role.

• threecx_run_report

  Read-only

  Run one of 3CX's built-in report families and return its JSON rows. Reach for this when no dedicated tool covers what you need: threecx_get_extension_statistics, threecx_get_queue_performance, threecx_get_agent_login_history, threecx_get_user_activity and threecx_get_call_log_report type their own filters properly and are deliberately not repeated in this enum. A date range is mandatory and capped at 366 days -- this API has no 429, so too wide a query comes back as a 504 after the PBX has already spent the time on it, on a box that is also carrying live call media. Report data is business-sensitive (who called whom, which agent handled what) and on many PBXs it requires the System Owner role; a 403 here means the service principal's role is too narrow, not that the credentials are wrong. Only the JSON Get…Data functions are reachable -- the Download… twins return files, and 3CX's legacy Pbx.GetOldCallLogData is not exposed anywhere in this connector because it reads the pre-V20 CDR schema that V20's consolidated CDR storage replaced.

Showing 4 of 4 tools

• threecx_add_phone_blacklist_number

  Write

  Block a caller ID so the PBX refuses its calls. The right tool for "block this nuisance caller". Match the format the number arrives in -- check a call-history row or threecx_list_phone_blacklist first, because a blacklist entry written as 07700900123 will not match a call that arrives as +447700900123, and the block will silently do nothing. Blocking a main switchboard number blocks everyone calling from that organisation, and blocking a mobile blocks a person, so confirm which you have. Entries do not expire; remove one with threecx_remove_phone_blacklist_number. This does not block SMS or chat, and it does not block a caller who withholds or spoofs their caller ID.

• threecx_list_ip_blocklist

  Read-only

  The PBX's IP blocklist and allowlist, with what added each entry and when it expires. This is the first place to look when someone says "my phone stopped registering" or "I can't connect from home" -- the PBX's anti-hacking module blocks an address automatically after repeated failed registrations, and those entries appear here with addedBy "AutoBlacklist" and an expiry, while a permanent block shows addedBy "Manual". blockType "Allow" is an exemption, not a block. Read-only: this connector will not add or remove IP entries, because an IP block hits everyone behind that address -- remote workers, the customer's own admin, or this connector itself, which would be unrecoverable. Change entries in the 3CX console.

• threecx_list_phone_blacklist

  Read-only

  Every caller ID the PBX refuses calls from, with the note recorded against each. Check this before adding a number -- a caller who says they cannot get through is often already on it -- and use it to review what has accumulated, since blacklist entries never expire and nobody goes back to prune them. Blocking here is by caller ID, which spoofed nuisance calls change freely, so a long list of near-identical numbers usually means the blocking is not working and the fix is elsewhere.

• threecx_remove_phone_blacklist_number

  Write

  Unblock a caller ID, so the PBX accepts calls from it again. Takes the number rather than an internal id and looks it up first, so it can only remove an entry that exactly matches what is stored -- run threecx_list_phone_blacklist if the number is not found, since the stored format often differs from the one you were given. Refuses to act if more than one entry matches, rather than guessing. The removed entry, including its description, is returned so it can be put back.

Showing 4 of 4 tools

• threecx_create_contact

  Write

  Add a contact to the PBX's shared phonebook. The new record is visible to everyone in the company and immediately changes what name appears on incoming calls from its numbers, so check threecx_search_contacts_by_number first -- creating a second record for a number that already has one leaves the PBX with two candidate names for the same caller. Numbers should be stored in the format the trunk delivers them (usually full E.164, e.g. +441234567890), or caller-ID matching will not fire. Only creates: this connector exposes no contact edit or delete, because 3CX's delete actions work in bulk from a single argument.

• threecx_get_contact

  Read-only

  One contact's full record by its numeric Id, from threecx_list_contacts or threecx_search_contacts_by_number. Prefer the list tool unless you already hold an Id -- this exists so you can re-read a single record without pulling the phonebook again.

• threecx_list_contacts

  Read-only

  The PBX's contact list -- the shared phonebook that resolves incoming caller ID into a name. Returns each contact's name, company, all its phone numbers, and contactType, which says whether the record was typed into 3CX or synced from a CRM, Google or Microsoft 365 (synced records are overwritten on the next sync). Use `search` for a name or company; to find who a specific NUMBER belongs to, use threecx_search_contacts_by_number instead, which matches the way the PBX itself does. Page with `top` and `skip` -- an unbounded pull on a large phonebook answers with a 504, not a rate-limit error.

• threecx_search_contacts_by_number

  Read-only

  Who a phone number belongs to, resolved the way the PBX itself resolves caller ID. Reach for this over threecx_list_contacts whenever you have a number and want a name -- it matches across every number field on the contact (business, home, mobile, fax, pager, other) rather than one, so it finds records a naive search on PhoneNumber would miss. Typical use: turning the caller ID on a missed call or a call-history row into a person. Returns an empty list when the number is unknown, which is the normal answer for a genuine cold call.

Showing 4 of 4 tools

• threecx_get_department

  Read-only

  One department in full: its office hours and break schedule, its holidays, and where inbound calls go during office hours, on a break, out of hours and on a holiday. This is the configuration that decides whether a caller reaches a person, so read it before concluding anything about why calls are or are not arriving -- an out-of-hours route pointing at the wrong destination looks identical to a working phone system from the outside. Read-only: this connector will not edit office hours, holidays or routing, because those changes are company-wide, silent, and easy to get plausibly wrong.

• threecx_get_my_department

  Read-only

  The department the API client this connection authenticates as belongs to, without needing to know its Id -- same shape as threecx_get_department. Useful for establishing the connector's own scope before reading anything else, since a service principal restricted to one department can only see that department's extensions and calls. On a full-access API client this is usually the DEFAULT company group.

• threecx_list_department_members

  Read-only

  Who belongs to one department, with each member's extension number, display name and what kind of object they are -- a department can contain queues, ring groups and other non-person extensions as well as people. Set includeRights to also return each member's role inside this department (system_owners, system_admins, group_owners, group_admins, managers, receptionists, users), which is how you find who can administer or monitor the department. Only membership fields are requested; no credential field is returned. To go from a member here to their full record, look them up with threecx_find_extension using the number.

• threecx_list_departments

  Read-only

  Every department on the PBX -- 3CX models departments as groups, and the one flagged isDefaultCompanyGroup is the whole company rather than a real department. Returns each department's Id, its number, its name, its time zone, and whether it is currently inside office hours, on a break, on a holiday or out of hours. That last field is the quick answer to "why is nobody answering": a department out of hours routes inbound calls to voicemail or an operator regardless of who is actually at their desk. Use threecx_get_department for the routing behind that, and threecx_list_department_members for who is in it.

Showing 4 of 4 tools

• threecx_get_trunk

  Read-only

  One trunk's full configuration, by its numeric Id or by its trunk Number. Prefer threecx_list_trunks unless the PBX has many trunks and you already know which one you want. Use this to read the exact current settings before advising a change -- the change itself has to be made in the 3CX admin console, deliberately, since this connector does not write to trunks. The carrier SIP password is never returned.

• threecx_list_dids

  Read-only

  Every DID (direct inward dial) number the PBX knows about and which trunk it arrives on. This is the inventory of the company's public phone numbers. It does NOT say where a DID is routed once it arrives -- that is an inbound rule, from threecx_list_inbound_rules. Pair the two to answer "what happens when someone calls 0800 123 4567".

• threecx_list_peers

  Read-only

  Every dialable destination on the PBX in one flat list -- extensions, queues, ring groups, IVRs, fax, conference rooms, parking orbits, route points and external lines -- with each one's number, name and type. This is the fastest way to answer "what is extension 802?" or to find a valid destination number before reading a routing rule that points at one. Cheaper and broader than listing users, queues and ring groups separately, but it carries only identity, not configuration.

• threecx_list_trunks

  Read-only

  Every SIP trunk configured on the PBX -- the carrier connections that carry all external calls. Returns registration state (isOnline), whether inbound and outbound are enabled, the licensed simultaneous-call count, the DIDs attached to each trunk, and configurationIssue, which is the PBX's own verdict that a trunk is misconfigured. Start here when nobody can dial out or calls stop arriving: an offline trunk explains both. The provider's name comes from the nested gateway, since the Trunk entity itself has no name field. SIP passwords are never returned. Read-only -- this connector exposes no trunk writes, because a wrong edit takes the company's phone lines down.

Showing 3 of 3 tools

• threecx_get_audit_log

  Read-only

  The configuration audit trail -- which administrator changed which object, from which IP, and when. This is the tool for "who turned that off", for reconstructing a change that broke routing, and for the change-history evidence a compliance review asks for. It records administrative changes, not calls: use threecx_search_activity_log for call behaviour and threecx_list_event_log for what the PBX itself reported. Action, ObjectType and Source come back as bare integers that 3CX does not document a mapping for, so read them alongside ObjectName rather than on their own. The before/after values are withheld unless you ask for them, because those fields are raw serialised settings that can carry credentials this connector's password stripping cannot reach inside. A date range is required -- this API returns a 504 rather than a rate-limit error when asked for too much. Nothing here can delete audit entries: 3CX's PurgeAllLogs destroys this trail along with the rest, which is exactly the record you would need afterwards, so it is not built.

• threecx_list_event_log

  Read-only

  The PBX's system event log -- service failures, trunk registration problems, licence and update events, security notices -- newest first, filtered to a date range and optionally to a severity. This is the first place to look when someone reports that "the phones went weird on Tuesday": it tells you what the PBX itself noticed and when. It is not a call log; for what happened on a specific call use threecx_search_activity_log, and for who changed a setting use threecx_get_audit_log. The date range is required, because 3CX answers an over-wide query with a 504 rather than a rate-limit error. No purge tool exists in this connector: clearing the event log destroys the record of the incident you are investigating.

• threecx_search_activity_log

  Read-only

  The PBX's activity trace, filterable by extension, call id and severity -- the line-by-line record of what the PBX did while handling calls. Reach for this when a specific call misbehaved and you need to see the PBX's own account of it: a call that dropped, one that routed somewhere unexpected, a handset that would not register. Each row is a timestamp and a message, so expect volume; scope it with the extension or call filter rather than reading a whole day. 3CX types the severity filter as a plain string and does not publish its accepted values -- the PBX exposes them at /ActivityLog/Pbx.GetFilter(), so if a severity value is rejected, omit it. The window is required and capped at 31 days here, tighter than the other log tools, because this is the chattiest log on the box and too wide a query returns a 504 rather than a rate-limit error. There is no purge tool in this connector; clearing this log destroys the trace you would need to explain the incident.

Showing 3 of 3 tools

• threecx_get_call_flow_app

  Read-only

  One call flow app in full, including its compilation result -- the compiler's own message about why a script failed to build, which is usually the answer to "why is this IVR not answering". Set includeScriptCode to also read the app's source. Read it before concluding anything about what a flow does: routing behaviour lives in the code, not in the app's settings. Nothing here writes: 3CX's own MCP server exposes an update-script tool and this connector deliberately does not, because a call flow app script is code executing in the path of every call the app handles, so a write is remote code execution on the customer's phone system with no undo and a failure mode -- callers silently never getting through -- that looks like nothing is wrong.

• threecx_get_call_flow_app_files

  Read-only

  The filenames uploaded alongside one call flow app -- prompt audio, data files, whatever the script reads at run time. Useful when a flow compiles but behaves wrong: a script referencing a prompt that was never uploaded, or that was uploaded under a different name, fails at the point a caller is already on the line. Returns names only; the files themselves are not fetched, and nothing here uploads or deletes them. 3CX exposes Pbx.DeleteFile for this collection and it is not built, because removing a file a live call flow depends on breaks that flow the next time someone calls in.

• threecx_list_call_flow_apps

  Read-only

  Every call flow app configured on the PBX, with its extension number, whether it is registered with the PBX, and whether its script last compiled. This is the inventory to start from when inbound calls are going somewhere unexpected: an app showing InvalidScript true or CompilationSucceeded false is a flow that is not doing what its author intended, and CompilationLastSuccess tells you when it last did. The script source itself is not returned here -- use threecx_get_call_flow_app with includeScriptCode for that. This connector reads call flow apps but never writes them: a call flow app script is code 3CX executes in the call path, so editing one is remote code execution on the customer's phone system, and it is left to a human with a deployment process.

Showing 3 of 3 tools

• threecx_get_recording_download_url

  Read-only

  The authenticated XAPI URL for one recording's audio file, together with the paths 3CX stores on the recording itself. It returns a URL and metadata -- it does not fetch, stream or return the audio, which could not usefully cross a tool boundary anyway. The URL is not a shareable link: calling it needs an Authorization: Bearer header from a service principal with the System Owner role, since a 3CX System Administrator cannot read recordings at all and will get a 403 that is about the role, not the credentials. Prefer threecx_get_recording_transcript for anything about what was said -- it answers the same questions from text 3CX already holds, with no audio involved. Reach for this only when the audio file itself is the deliverable: a subject access request, a dispute, a regulator. Call recordings are personal data. 3CX ships no built-in recording announcement -- its only notice mechanism is a per-queue Disabled / AllowToOptOut / AskToOptIn setting whose prompt audio the customer records themselves -- and 3CX's position is that the PBX owner, not 3CX, is the controller for this data. In all-party-consent jurisdictions, obtaining and passing on a recording carries obligations that exist whether or not this connector is in the loop, and a notice covering "recorded for training and quality purposes" does not obviously extend to onward disclosure. Since V20 Update 10 the PBX audits recording downloads, so a download driven through this tool is logged on the customer's own system and attributable to this service principal.

• threecx_get_recording_transcript

  Read-only

  The transcript, AI summary and sentiment score 3CX already stores on a recording, plus enough metadata to know whose call it was. This is the tool to reach for on "what was said on that call" or "summarise yesterday's support calls": the PBX holds these as plain text fields on the recording, so the answer arrives without any audio being fetched, copied or sent anywhere -- a much smaller footprint than the download tool for the same question. It only returns what is already there: fields are empty unless transcription has previously run on that recording, which IsTranscribed and CanBeTranscribed tell you. This connector deliberately has no tool to start transcription, because that sends call audio to a third-party AI provider and bills the customer. Treat the output as personal data in its own right -- a transcript, a summary and a sentiment score are all derived from the recording and describe an identifiable person's conversation, and the same consent and lawful-basis questions apply to them as to the audio. Role-gated like every recording read: a System Administrator cannot see recordings, a System Owner can, so a 403 is about the role rather than the credentials.

• threecx_list_recordings

  Read-only

  Call recordings held on the PBX, as metadata only -- when the call was, between which extension and which number, and whether a transcript exists. No audio and no transcript text is returned; use threecx_get_recording_transcript for the words, which is the path to prefer because it needs no audio at all. Filter by date range, extension or caller number, then take the Id of the row you want. Recordings and the metadata about them are personal data: they identify a caller, a callee and the fact and timing of a conversation between them, and in all-party-consent jurisdictions handling them carries obligations that exist independently of this connector. 3CX ships no built-in recording announcement -- the only notice mechanism it provides is a per-queue setting (Disabled / AllowToOptOut / AskToOptIn) whose prompt audio the customer records themselves -- so do not assume the people on these calls were told. Access is role-gated: a 3CX System Administrator cannot read recordings while a System Owner can, so a 403 here means the service principal's role is too narrow, not that the credentials are wrong. Bound the date range: this API answers too wide a query with a 504, not a rate-limit error.

Showing 1 of 1 tools

• threecx_list_my_profiles

  Read-only

  The forwarding / presence profiles belonging to the identity these API credentials authenticate as -- each profile's name, its custom status message, whether it rings the mobile, and the routes it sends available and away calls to. In 3CX a profile is a routing rule set, not a status badge: the active one decides where that extension's calls actually land. Two things to be clear about before using this. First, "my" means the service principal's own DN, which on most installs is the integration's account rather than any member of staff -- for a specific person, read their profiles through the user tools instead. Second, this connector is READ-ONLY on profiles: 3CX's public API exposes no way to activate a profile, set a profile message or apply an override, so a profile change has to be made by the person themselves in the 3CX client or by an admin in the console.