n8n-nodes-sip-trunk

This is an n8n community node that enables SIP trunk integration for voice calling with support for multiple providers including Twilio, Sipgate, Deutsche Telekom, Gamma, and Ecotel. It provides audio streaming capabilities for integration with services like ElevenLabs.

Features

• Server-Side Implementation: Fully Node.js compatible - works in any n8n installation (Docker, VPS, Cloud, Desktop)
• SIP Digest Authentication: RFC 3261 compliant authentication with automatic challenge-response for all major providers
• NAT Traversal: Built-in STUN support for automatic public IP discovery and NAT traversal
• Multiple SIP Providers: Pre-configured support for Twilio, Sipgate, Deutsche Telekom, Gamma, Ecotel, and custom SIP servers
• Trigger & Action Modes:
  • Trigger mode to receive incoming calls
  • Action mode to make calls and control existing calls
• Call Operations: Make calls, hangup, get audio recordings
• Real Audio Capture: Direct RTP audio capture and processing on the server
• Audio Streaming: Output audio in base64 format (for ElevenLabs STT) or WebSocket stream for real-time processing
• Built-in Transcription: Direct integration with ElevenLabs, OpenAI Whisper, AssemblyAI, and Deepgram
• Flexible Transport: Support for UDP, TCP, TLS
• WAV Audio Export: Automatic conversion to WAV format (8kHz, 16-bit, mono)

Installation

Community Node Installation

1. Go to Settings > Community Nodes in your n8n instance
2. Select Install a community node
3. Enter n8n-nodes-sip-trunk and install

Manual Installation

npm install n8n-nodes-sip-trunk

Architecture

Server-Side SIP & RTP Handling

This node is built with pure Node.js components, making it compatible with any n8n installation:

• SIP Protocol: Custom UDP-based SIP client for signaling (REGISTER, INVITE, BYE)
• RTP Audio: Direct UDP socket handling for real-time audio packet capture
• Audio Processing: Server-side WAV encoding using the wav library
• WebSocket Server: Built-in WebSocket server for real-time audio streaming
• Session Management: In-memory session tracking across multiple concurrent calls

Why Server-Side?

Unlike browser-based WebRTC implementations, this node:

• ✅ Works in Docker containers
• ✅ Works on VPS/Cloud servers
• ✅ Works in n8n Desktop
• ✅ No browser environment required
• ✅ Direct RTP packet processing
• ✅ Lower latency and overhead

Authentication & NAT Support

SIP Digest Authentication (RFC 3261):

• Automatic challenge-response authentication
• Supports MD5 and SHA-256 algorithms
• Handles 401/407 authentication challenges
• Works with all major SIP providers

STUN for NAT Traversal (RFC 5389):

• Automatic public IP/port discovery
• Works behind home/office NAT
• Works in Docker containers
• Multiple public STUN servers configured
• Optional custom STUN server support

How NAT Traversal Works:

1. Node starts behind NAT (private IP: 192.168.1.100)
2. STUN request to stun.l.google.com
3. STUN response: public IP 203.0.113.45:52891
4. SIP messages use public IP in headers
5. RTP audio flows directly using discovered address
6. ✅ Calls work from anywhere!

Network Requirements

For the node to work properly, ensure:

• UDP ports: Open for SIP signaling (default 5060) and RTP audio (dynamic range 10000-20000)
• Firewall rules: Allow incoming/outgoing UDP traffic
• NAT traversal: STUN enabled by default (configurable)
• Provider compatibility: All major providers supported with proper authentication

Credentials Setup

Authentication Methods

All providers use SIP Digest Authentication (RFC 3261). The node automatically handles authentication challenges.

Twilio

1. Log in to your Twilio Console
2. Navigate to Elastic SIP Trunking → Select or create your SIP Trunk
3. Note your Termination SIP URI (e.g., yourtrunk.pstn.twilio.com)
4. Go to Authentication tab and note your credentials
5. In n8n, configure:
   • Provider: Twilio
   • SIP Server: Your Termination SIP URI (e.g., mytrunk.pstn.twilio.com or mytrunk.pstn.ashburn.twilio.com)
   • Username: Your SIP trunk username
   • Password: Your SIP trunk password
   • Port: 5060
   • Transport: UDP

Important: Each Twilio account has a unique SIP trunk domain. You must enter YOUR specific trunk URI from the Twilio console.

Sipgate

1. Log in to Sipgate
2. Go to Settings > SIP Credentials
3. Create or view existing SIP credentials
4. In n8n, configure:
   • Provider: Sipgate
   • Username: Your Sipgate SIP ID (e.g., 1234567e0)
   • Password: Your SIP password
   • SIP Server: sipgate.de (auto-configured)
   • Transport: WebSocket Secure (wss)

Deutsche Telekom

1. Log in to your Telekom account
2. Navigate to IP-based telephony settings
3. Get your SIP credentials
4. In n8n, configure:
   • Provider: Deutsche Telekom
   • Username: Your registration ID
   • Password: Your SIP password
   • SIP Server: tel.t-online.de (auto-configured)
   • Transport: TLS or WebSocket Secure

Gamma

1. Access your Gamma portal
2. Navigate to SIP Trunk settings
3. Get your authentication credentials
4. In n8n, configure:
   • Provider: Gamma
   • Username: Your SIP username
   • Password: Your SIP password
   • SIP Server: sip.gamma.co.uk (auto-configured)
   • Transport: WebSocket Secure (wss)

Ecotel

1. Access your Ecotel nBSS portal
2. Get your contract number and SIP credentials
3. Note your assigned realm (format: nbss-xxxxxx.sip-ecotel.de)
4. In n8n, configure:
   • Provider: Ecotel
   • Username: BSS + your contract number (e.g., BSS123456)
   • Password: Your SIP password
   • SIP Server: trunkf.sip-ecotel.de or trunkd.sip-ecotel.de (auto-configured)
   • Port: 5083
   • Transport: UDP
   • NAT Traversal Options:
     • Enable STUN: false (⚠️ Important: Ecotel does not use STUN servers)

Important Notes:

• Ecotel uses specific media ports: UDP 10000-59999 (ensure these are open in your firewall)
• STUN must be disabled for Ecotel connections
• Authentication realm is contract-specific (nbss-xxxxxx.sip-ecotel.de)
• Uses standard SIP Digest Authentication (MD5)

Custom SIP Provider

For any other SIP provider:

1. Get your SIP credentials from your provider
2. In n8n, configure:
   • Provider: Custom
   • SIP Server: Your provider's SIP server hostname
   • Username: Your SIP username/URI
   • Password: Your SIP password
   • Port: Default 5060 (UDP/TCP) or 5061 (TLS)
   • Transport: Choose appropriate protocol

Usage

Trigger Mode: Receiving Calls

1. Add the SIP Trunk node to your workflow
2. Set Mode to "Trigger (Receive Calls)"
3. Configure:
   • Audio Output Format: Choose between Base64, WebSocket, or Both
   • Auto Answer: Enable to automatically answer incoming calls
   • Recording Duration: Set maximum recording time (0 for unlimited)
4. The node will output call data including:
   • from: Caller's number
   • to: Destination number
   • callId: Unique call identifier
   • sessionId: Session ID for call control
   • audioBase64: Audio data in base64 (if selected)
   • webSocketUrl: WebSocket URL for audio stream (if selected)

Action Mode: Making Calls

1. Add the SIP Trunk node to your workflow
2. Set Mode to "Action"
3. Set Operation to "Make Call"
4. Configure:
   • Phone Number: Destination number in E.164 format (e.g., +1234567890)
   • Audio Output Format: Choose output format
   • Recording Duration: Set recording time
5. The node will initiate the call and return session information

Action Mode: Hangup Call

To end an active call:

1. Set Mode to "Action"
2. Set Operation to "Hangup"
3. Provide the Session ID from the call you want to end
4. The node will terminate the call and return duration information

Action Mode: Get Audio

To retrieve recorded audio from an active or completed call:

1. Set Mode to "Action"
2. Set Operation to "Get Audio"
3. Provide the Session ID of the call
4. Choose Audio Output Format (base64 or WebSocket)
5. The node will return:
   • audioBase64: WAV audio encoded as base64 (if base64 format selected)
   • audioFormat: "audio/wav"
   • sampleRate: 8000 Hz
   • channels: 1 (mono)
   • audioSize: Size in bytes
   • duration: Call duration in seconds

Integration with ElevenLabs

To use the audio output with ElevenLabs STT:

{
  "workflow": {
    "nodes": [
      {
        "name": "SIP Trunk Trigger",
        "type": "n8n-nodes-sip-trunk.sipTrunk",
        "parameters": {
          "mode": "trigger",
          "audioFormat": "base64",
          "autoAnswer": true
        }
      },
      {
        "name": "ElevenLabs STT",
        "type": "n8n-nodes-elevenlabs",
        "parameters": {
          "operation": "speechToText",
          "audioData": "={{$node['SIP Trunk Trigger'].json.audioBase64}}"
        }
      }
    ]
  }
}

Example Workflows

1. Auto-Answer and Transcribe

[SIP Trunk Trigger] → [ElevenLabs STT] → [Process Text]

2. Outbound Call with Recording

[Schedule/Webhook] → [SIP Trunk Make Call] → [Save Audio] → [ElevenLabs TTS Response]

3. Call Routing

[SIP Trunk Trigger] → [Switch Node] → [Route Based on Caller] → [Custom Action]

4. Get Audio After Call

[SIP Trunk Make Call] → [Wait/Delay] → [Get Audio Operation] → [ElevenLabs STT]

Audio Formats

Base64 Encoded Audio

• Best for: ElevenLabs STT, storing recordings, sending to APIs
• Format: WAV audio (PCM, 8kHz, 16-bit, mono) encoded as base64 string
• Sample Rate: 8000 Hz (telephone quality)
• Codec Support: PCMU (G.711 μ-law) and PCMA (G.711 A-law)
• Usage: Direct input to ElevenLabs or other STT services

Example output:

{
  "audioBase64": "UklGRiQAAABXQVZFZm10...",
  "audioFormat": "audio/wav",
  "sampleRate": 8000,
  "channels": 1,
  "audioSize": 128000
}

WebSocket Stream

• Best for: Real-time processing, live transcription
• Format: JSON messages with base64-encoded audio chunks
• Connection: Standard WebSocket (ws://)
• Usage: Connect to real-time processing services

Example WebSocket message:

{
  "sessionId": "abc123",
  "audio": "base64_chunk_here",
  "timestamp": 1234567890
}

Limitations

• UDP-based: Requires open UDP ports for SIP signaling and RTP audio
• NAT traversal: May need STUN/TURN configuration for complex network setups
• Memory usage: Audio is stored in memory during recording
• Concurrent calls: Limited by available memory and network bandwidth
• Authentication: Currently supports basic username/password authentication (SIP authentication challenges not yet implemented)
• Codecs: Supports PCMU (G.711 μ-law) and PCMA (G.711 A-law) - most common telephony codecs

Development

Building from Source

npm install
npm run build

Testing

npm run lint
npm test

Troubleshooting

Connection Issues

1. WebSocket connection fails: Ensure your SIP provider supports WebSocket transport
2. Authentication errors: Verify credentials and username format (some providers require full SIP URI)
3. No audio: Check that WebRTC is supported in your environment

Provider-Specific Issues

Twilio

• Use WebSocket Secure (wss) transport
• Ensure you're using the correct regional WebSocket URL
• Account SID as username, Auth Token as password

Sipgate

• SIP ID format is usually numeric followed by 'e' (e.g., 1234567e0)
• Use WebSocket transport for best compatibility

Deutsche Telekom

• May require TLS transport
• Check that IP-based telephony is enabled on your account

Support

For issues, questions, or contributions:

• GitHub Issues: [Create an issue]
• Documentation: n8n Community Nodes Docs

License

MIT

Credits

Built with:

• SIP.js - JavaScript SIP library
• n8n - Workflow automation platform