n8n-nodes-3cx-sip-call/README.md

n8n custom node for 3CX SIP integration. Make calls, send messages, and register SIP accounts directly from your workflows

# n8n-nodes-3cx-sip-call

[![npm version](https://img.shields.io/npm/v/n8n-nodes-3cx-sip-call.svg)](https://www.npmjs.com/package/n8n-nodes-3cx-sip-call)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

n8n custom node for 3CX SIP integration. This node allows you to interact with 3CX SIP servers to make calls, send messages, and register SIP accounts directly from your n8n workflows.

## Features

- ✅ **Make Calls**: Initiate internal or external SIP calls via 3CX
- ✅ **Receive Calls**: Wait for and auto-answer incoming SIP calls
- ✅ **Send Messages**: Send SIP messages to other extensions
- ✅ **Register Account**: Register SIP account with 3CX server
- ✅ **Easy Configuration**: Simple credential setup in n8n
- ✅ **TypeScript**: Built with TypeScript for better reliability

## Installation

### Method 1: Via n8n UI (Recommended)

1. Open your n8n instance
2. Go to **Settings** > **Community Nodes**
3. Click **Install a community node**
4. Enter: `n8n-nodes-3cx-sip-call`
5. Click **Install**

### Method 2: Via npm

```bash
npm install n8n-nodes-3cx-sip-call
```

Then restart your n8n instance.

## Configuration

### Step 1: Create Credentials

1. In n8n, go to **Credentials** > **New**
2. Search for **3CX SIP API**
3. Fill in your 3CX SIP server details:

   - **SIP Server Address**: Your 3CX SIP server IP address (e.g., `10.30.0.2`)
   - **SIP Server Port**: SIP server port (default: `5060`)
   - **Auth ID**: Your authentication ID (e.g., `Jd7S9hsA30`)
   - **Extension Number**: Your extension number (e.g., `1070`)
   - **Password**: Your SIP account password

### Step 2: Example Configuration

```
SIP Server: 10.30.0.2
Port: 5060
Auth ID: Jd7S9hsA30
Extension: 1070
Password: o8oIsWzW6V
```

## Usage

### Make a Call

1. Add the **3CX SIP** node to your workflow
2. Select **"Make Call"** operation
3. Configure the call parameters:
   - **Destination Number**: Phone number to call
     - External number: `0539372XXXX` or `90539372XXXX`
     - Internal extension: `1001`
   - **Caller ID (From)**: Optional - Caller ID to display (defaults to extension from credentials)
     - Example: `1070` (leave empty to use default extension)
4. Connect your credentials
5. Execute the workflow

**Example: Call from extension 1070 to external number 0539372XXXX**
- Destination Number: `0539372XXXX`
- Caller ID: `1070` (or leave empty)

**Output:**
```json
{
  "success": true,
  "message": "Call initiated",
  "destination": "539372XXXX",
  "callerId": "1070",
  "fromExtension": "1070",
  "sessionId": "call-id-123456"
}
```

### Send a Message

1. Add the **3CX SIP** node to your workflow
2. Select **"Send Message"** operation
3. Enter the message content
4. Enter the destination number
5. Connect your credentials
6. Execute the workflow

**Output:**
```json
{
  "success": true,
  "message": "Message sent successfully",
  "to": "1001",
  "content": "Hello from n8n!"
}
```

### Receive a Call

1. Add the **3CX SIP** node to your workflow
2. Select **"Receive Call"** operation
3. Configure the wait/answer behavior:
   - **Max Wait Time (seconds)**: How long to wait for an incoming call (default: 30)
   - **Auto Answer**: Automatically answer the call when it arrives (default: true)
4. Connect your credentials
5. Execute the workflow and wait for an incoming call

**Output:**
```json
{
  "success": true,
  "message": "Incoming call handled",
  "caller": "0539372XXXX",
  "callee": "1070",
  "callId": "call-id-456",
  "autoAnswered": true
}
```

### Register Account

1. Add the **3CX SIP** node to your workflow
2. Select **"Register"** operation
3. Connect your credentials
4. Execute the workflow to register your SIP account

**Output:**
```json
{
  "success": true,
  "message": "SIP account registered successfully",
  "extension": "1070",
  "sipServer": "10.30.0.2"
}
```

## Workflow Examples

### Example 1: Call External Number from Extension

```
Manual Trigger → 3CX SIP (Make Call) → Response
```

**Node Configuration:**
- Operation: Make Call
- Destination Number: `0539372XXXX`
- Caller ID: `1070`

Call from extension 1070 to external number 0539372XXXX.

### Example 2: Call on Webhook Trigger

```
Webhook → 3CX SIP (Make Call) → Response
```

When a webhook is received, automatically make a call to a predefined number. Use `{{$json.phoneNumber}}` to get the number from webhook data.

### Example 3: Send SMS via SIP Message

```
Schedule Trigger → 3CX SIP (Send Message) → Log
```

Send a daily reminder message via SIP.

### Example 4: Register and Monitor

```
3CX SIP (Register) → Wait → 3CX SIP (Make Call)
```

Register the account first, then make a call after a delay.

### Example 5: Auto-Answer Incoming Call

```
Manual Trigger → 3CX SIP (Receive Call)
```

Use the node to register and wait up to 30 seconds for an incoming call. When the call arrives it is automatically answered so the rest of the workflow can continue (e.g., notify a team, log the call, etc.).

## Technical Details

### Transport Protocol

This node uses **WebSocket transport** by default. The implementation uses the `sip.js` library which primarily supports WebSocket connections.

**Important Notes:**
- If your 3CX server requires UDP transport, you may need to configure a SIP proxy
- Ensure your 3CX server supports WebSocket connections
- For production use, test thoroughly with your 3CX configuration

### Dependencies

- `sip.js`: ^0.20.0 - SIP protocol implementation
- `n8n-workflow`: n8n workflow types and interfaces

## Development

### Prerequisites

- Node.js >= 14
- npm >= 6
- n8n instance

### Build from Source

```bash
# Clone the repository
git clone https://github.com/abdurrahimceylan/n8n-nodes-3cx-sip-call.git
cd n8n-nodes-3cx-sip-call

# Install dependencies
npm install

# Build the project
npm run build
```

### Development Mode

```bash
# Watch mode for development
npm run dev
```

### Code Quality

```bash
# Lint code
npm run lint

# Fix linting issues
npm run lintfix

# Format code
npm run format
```

## Troubleshooting

### Connection Issues

- Verify your SIP server address and port are correct
- Check firewall settings
- Ensure 3CX server is accessible from your n8n instance

### Authentication Errors

- Double-check your Auth ID, Extension, and Password
- Verify credentials in 3CX management console
- Ensure the extension is enabled for SIP

### WebSocket Connection Failed

- Confirm 3CX supports WebSocket connections
- Check if a proxy is required
- Review 3CX server logs for connection attempts

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details

## Author

**Abdurrahim CEYLAN**

## Support

For issues and questions:
- Open an issue on [GitHub](https://github.com/abdurrahimceylan/n8n-nodes-3cx-sip-call/issues)
- Check n8n community forums

## Related Links

- [n8n Documentation](https://docs.n8n.io/)
- [3CX Documentation](https://www.3cx.com/docs/)
- [SIP.js Documentation](https://sipjs.com/)

---

**Note**: This is a community node. For production use, please test thoroughly with your 3CX server configuration.