sonax-voip

Sonax VoIP community node for n8n with 9 operations.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.1
Author: Connect

Documentation

n8n-nodes-sonax-voip

This n8n community node package lets you use the Sonax PBX/Voice API (click-to-call, dialer campaigns, IVR, recordings) in your n8n workflows.

n8n is a fair-code licensed workflow automation platform.

Installation
Operations
Credentials
Compatibility
Usage
Resources
Version history

Installation

Follow the official manual installation guide for community nodes, using the package name n8n-nodes-sonax-voip.

This is a sibling package to n8n-nodes-sonax-chat, developed in the same repository. Install this one if you only need the Voice/PBX operations; install both if you also need Sonax Chat.

Operations

Add Sonax VoIP to your workflow, then select its Operation:

Operation What it does
Click to Call Originates a call from an extension to a phone number.
Create Queue Campaign Creates a dialer campaign that sends answered calls to a human queue.
Create IVR Campaign Creates a dialer campaign that sends answered calls to an IVR or voicebot.
Add Contact to Campaign Adds one contact to an existing campaign's mailing.
Add Contacts File to Campaign Adds many contacts at once by uploading a contacts file from a binary field.
Start Campaign Puts a campaign into execution (play).
Stop Campaign Stops an active campaign.
Get Call Recording Returns the recording of a call: as binary audio, or as JSON when Sonax returns a link.
Get Call Status Returns the status and outcome of a specific call.

Selecting items by name

Queue, campaign and IVR fields are drop-downs filled from the Sonax APIs: you see names, the node sends the matching ID. You can always switch a field to an expression to supply a value yourself, for example an ID coming from a previous node.

Extensions (Click to Call) have no listing endpoint and are typed.

The IVR drop-down comes from the Voice v2 API, which needs the optional Voice V2 Password (see Credentials). Without it, switch the IVR field to an expression and type the IVR ID shown in your Sonax PBX panel; Create IVR Campaign itself only uses the Voice v1 API.

Credentials

Sonax VoIP API

Field Description
Client ID Provided by Sonax when your PBX was activated.
API Token Voice API token (v1) provided by Sonax together with your Client ID.
Voice V2 Password Optional. Only needed to load the IVR drop-down in Create IVR Campaign. The login ID is your Client ID. Each time the list is opened, the node logs in to the Voice v2 API (POST https://apiv2.sonax.net.br/login) and asks for the IVRs with a fresh token, which is valid for 24 hours and is never stored, so nothing expires in your workflows.

Saving the credential runs a read-only test (listing queues). The credential refuses to send secrets to any host other than the documented Sonax endpoints, and secrets are stored as password fields.

You need a Sonax PBX account. Sonax provides the Client ID and tokens.

Compatibility

Built against n8n-workflow 2.16.0 (n8n nodes API version 1). Request routing is tested with the real n8n-core 2.23.1 declarative router. The package has no additional runtime dependencies.

If you have a workflow using an earlier combined sonax node, or the intermediate n8n-nodes-sonax.sonaxVoip type, convert it locally without executing it. From the repository root:

node scripts/migrate-split-nodes.cjs workflow-original.json workflow-migrado.json

Usage

Import the call-status example, select your Sonax VoIP credential, and replace the placeholder ID with an existing call ID.

  • Add Contacts File to Campaign uploads the file from a binary field of the incoming item (default field name data) unchanged. Use a file format accepted by Sonax's upload de arquivo de contato action. Read the file with a node such as Read/Write Files from Disk or HTTP Request first.
  • Get Call Recording writes audio to the binary field set in Output Binary Field (default data). If Sonax answers with a link or JSON instead of audio, that is returned as JSON.
  • Dates and times follow the formats in Sonax's documentation: campaign start/end time HH:mm:ss, scheduled contact time YYYY-MM-DD HH:mm:ss (in the PBX time zone), weekdays 1-7 as configured in your PBX.
  • The Sonax API sometimes reports failures with HTTP 200 and an error body. The node turns those into regular n8n errors, so Continue On Fail and error workflows behave as expected.
  • This node can also be used as an AI agent tool. Binary-input/output operations (Add Contacts File to Campaign, Get Call Recording) depend on binary data flowing through the workflow and are not practical to call from an agent; prefer the other operations for AI-driven use.

Validation

npm run lint
npm test

Resources

Version history

See CHANGELOG.md.

Discussion