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: 123456@g.us
  ↓
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:john@example.com
      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

---