n8n-nodes-3cx

A comprehensive n8n community node for integrating with 3CX telephony systems. This node provides access to all 3CX Management API operations, enabling automation of call management, user administration, reporting, and system configuration.

Features

• Complete 3CX API Coverage: Access to all 3CX Management API endpoints
• OAuth 2.0 Authentication: Secure service-to-service authentication using Client Credentials flow
• Telephony Operations: Manage active calls, call history, extensions, users, and system settings
• Advanced Filtering: Support for OData query parameters including filtering, pagination, and sorting
• Auto-generated: Built from 3CX's official OpenAPI specification for accuracy and completeness

Installation

To use this node, you need to install it in your n8n instance:

# For community version
npm install n8n-nodes-3cx

# For self-hosted n8n
cd ~/.n8n/nodes
npm install n8n-nodes-3cx

# Restart n8n

Configuration

Prerequisites

1. 3CX System: A running 3CX phone system (version 18 or later recommended)
2. API Access: Enabled 3CX Management API
3. OAuth Credentials: Service principal configured in your 3CX system

Setting up OAuth 2.0 Credentials

1. In n8n, go to Credentials → Create New Credential
2. Search for "3CX OAuth 2.0 API" and select it
3. Fill in the required fields:

• Server URL: Your 3CX server URL (e.g., https://your-3cx-server.com)
• Access Token URL: Your OAuth token endpoint (e.g., https://your-3cx-server.com/connect/token)
• Client ID: OAuth 2.0 Client ID from your 3CX system
• Client Secret: OAuth 2.0 Client Secret from your 3CX system

3CX System Configuration

To obtain OAuth credentials for your 3CX system:

1. Log into your 3CX Management Console
2. Navigate to Settings → Security → API
3. Create a new service principal/application
4. Note the generated Client ID and Client Secret
5. Ensure the service principal has appropriate permissions for the operations you want to perform

Usage

Once installed and configured, the 3CX node provides access to the following resources:

Available Resources

• Active Calls: Monitor and manage currently active phone calls
• Call History: Access historical call records and logs
• Extensions: Manage phone extensions and settings
• Users: Administer user accounts and permissions
• Call Queues: Manage call queues and statistics
• Call Recordings: Access and manage call recordings
• Reports: Generate system reports and analytics
• System: System administration and configuration
• Voicemail: Manage voicemail messages and settings
• Conferences: Manage conference rooms and calls
• Trunks: Manage SIP trunks and connectivity
• Phone Book: Manage contacts and phone directories

Example Workflows

Get Active Calls

1. Add 3CX node to your workflow
2. Select Resource: "Active Calls"
3. Select Operation: "Get Active Calls"
4. Configure any filters (optional)
5. Execute to retrieve current call status

Query Call History

1. Add 3CX node to your workflow
2. Select Resource: "Call History"
3. Select Operation: "Get Call History"
4. Add OData filters (e.g., "Duration gt 60" for calls longer than 60 seconds)
5. Set pagination options if needed
6. Execute to retrieve call records

OData Query Support

The 3CX node supports advanced OData query parameters for filtering and pagination:

• $filter: Filter results using OData expressions
  • Examples: State eq 'Connected', Duration gt 30, Extension eq '101'
• $top: Limit number of results (1-1000)
• $skip: Skip records for pagination
• $orderby: Sort results by specified fields
• $select: Choose specific fields to return
• $expand: Include related entities in the response

Error Handling

The node includes comprehensive error handling for common scenarios:

• Authentication Errors: Clear messages for credential issues
• Rate Limiting: Automatic handling of API rate limits
• Network Issues: Retry logic for temporary connectivity problems
• Invalid Parameters: Validation of input parameters

Development

This node was generated using the @devlikeapro/n8n-openapi-node tool from 3CX's official OpenAPI specification.

Building from Source

git clone <repository-url>
cd n8n-nodes-3cx
npm install
npm run build

Testing

npm test

Support

• 3CX Documentation: 3CX API Documentation
• n8n Community: n8n Community Forum
• Issues: Report issues in this repository's issue tracker

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This is a community-developed node and is not officially supported by 3CX Ltd. 3CX is a trademark of 3CX Ltd.

Version History

• 0.1.0: Initial release with complete 3CX Management API coverage

  • OAuth 2.0 authentication
  • All 3CX API endpoints
  • OData query support
  • Custom resource and operation parsers

• 1.0.11: Make OData query params optional and grouped under an "Options" collection

  • $filter, $select, $expand, $orderby, $count, $search, $top, $skip are not sent unless set
  • Fixes list operations failing due to defaulted values (e.g., [null])

• 1.0.12: Ensure list GET endpoints expose the Options group even when the OpenAPI spec omits OData params

  • Adds a standard Options collection to list operations like /Users, /Queues when missing
  • Still sends no params by default; expand Options only when needed

• 1.0.13: Fix parameter dependency resolution in n8n UI

  • Removed displayOptions from children inside Options collections to prevent resolver loops
  • Keeps all OData toggles optional and non-sent by default

• 1.0.14: Improve $search handling

  • Automatically wraps search phrases containing spaces in quotes (e.g., Joshua Bedania -> "Joshua Bedania")
  • Avoids 400 "Invalid search Term" from 3CX

• 1.0.15: Credential UX

  • Access Token URL is now optional and auto-filled from Server URL (/connect/token)
  • Reduces setup friction—only Server URL, Client ID, and Client Secret are needed

• 1.0.16: Maintenance bump

  • No functional changes; republish with latest credential and search improvements

• 1.0.17: Credential polish

  • Access Token URL is hidden for Client Credentials (still auto-derived from Server URL)
  • Keeps the field visible only for Authorization Code scenarios

• 1.0.18: UI polish

  • Updated 3CX node SVG icon

• 1.0.24: Credential UX hardening

  • Access Token URL is now required and user-entered (no dynamic default)
  • Fixes cases where expression defaults didn’t resolve in n8n UI
  • Base URL handling normalized to avoid double slashes

• 1.0.25: Fix credential test/content-type regression

  • Revert test request to only send Accept: application/json (no Content-Type on GET)
  • Default OAuth2 Authentication back to Body for client credentials

Made with ❤️ for the n8n community

Authentication Notes

This package uses n8n's built-in OAuth 2.0 with Client Credentials for 3CX.

• Access Token URL: https://<your-3cx>/connect/token
• Grant Type: Client Credentials
• Authentication: Body (client_id and client_secret in the form body)
• Test endpoint used by the credential: GET https://<your-3cx>/xapi/v1/SystemStatus with Accept: application/json

Expected successful response example:

{
  "@odata.context": "https://<your-3cx>/xapi/v1/$metadata#SystemStatus",
  "FQDN": "...",
  "Version": "...",
  "Activated": true,
  "MaxSimCalls": 128,
  ...
}