acoustic-connect

n8n node for Acoustic Connect - Marketing automation and customer engagement platform

Package Information

Downloads: 32 weekly / 45 monthly
Latest Version: 0.1.0
Author: Acoustic

Available Nodes

Acoustic Connect icon
Acoustic Connect
Interact with Acoustic Connect GraphQL API

Documentation

n8n-nodes-acoustic-connect

This is an n8n community node that lets you use Acoustic Connect in your n8n workflows.

Acoustic Connect is a comprehensive marketing automation and customer engagement platform that enables businesses to create personalized, data-driven marketing campaigns across multiple channels including email, SMS, and WhatsApp.

n8n is a fair-code licensed workflow automation platform.

Table of Contents

Installation

Follow the installation guide in the n8n community nodes documentation.

Quick Install

Within n8n, go to Settings > Community Nodes and search for n8n-nodes-acoustic-connect.

Manual Install

For local development or testing:

npm install n8n-nodes-acoustic-connect

Operations

The Acoustic Connect node provides 10 operations across 4 main resources:

Audience Operations

Manage contacts and audience data:

  • Get Contacts - Retrieve contacts from a data set with filtering, sorting, and pagination
  • Create Contacts - Add new contacts to a data set with attributes and consent
  • Update Contacts - Modify existing contacts using MERGE or REPLACE strategies
  • Delete Contacts - Remove contacts from a data set with reason tracking

Data Set Operations

Manage data schemas:

  • Get Data Sets - List all data sets with optional filtering and pagination
  • Update Data Set - Modify data set metadata, attributes, and associations

Data Job Operations

Manage data import jobs:

  • Get Data Jobs - List all data jobs with status filtering and pagination
  • Get Data Job - Retrieve details of a specific data job including results
  • Create Import Job - Create bulk data import jobs from SFTP or uploaded files

Message Operations

Send marketing messages:

  • Send Message - Send messages to segments or individual contacts across multiple channels (EMAIL, SMS, WHATSAPP, MOBILE) with personalization support

Credentials

To use this node, you need an Acoustic Connect account with API access.

Prerequisites

  1. An active Acoustic Connect account
  2. API key with appropriate permissions
  3. Knowledge of your account's region (US or EMEA)

Obtaining API Credentials

  1. Log in to your Acoustic Connect account
  2. Navigate to Settings > API Keys
  3. Generate a new API key or use an existing one
  4. Note your account region (US or EMEA)

Setting Up Credentials in n8n

  1. In n8n, go to Credentials > New
  2. Search for "Acoustic Connect API"
  3. Enter your credentials:
    • API Key: Your Acoustic Connect API key
    • Region: Select your account region (US or EMEA)
  4. Click Save to test the connection

The credential test will execute a simple query to verify your API key and region are correct.

Compatibility

  • Minimum n8n version: 0.199.0
  • Tested against: n8n v1.0.0+
  • Node.js version: >=20.15

This node uses:

  • n8n-workflow API version 1
  • TypeScript for type safety
  • GraphQL for API communication

Known Issues

None at this time. Please report any issues on GitHub.

Usage

Quick Start

  1. Add the Acoustic Connect node to your workflow
  2. Select a resource (Audience, Data Set, Data Job, or Message)
  3. Choose an operation (varies by resource)
  4. Configure parameters according to your needs
  5. Connect your credential (Acoustic Connect API)
  6. Execute the workflow

Common Use Cases

Example 1: Sync Contacts from External System

Webhook → Function (transform data) → Acoustic Connect (Create Contacts)

Automatically create contacts in Acoustic Connect when data arrives via webhook.

Example 2: Daily Contact Export

Schedule Trigger → Acoustic Connect (Get Contacts) → Function (format) → Send to SFTP

Export all contacts daily for backup or external processing.

Example 3: Import Contacts from CSV

Schedule Trigger → Acoustic Connect (Create Import Job) → Wait → Acoustic Connect (Get Data Job)

Create and monitor bulk import jobs on a schedule.

Example 4: Send Triggered Campaign

Webhook → Acoustic Connect (Get Contacts with filter) → Acoustic Connect (Send Message)

Send targeted messages based on external events.

Advanced Features

Filtering

Many operations support advanced filtering with 8 operators:

  • eq - Exact match
  • neq - Not equal
  • in - Match any value in list
  • nin - Not in list
  • like - Contains (case-insensitive)
  • blank - Field is null or empty
  • after - Date after (for timestamps)
  • before - Date before (for timestamps)

Example: Find contacts created after a specific date:

Field: tracking.createdAt
Operator: after
Value: 2025-01-01T00:00:00Z

Pagination

List operations support two modes:

  • Return All: Automatically fetches all pages (recommended)
  • Limit: Specify exact number of records

The node handles cursor-based pagination automatically.

Error Handling

Enable Continue on Fail in node settings to:

  • Process remaining items when errors occur
  • Return error objects instead of stopping workflow
  • Useful for batch operations where some items might fail

Tips and Best Practices

  1. Use "Return All" for complete data - Let the node handle pagination automatically
  2. Filter on the server - Use built-in filters instead of filtering in n8n for better performance
  3. Batch operations - Group contacts into batches of 100-500 for create/update operations
  4. Monitor import jobs - Poll job status after creating import jobs to track completion
  5. Handle errors gracefully - Enable "Continue on Fail" for batch operations
  6. Use merge strategy wisely - Choose MERGE to update specific fields or REPLACE to overwrite all

Detailed Usage Examples

For comprehensive usage examples with code samples and workflow configurations, see the Node README.

Resources

Official Documentation

Node Documentation

Support

Version History

v0.1.0 (2025-10-19) - Initial Release

P0 Features:

  • ✅ 4 Resources: Audience, Data Set, Data Job, Message
  • ✅ 10 Operations: Full CRUD + bulk imports + messaging
  • ✅ Advanced filtering with 8 operators
  • ✅ Automatic pagination support
  • ✅ Comprehensive error handling
  • ✅ Multi-channel messaging (EMAIL, SMS, WHATSAPP, MOBILE)
  • ✅ TypeScript type safety
  • ✅ 176+ comprehensive tests
  • ✅ Complete documentation

API Coverage:

  • Audience: Get, Create, Update, Delete
  • Data Set: Get, Update
  • Data Job: Get (list), Get (single), Create Import
  • Message: Send

Known Limitations:

  • Segment operations not yet implemented (planned for future release)
  • Template operations not yet implemented (planned for future release)
  • Campaign operations not yet implemented (planned for future release)

Development

Setup

# Clone the repository
git clone https://github.com/acoustic/n8n-nodes-acoustic-connect.git
cd n8n-nodes-acoustic-connect

# Install dependencies
npm install

# Build the node
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Check code quality
npm run lint

# Auto-fix linting issues
npm run lintfix

# Format code
npm run format

Development Workflow

# Start development mode (auto-rebuild on changes)
npm run dev

# In another terminal, link to n8n
npm link
cd ~/.n8n/custom
npm link n8n-nodes-acoustic-connect

# Start n8n
n8n start

Project Structure

n8n-nodes-acoustic-connect/
├── nodes/AcousticConnect/          # Node implementation
│   ├── AcousticConnect.node.ts    # Main node class
│   ├── descriptions/               # UI field definitions
│   ├── operations/                 # Operation implementations
│   ├── helpers/                    # Utility functions
│   └── types/                      # TypeScript types
├── credentials/                    # Credential definitions
├── __tests__/                      # Test suite
├── docs/                          # Documentation
│   ├── architecture/              # Architecture docs
│   ├── plans/                     # Implementation plans
│   └── product/                   # Product docs
└── dist/                          # Build output

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Add tests for new functionality
  5. Run tests and linting (npm test && npm run lint)
  6. Commit your changes (git commit -m 'Add amazing feature')
  7. Push to the branch (git push origin feature/amazing-feature)
  8. Open a Pull Request

Testing

# Run all tests
npm test

# Run specific test file
npm test AudienceOperations

# Generate coverage report
npm run test:coverage

# Watch mode for development
npm run test:watch

Code Quality

This project uses:

  • TypeScript for type safety
  • ESLint with n8n-specific rules
  • Prettier for code formatting
  • Jest for testing

Architecture

The node follows a clean architecture pattern with separation of concerns:

  1. Main Node (AcousticConnect.node.ts) - Routes operations
  2. Descriptions - UI field definitions
  3. Operations - Business logic implementation
  4. Helpers - Reusable utilities (GraphQL builder, response parser)
  5. Types - TypeScript type definitions

For detailed architecture documentation, see docs/architecture/README.md.

License

MIT

Copyright (c) 2025 Acoustic

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Built with ❤️ by the Acoustic team

For questions, issues, or contributions, visit our GitHub repository.

Discussion