n8n-nodes-wasasa

Professional WhatsApp automation for n8n workflows

This is an n8n community node that provides comprehensive WhatsApp integration through the Wasasa API. Automate your WhatsApp communications with powerful workflows, send various message types, manage instances, and build sophisticated chatbot solutions.

n8n is a fair-code licensed workflow automation platform.

📋 Table of Contents

• Features
• Installation
• Credentials
• Operations
  • Instance Resource
  • Message Resource
  • Wasasa Trigger
• Usage Examples
• API Compatibility
• Development
• Troubleshooting
• Version History
• Contributing
• License

✨ Features

🎯 Complete WhatsApp Automation

• 2 Nodes (Wasasa + Wasasa Trigger)
• 16 Operations across 2 resources (Instance & Message)
• 8 Message Types supported (Text, Image, Video, Document, Audio, Location, Contact, Poll)
• 5 Trigger Events (Message, Group Message, Status, Call, Any)
• Instance Management with full lifecycle control
• Real-time Status monitoring and QR code generation
• Webhook Integration for event-driven workflows

🚀 Production Ready

• Built with TypeScript for type safety
• Declarative routing for clean code
• Comprehensive error handling
• Follows n8n best practices
• Fully tested and documented

💡 Developer Friendly

• Auto-complete for instance selection
• Intuitive field organization
• Clear operation descriptions
• Extensive inline documentation

📦 Installation

Via n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings > Community Nodes
3. Click Install
4. Enter n8n-nodes-wasasa
5. Agree to the risks and click Install
6. Restart n8n

Via npm

npm install n8n-nodes-wasasa

Manual Installation

cd ~/.n8n/nodes
git clone https://github.com/wasasa/n8n-nodes-wasasa.git
cd n8n-nodes-wasasa
npm install
npm run build

🔐 Credentials

Wasasa API Credentials

Before using this node, you need to configure your Wasasa API credentials:

1. In n8n, go to Credentials > New Credential
2. Search for Wasasa API
3. Fill in the required fields:

| Field | Description | Example | |-------|-------------|---------| | API URL | Base URL of your Wasasa API server | https://api.wasasa.com or http://localhost:8080 | | API Key | Your Wasasa API authentication key | your-secret-api-key |

4. Click Test to verify the connection
5. Click Save

Note: The credential test will attempt to fetch your instances list to verify connectivity.

🎛️ Operations

Instance Resource

Manage your WhatsApp instances with full lifecycle control.

📝 Available Operations

| Operation | Description | HTTP Method | Endpoint | |-----------|-------------|-------------|----------| | Create | Create a new WhatsApp instance | POST | /instance/create | | Get | Get information about a specific instance | GET | /instance/:id | | Get All | List all available instances | GET | /instance/fetchInstances | | Delete | Permanently delete an instance | DELETE | /instance/delete/:id | | Get QR Code | Retrieve QR code for connecting | GET | /instance/connect/:id/image | | Get Status | Check connection status | GET | /instance/connectionState/:id | | Logout | Disconnect and logout instance | DELETE | /instance/logout/:id | | Update Settings | Modify instance configuration | PUT | /instance/update/:id |

⚙️ Update Settings Fields

When using Update Settings, you can configure:

• Reject Calls - Automatically reject incoming calls
• Always Online - Keep online status active 24/7
• Read Messages - Mark messages as read automatically
• Webhook URL - Endpoint for receiving events

Message Resource

Send various types of messages to WhatsApp contacts.

📨 Available Operations

| Operation | Description | Required Fields | Optional Fields | |-----------|-------------|-----------------|-----------------| | Send Text | Send a text message | number, text | - | | Send Image | Send an image | number, media (URL) | caption | | Send Video | Send a video | number, media (URL) | caption | | Send Document | Send a document/file | number, media (URL) | fileName, caption | | Send Audio | Send an audio file | number, audio (URL) | - | | Send Location | Send GPS coordinates | number, latitude, longitude | name, address | | Send Contact | Send a contact card | number, displayName, vcard | - | | Send Poll | Send a poll/survey | number, name, options (2-12) | selectCount |

📋 Field Details

Common Fields:

• instanceName - WhatsApp instance to use (auto-complete enabled)
• number - Phone number without + or country code (e.g., 1234567890)

Media Fields:

• media / audio - Public URL of the file to send
• caption - Optional text caption for media
• fileName - Custom filename for documents

Location Fields:

• latitude - GPS latitude coordinate (e.g., 19.4326)
• longitude - GPS longitude coordinate (e.g., -99.1332)
• name - Location name (e.g., "Mexico City")
• address - Full address text

Contact Fields:

• displayName - Name to display
• vcard - vCard format contact data (see example below)

Poll Fields:

• name - Poll question
• options - Array of 2-12 answer options
• selectCount - Number of selections allowed (default: 1)

Wasasa Trigger

Automatically start workflows when WhatsApp events occur.

🔔 Available Events

| Event | Description | Filters Available | |-------|-------------|-------------------| | Message Received | Trigger on new direct messages | Message type, From number | | Group Message Received | Trigger on new group messages | Message type, Group ID | | Status Changed | Trigger when connection status changes | - | | Call Received | Trigger on incoming calls | - | | Any Event | Trigger on any event | - |

🔍 Event Filters

Message Type Filter (for Message/Group Message events):

• Any, Text, Image, Video, Document, Audio, Location, Contact

From Number (for Message events):

• Filter messages from specific phone number

Group ID (for Group Message events):

• Filter messages from specific group

📋 Trigger Examples

Auto-responder:

Wasasa Trigger (Message Received)
  ↓
IF: message contains "hello"
  ↓
Wasasa: Send Text
  - Text: "Hi! How can I help?"

Group Bot:

Wasasa Trigger (Group Message)
  - Message Type: Text
  - Group ID: [email protected]
  ↓
IF: message contains "@bot"
  ↓
Wasasa: Send Text
  - Text: "Command received!"

Status Monitor:

Wasasa Trigger (Status Changed)
  ↓
IF: status === "disconnected"
  ↓
Email: Alert Admin

💼 Usage Examples

Example 1: Send a Welcome Message

Trigger: Webhook
  ↓
Wasasa: Send Text
  - Instance: my-bot
  - Number: 1234567890
  - Text: "Welcome to our service! 👋"

Example 2: Send Order Confirmation with Location

Shopify: New Order
  ↓
Wasasa: Send Text
  - Text: "Order confirmed! #{{$json.order_number}}"
  ↓
Wasasa: Send Location
  - Latitude: {{$json.shipping_address.latitude}}
  - Longitude: {{$json.shipping_address.longitude}}
  - Name: "Delivery Location"

Example 3: Daily Customer Survey

Cron: Daily at 9 AM
  ↓
Google Sheets: Get Customer List
  ↓
Loop: For Each Customer
  ↓
  Wasasa: Send Poll
    - Question: "How satisfied are you with our service?"
    - Options: ["Very Satisfied", "Satisfied", "Neutral", "Unsatisfied"]

Example 4: Automated Instance Management

Manual Trigger
  ↓
Wasasa: Create Instance
  - Name: "customer-{{$now.format('YYYY-MM-DD')}}"
  ↓
Wasasa: Get QR Code
  ↓
Wasasa: Update Settings
  - Reject Calls: true
  - Webhook URL: "https://my-app.com/webhook"
  ↓
Email: Send QR to Admin

Example 5: Send Contact Card

HTTP Request: Get Contact Info
  ↓
Wasasa: Send Contact
  - Display Name: "John Doe"
  - vCard: |
      BEGIN:VCARD
      VERSION:3.0
      FN:John Doe
      TEL:+1234567890
      EMAIL:[email protected]
      ORG:Acme Corp
      END:VCARD

Example 6: Status Monitoring

Cron: Every 5 minutes
  ↓
Wasasa: Get All Instances
  ↓
Loop: For Each Instance
  ↓
  Wasasa: Get Status
    ↓
    IF: Status !== "open"
      ↓
      Slack: Alert Admin
      - Message: "Instance {{$json.name}} is disconnected!"

🔗 API Compatibility

This node is compatible with Wasasa API servers that implement the following endpoints:

Instance Endpoints

• POST /instance/create
• GET /instance/fetchInstances
• GET /instance/:id
• DELETE /instance/delete/:id
• PUT /instance/update/:id
• GET /instance/connect/:id/image
• GET /instance/connectionState/:id
• DELETE /instance/logout/:id

Message Endpoints

• POST /instance/:id/message/text
• POST /instance/:id/message/image
• POST /instance/:id/message/video
• POST /instance/:id/message/document
• POST /instance/:id/message/audio
• POST /instance/:id/message/location
• POST /instance/:id/message/contact
• POST /instance/:id/message/poll

🛠️ Development

Prerequisites

• Node.js v20 or higher
• npm v9 or higher
• n8n installed (via @n8n/node-cli)

Setup

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

# Install dependencies
npm install

# Build the project
npm run build

# Start development server
npm run dev

The npm run dev command will:

1. Build your node with watch mode
2. Start n8n with your node loaded
3. Open n8n at http://localhost:5678

Project Structure

n8n-nodes-wasasa/
├── credentials/
│   └── WasasaApi.credentials.ts    # API credentials definition
├── nodes/
│   ├── Wasasa/
│   │   ├── Wasasa.node.ts          # Main node definition
│   │   ├── wasasa.svg              # Node icon
│   │   ├── resources/
│   │   │   ├── instance/
│   │   │   │   └── index.ts        # Instance operations
│   │   │   └── message/
│   │   │       └── index.ts        # Message operations
│   │   └── listSearch/
│   │       └── getInstances.ts     # Auto-complete logic
│   └── WasasaTrigger/
│       ├── WasasaTrigger.node.ts   # Trigger node definition
│       └── wasasa.svg              # Node icon
├── dist/                           # Compiled output
├── package.json
├── tsconfig.json
└── README.md

Scripts

| Command | Description | |---------|-------------| | npm run build | Compile TypeScript to JavaScript | | npm run build:watch | Build in watch mode | | npm run dev | Start n8n with node loaded | | npm run lint | Check code for errors | | npm run lint:fix | Auto-fix linting issues |

🔧 Troubleshooting

Node doesn't appear in n8n

1. Ensure the package is installed: npm list n8n-nodes-wasasa
2. Restart n8n completely
3. Check n8n logs for errors
4. Verify the node is listed in package.json under n8n.nodes

Connection test fails

1. Verify your API URL is correct and accessible
2. Check that your API key is valid
3. Ensure the Wasasa API server is running
4. Test the endpoint manually: curl -H "Authorization: Bearer YOUR_KEY" YOUR_URL/instance/fetchInstances

Instance dropdown is empty

1. Ensure you have created at least one instance
2. Check that the API key has permission to list instances
3. Verify the getInstances list search is working

Messages not sending

1. Verify the instance is connected (use Get Status)
2. Check the phone number format (no + or spaces)
3. Ensure media URLs are publicly accessible
4. Check Wasasa API logs for errors

📚 Resources

• n8n Community Nodes Documentation
• n8n Workflow Examples
• WhatsApp Business API Docs

📝 Version History

0.1.0 (Current)

Initial Release - Full-featured WhatsApp automation

Nodes (2):

• ✅ Wasasa (Main node)
• ✅ Wasasa Trigger (Event-driven workflows)

Instance Resource (8 operations):

• ✅ Create, Get, Get Many, Delete
• ✅ Get QR Code, Get Status, Logout
• ✅ Update Settings

Message Resource (8 operations):

• ✅ Send Text, Image, Video, Document
• ✅ Send Audio, Location, Contact, Poll

Trigger Events (5):

• ✅ Message Received
• ✅ Group Message Received
• ✅ Status Changed
• ✅ Call Received
• ✅ Any Event

Features:

• Auto-complete for instance selection
• Declarative routing for all operations
• Comprehensive field validation
• Professional error handling
• Webhook integration for triggers

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Use declarative routing when possible
• Add JSDoc comments for complex logic
• Test all operations thoroughly
• Update README for new features

📄 License

MIT

Copyright (c) 2024 Wasasa Team

🙏 Acknowledgments

• Built with n8n - Fair-code workflow automation
• Powered by Wasasa API - WhatsApp integration platform
• Inspired by the n8n community

Made with ❤️ for the n8n community

⭐ Star on GitHub | 📦 View on npm | 📖 Documentation